@softize/opus 8.6.6

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

@@ -0,0 +1,138 @@
+---
+title: Actions & contratos
+---
+
+# Actions & contratos
+
+A action é a unidade do Opus. O contrato (entidade + input/output + metadados) mora no package
+compartilhado; a API amarra o handler; a web renderiza a partir do mesmo contrato. Um shape,
+três consumidores.
+
+## Contrato primeiro
+
+> `defineContract` no `shared/` — entidades, schemas (zod + `t.*` pra tipos lógicos) e os
+> metadados da action. `api` e `web` importam; nada se duplica.
+
+```ts
+// shared/ — roda nos dois lados.
+import { defineContract } from '@softize/opus'
+import { t } from '@softize/opus/schema/zod'
+import { z } from 'zod'
+
+export const workspaceListContract = defineContract({
+  name: 'workspace.list',
+  kind: 'list',
+  summary: 'Lista os workspaces do back-office',
+  description: 'O workspace é a entidade raiz que agrupa repositórios, apps e agentes…',
+  input: z.object({ q: z.string().optional() }),
+  output: workspaceRowSchema,
+  paginate: 'cursor',
+})
+```
+
+## A action
+
+> `name = <resource>.<verb>`; `kind ∈ simple | form | list | view`; uma por arquivo em
+> `src/domains/<resource>/actions/`, registrada no runtime. Não registrada = não existe.
+
+```ts
+// api/ — server-only. bindAction amarra o handler no contrato compartilhado.
+import { bindAction } from '@softize/opus/core'
+import { workspaceCreateContract } from '@app/shared' // o mesmo contrato do bloco acima
+
+export const workspaceCreate = bindAction(workspaceCreateContract, {
+  handler: async (ctx, input) => {
+    const id = randomUUID()
+    await ctx.db.insertInto('workspaces').values({ id, name: input.name, /* … */ }).execute()
+    return { id }
+  },
+})
+```
+
+## Ordem canônica dos campos
+
+> O `opus check` reprova fora desta ordem — é a régua, 0 violação antes de entregar. A skill
+> `create-action` gera o esqueleto certo por construção.
+
+```text
+name → kind → (label / summary / messages / tags…)
+  → input → output
+  → (authorize)
+  → fields / paginate
+  → handler
+  → invalidates
+```
+
+Fail-closed por padrão: `input`/`output` via `z.object` + `t.*` pros tipos lógicos; `authorize`
+declarado ou gate explícito do adapter.
+
+Os átomos do catálogo servem TAMBÉM dentro dos schemas de input/output — não re-escreva
+regex do que o Opus já valida: `z.object({ tag: t.slug().zod(), contato: t.email().zod() })`.
+O `.zod()` devolve o schema zod subjacente do tipo lógico (slug, email, phone, money…).
+
+## Modo design — o mock mora no contrato
+
+Um `mockHandler` no contrato deixa a UI rodar com dado realista **sem backend nem banco**: em
+`OPUS_MODE=design` o runtime roteia o `execute` pro `mockHandler` (cai no `handler` real se
+ausente). Como ele fica no CONTRATO (não no `bindAction`), é isomorfo — o design autora, o
+handoff pluga o handler, e o mock nem toca `ctx.db`.
+
+Alimente com `fake`/`fakeMany` (fixtures determinísticas do próprio schema — ver [Testes](testing)):
+
+```ts
+import { fake, fakeMany } from '@softize/opus/testing'
+
+export const eventGet = defineContract({
+  name: 'event.get',
+  kind: 'view',
+  input: z.object({ id: z.string().uuid() }),
+  output: EventEntity.zod(),
+  mockHandler: () => fake(EventEntity.zod()), // 1 evento fake
+})
+// listas: `mockHandler: () => fakeMany(EventEntity.zod(), 20)`
+
+// o handoff, depois, só pluga o real — MESMO contrato:
+export const eventGetImpl = bindAction(eventGet, { handler: async (ctx, input) => { /* db */ } })
+```
+
+O `mockHandler` roda no **servidor em modo design** (`OPUS_MODE=design`), não no cliente — e
+quem sobe esse servidor é o próprio dev server: o plugin `opusDesign()` (`@softize/opus/vite`)
+monta o runtime Opus DENTRO do vite e serve `/api` in-process, com os mocks respondendo e
+qualquer `server.proxy` pra backend externo desligado (prefixo ex-proxy sem cobertura responde
+503 em envelope — nada vaza pra prod). A SPA chama `/api` normal e recebe o dado fake, isolado:
+
+```ts
+// vite.config.ts
+import { opusDesign } from '@softize/opus/vite'
+export default defineConfig({ plugins: [react(), opusDesign()] })
+// sobe com: vite --mode design
+```
+
+O `entry` (default `./opus.config.ts`) também aceita **glob** — `opusDesign({ entry:
+'src/domains/*/contract.ts' })` — re-expandido a cada rebuild: **domínio novo entra no ar ao
+salvar o arquivo**, sem editar entry nem reiniciar o dev server (criar o arquivo já invalida o
+runtime; o rebuild é lazy, na request seguinte). E o 404 de action desconhecida **se cura
+sozinho**: antes de responder, o plugin força um rebuild (um por ciclo de mudança) e re-tenta —
+persistindo, o envelope traz a mensagem-guia apontando o entry.
+
+Como o contrato é isomorfo, o `mockHandler` também acompanha o **bundle web** — peso morto lá
+(a SPA nunca o chama; o dado é fake). Tirá-lo do bundle de prod é um transform de build
+(deferido); **não** dá pra gatear no call-site com `import.meta.env` sem quebrar o servidor
+(não existe em Node). É a materialização Opus-nativa do "mock = contrato": o design não é
+descartável — vira o contrato que o backend honra.
+
+## O front consome o contrato
+
+> Nunca fetch ou tipos na mão. Os hooks e os patterns (ActionForm/ActionList…) renderizam a
+> action inteira a partir do contrato — o spec é a fonte, o pattern é o renderizador.
+
+```tsx
+import { useLookupAction } from '@softize/opus/client'
+import { ActionForm } from '@softize/opus/ui/react'
+
+// Lista paginada, tipada pelo contrato — zero shape duplicado.
+const { rows, fetchNextPage } = useLookupAction(workspaceListContract)
+
+// Form contract-driven: os campos (fields) moram NO contrato.
+<ActionForm contract={workspaceCreateContract} onSuccess={…} />
+```

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

@@ -0,0 +1,112 @@
+---
+title: IA generativa
+---
+
+# IA generativa
+
+> **Experimental.** Superfície mínima — cresce por reincidência de caso real, não por
+> especulação (streaming e memória longa de conversa entram quando um caso real cobrar).
+
+Três coisas: **completar** texto, **extrair** dado estruturado, e **rodar um agente** sobre
+as actions do app. O contrato é um adapter do core (`AiAdapter`). O diferencial do `extract`
+é que **o mesmo `Schema` das actions vira o contrato da resposta do modelo** — saída forçada
+e validada pelo schema. O do `run` é que **as actions viram as tools** — o modelo age no app,
+como o usuário, pelas mesmas actions que a UI usa.
+
+## O contrato
+
+```ts
+interface AiAdapter {
+  complete(prompt: string, opts?: AiCompleteOptions): Promise<string>
+  extract<T>(prompt: string, schema: Schema<T>, opts?: AiCompleteOptions): Promise<T>
+  // Loop agêntico: o modelo chama tools (as actions ai:enabled) até responder em texto.
+  run(input: string | AiMessage[], opts): Promise<AiRunResult>
+}
+// opts: { system?, model?, maxTokens?, temperature? } — tudo tem default do driver.
+```
+
+## Driver
+
+```ts
+import { anthropicAi } from '@softize/opus/ai/anthropic'
+
+// Default: haiku (rápido/barato) e ANTHROPIC_API_KEY do ambiente.
+const ai = anthropicAi()
+
+// Tudo injetável: client próprio, modelo default, teto de tokens.
+const custom = anthropicAi({ apiKey, model: 'claude-sonnet-5', maxTokens: 2048 })
+```
+
+O peer é **opcional** (`@anthropic-ai/sdk`): quem não usa o driver não o instala —
+importado sob demanda. Em teste, injete um client fake (`{ messages: { create } }`)
+e nada toca a rede.
+
+## No runtime
+
+```ts
+const runtime = createRuntime({
+  // …server/data/auth…
+  ai: anthropicAi(),
+})
+
+// No handler: ctx.ai (null quando não configurado).
+handler: async (ctx, input) => {
+  const meta = await ctx.ai!.extract(
+    `Classifique o chamado e proponha um título curto: ${input.texto}`,
+    z.object({ titulo: z.string(), prioridade: z.enum(['baixa', 'media', 'alta']) }),
+  )
+  return meta // já validado pelo schema — fora do contrato, o extract estoura.
+}
+```
+
+## Actions como tools (o agente)
+
+Marque uma action com `ai: { enabled: true }` no contrato e ela vira uma **tool** que o
+modelo pode chamar. Aí `ctx.ai.run(prompt)` roda o loop agêntico sobre as actions `ai:enabled`:
+o modelo escolhe a tool → o runtime executa a action **como o usuário logado** (limitado pelo
+`ctx.can`) → o resultado volta pro modelo → repete até a resposta em texto.
+
+```ts
+// A action opta por entrar — o contrato já tem o schema, que vira a tool spec de graça:
+export const buscarNotas = defineContract({
+  name: 'nota.buscar',
+  kind: 'list',
+  input: z.object({ cliente: z.string(), mes: z.string() }),
+  output: z.object({ total: z.number() }),
+  ai: { enabled: true, description: 'Busca notas por cliente e mês.' },
+})
+
+// No handler — ou fora dele, via runtime.aiFor(base), pro backend de um chat:
+const { text } = await ctx.ai!.run('Quantas notas a Empresa X emitiu em junho?')
+// o modelo chamou nota.buscar sozinho, como o usuário logado, e respondeu em texto.
+```
+
+O que é `destructive` ou pede `requiresConfirmation` **não roda sem aprovação**: passe
+`run(prompt, { confirm })` — o chat mostra o "confirmar?"; sem isso, a action é recusada e o
+modelo avisa. Fora do handler, `runtime.aiFor(base)` devolve o `ai` já ligado a um contexto —
+o backend do chat resolve o usuário e chama `.run(historico)`.
+
+## Streaming — o protocolo de eventos de conversa
+
+`runStream` é o mesmo loop agêntico do `run`, emitindo **`ChatEvent`** conforme acontece
+(o contrato: `docs/chat-event-protocol.md`): `text` (delta incremental), `tool` (a action
+em uso — dado cru; humanizar é da apresentação), `artifact` (algo produzido na conversa)
+e `done`. Aditivo: o `run` clássico permanece, e `Promise<string>` segue sendo o caso
+degenerado do protocolo (um `text` + um `done`).
+
+```ts
+// O backend de um chat streamando por SSE:
+for await (const event of runtime.aiFor(base)!.runStream(messages)) {
+  res.write(`data: ${JSON.stringify(event)}\n\n`)
+}
+```
+
+O driver Anthropic emite os deltas token a token quando o client suporta `messages.stream`;
+com um client só-`create` (ex.: fake de teste), o texto de cada passo sai como delta único.
+O `<Chat>` do opus/ui consome os dois modos — ver a página **Chat**.
+
+## Limites (por enquanto)
+
+O `run`/`runStream` fiam histórico multi-turn, mas sem memória longa/resumo automático.
+`extract` exige schema com objeto na raiz (`z.object`) — regra da API de tools do provider
+e o formato natural de um contrato.

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

@@ -0,0 +1,73 @@
+## Quase sempre é o `dialog`
+
+Pergunta de sim/não, um aviso a reconhecer, uma string — **não monte isto à mão**: o trio
+`dialog.confirm/alert/prompt` faz em uma linha, e o `body` cobre até corpo com conteúdo
+próprio (lista, detalhe). A demo viva mora na [página do dialog](/ui/confirm). Este
+componente é o **primitivo por baixo deles**.
+
+Então **componha o AlertDialog à mão só quando o trio não alcança**: mais de duas ações, ou
+um layout totalmente custom. É o que as seções abaixo mostram.
+
+## Mais de duas ações
+
+O caso que o `confirm` (binário) não expressa: três saídas. `AlertDialogTrigger` (asChild
+com Button) abre; cada `AlertDialogAction`/`AlertDialogCancel` é uma saída. Diferente do
+Dialog, **não fecha clicando fora** — exige uma escolha.
+
+```tsx preview
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="outline">Fechar editor</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Alterações não salvas</AlertDialogTitle>
+      <AlertDialogDescription>
+        Você editou o contrato e ainda não salvou. O que fazer antes de fechar?
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Continuar editando</AlertDialogCancel>
+      <AlertDialogAction variant="outline">Descartar</AlertDialogAction>
+      <AlertDialogAction>Salvar e fechar</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+## A estrutura e o botão destrutivo
+
+`AlertDialogHeader` (media/título/descrição) + `AlertDialogFooter` (as ações).
+`variant="destructive"` no `AlertDialogAction` (ele herda variant/size do Button) pinta o
+confirmar de vermelho. Uma confirmação destrutiva **binária** é só
+`dialog.confirm({ variant: 'destructive' })` — o exemplo abaixo é só pra mostrar a
+composição e onde o `variant` entra:
+
+```tsx preview
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="destructive">Excluir repositório</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Excluir empresa-x-api?</AlertDialogTitle>
+      <AlertDialogDescription>
+        O repositório sai do workspace e os agentes vinculados perdem o acesso ao código. Não dá pra desfazer.
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancelar</AlertDialogCancel>
+      <AlertDialogAction variant="destructive">Excluir</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `open` (AlertDialog) | `boolean` | | Estado de aberto no modo controlado — pareie com onOpenChange. No padrão, o Trigger cuida disso. |
+| `onOpenChange` (AlertDialog) | `(open: boolean) => void` | | Chamado quando o diálogo abre ou fecha (Trigger, Cancel, Action ou Esc). |
+| `variant` (AlertDialogAction) | `'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'` | `'default'` | Intenção do botão de confirmar (herdada do Button) — destructive pra ação perigosa. |
+| `variant` (AlertDialogCancel) | `'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'` | `'outline'` | Intenção do botão de cancelar (herdada do Button). |

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

@@ -0,0 +1,69 @@
+## Forma curta
+
+Quase todo alert é ícone + título + uma frase — então isso é UMA linha: `title`, `description` e `icon` como props. O componente monta os slots e a a11y (`role="alert"`, que faz o leitor de tela anunciar sozinho).
+
+```tsx preview col
+<Alert icon={<Info />} title="Opus 2.8.0" description="Este workspace usa a versão pinada em opus.json." />
+<Alert
+  variant="destructive"
+  icon={<CircleAlert />}
+  title="Sessão encerrada"
+  description="O agente parou antes de concluir. Veja o detalhe no log da sessão."
+/>
+<Alert
+  variant="success"
+  icon={<CircleCheck />}
+  title="Skill publicada"
+  description="Os agentes do workspace já enxergam a nova versão."
+/>
+```
+
+## Só a frase
+
+Título é opcional — o aviso de uma linha dispensa. `destructive` e `success` mantêm superfície tonalizada + borda (divergência da casa: o shadcn rebaixou destructive pra `bg-card`, nós preservamos o realce).
+
+```tsx preview col
+<Alert description="Nenhuma sessão aberta neste repositório." />
+<Alert variant="success" icon={<CircleCheck />} description="Workspace Empresa X sincronizado." />
+```
+
+## Ícone é opcional
+
+Sem `icon` o alert é bloco comum; com ele, vira grid de duas colunas e o conteúdo se alinha ao lado. Texto solto como filho também vale (`<Alert>Sincronizado.</Alert>`) — cai no slot de descrição sozinho.
+
+```tsx preview col
+<Alert title="Sem provider próprio" description="As conversas usam o padrão do sistema." />
+<Alert variant="success">Workspace Empresa X sincronizado.</Alert>
+```
+
+## Composição (conteúdo rico)
+
+Quando a descrição tem mais que uma frase — parágrafos, lista, um botão — componha: `AlertTitle` e `AlertDescription` seguem exportados, e o espaço entre BLOCOS filhos vem de graça.
+
+```tsx preview col
+<Alert variant="destructive" icon={<CircleAlert />}>
+  <AlertTitle>Não deu pra publicar</AlertTitle>
+  <AlertDescription>
+    <p>O registry recusou a versão 3.0.0 — ela já existe.</p>
+    <p>Suba o patch e tente de novo.</p>
+  </AlertDescription>
+</Alert>
+```
+
+Os dois modos convivem: com `title`/`description` preenchidos, `children` entra DEPOIS da frase — é onde vai a ação.
+
+```tsx preview col
+<Alert icon={<CircleAlert />} title="Sessão presa" description="O ambiente não subiu no tempo esperado.">
+  <Button size="sm" variant="outline">Reiniciar</Button>
+</Alert>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `title` | `React.ReactNode` | | Título do alert (a forma curta). Não é o atributo `title` do HTML — esse é tooltip nativo, banido na casa, e o componente não o aceita. |
+| `description` | `React.ReactNode` | | A frase. Sozinha, dispensa título. |
+| `icon` | `React.ReactNode` | | Ícone à esquerda; é ele que liga o layout de duas colunas. Decorativo — quem nomeia é o título. |
+| `variant` | `'default' \| 'destructive' \| 'success'` | `'default'` | O tom da mensagem. |
+| `children` | `React.ReactNode` | | Composição (`AlertTitle`/`AlertDescription`), texto cru, ou — junto da forma curta — o que vem depois da frase. |

package/src/ui/docs/content/app-shell.md

@@ -0,0 +1,155 @@
+## Chrome da aplicação
+
+O esqueleto que todo app da casa repete: sidebar de navegação à esquerda (header, nav rolável, rodapé ancorado) e o conteúdo. É o quadro — o que vai em cada slot (a marca, o seletor de contexto, o nav do app) é do consumidor. Pro esqueleto de *uma página* (título, descrição, ação), use o `Page` dentro do conteúdo.
+
+```tsx preview col
+render(
+  <div className="w-full overflow-hidden rounded-lg border border-border">
+    <AppShell
+      className="h-96"
+      sidebarHeader={<div className="px-2.5 py-2 text-sm font-semibold">◆ Acme</div>}
+      sidebarNav={
+        <nav className="space-y-1 pt-2">
+          {['Clientes', 'Workspaces', 'Agentes'].map((item, index) => (
+            <button
+              key={item}
+              type="button"
+              className={
+                'flex w-full items-center rounded-md px-2.5 py-1.5 text-left text-sm transition-colors hover:bg-muted/60 ' +
+                (index === 0 ? 'bg-muted' : 'text-foreground/80')
+              }
+            >
+              {item}
+            </button>
+          ))}
+        </nav>
+      }
+      sidebarFooter={<div className="px-2.5 py-2 text-xs text-muted-foreground">ana@acme.com</div>}
+    >
+      <div className="m-4 flex-1 rounded-lg border border-dashed border-border p-10 text-center text-sm text-muted-foreground">
+        O conteúdo (em geral um Page).
+      </div>
+    </AppShell>
+  </div>,
+)
+```
+
+## Recolher a sidebar
+
+`collapsible` é **opt-in** — sem ele o shell é o de sempre. O shell controla a **largura** e publica o estado; **o que some é decisão do conteúdo**, porque o `sidebarNav` é seu. Em vez de te obrigar a gerenciar estado, o aside expõe `data-collapsed` e o grupo `sidebar`: o rótulo some por CSS.
+
+```
+<span className="group-data-[collapsed=true]/sidebar:hidden">Clientes</span>
+```
+
+O botão é o `<AppShellTrigger />`, que **você** posiciona (numa `AppShellBar`, no header do conteúdo…) — ele some sozinho quando o shell não é `collapsible`, então não precisa de condicional. Pra ler o estado em JS, `useAppShell()`. Pra persistir a preferência, controle de fora com `collapsed` + `onCollapsedChange`; `sidebarCollapsedClassName` ajusta a largura recolhida (default `w-14`).
+
+Se você passa a própria largura em `sidebarClassName`, ela vale no **expandido**: no recolhido quem vence é a largura do recolhido — recolher é estado, não estilo default, e o contrário deixaria o aside meio-recolhido (rótulo some, largura fica).
+
+```tsx preview col
+render(
+  <div className="w-full overflow-hidden rounded-lg border border-border">
+    <AppShell
+      collapsible
+      className="h-96"
+      sidebarHeader={
+        <div className="flex h-12 items-center gap-2 border-b border-border px-2.5">
+          <AppShellTrigger />
+          <span className="text-sm font-semibold group-data-[collapsed=true]/sidebar:hidden">◆ Acme</span>
+        </div>
+      }
+      sidebarNav={
+        <nav className="space-y-1 pt-2">
+          {[
+            { label: 'Clientes', icon: '👤' },
+            { label: 'Workspaces', icon: '▦' },
+            { label: 'Agentes', icon: '✦' },
+          ].map((item, index) => (
+            <button
+              key={item.label}
+              type="button"
+              title={item.label}
+              className={
+                'flex w-full items-center gap-2.5 rounded-md px-2.5 py-1.5 text-left text-sm transition-colors hover:bg-muted/60 ' +
+                (index === 0 ? 'bg-muted' : 'text-foreground/80')
+              }
+            >
+              <span className="shrink-0">{item.icon}</span>
+              <span className="truncate group-data-[collapsed=true]/sidebar:hidden">{item.label}</span>
+            </button>
+          ))}
+        </nav>
+      }
+    >
+      <div className="m-4 flex-1 rounded-lg border border-dashed border-border p-10 text-center text-sm text-muted-foreground">
+        Clique no botão da sidebar pra recolher.
+      </div>
+    </AppShell>
+  </div>,
+)
+```
+
+## Com rail à direita
+
+`rail` liga o terceiro painel — o lugar do chat de agente ou de um inspetor. Conteúdo e rail viram painéis redimensionáveis (arraste a divisória); `mainDefaultSize`/`mainMinSize`/`railMinSize` (em %) calibram a partilha.
+
+```tsx preview col
+render(
+  <div className="w-full overflow-hidden rounded-lg border border-border">
+    <AppShell
+      className="h-96"
+      sidebarHeader={<div className="px-2.5 py-2 text-sm font-semibold">◆ Acme</div>}
+      sidebarNav={
+        <nav className="space-y-1 pt-2">
+          <button type="button" className="flex w-full items-center rounded-md bg-muted px-2.5 py-1.5 text-left text-sm">
+            Painel comercial
+          </button>
+        </nav>
+      }
+      rail={
+        <div className="flex h-full flex-col border-l bg-background">
+          <div className="border-b px-3 py-2 text-xs text-muted-foreground">Conversa</div>
+          <div className="flex-1 p-3 text-sm text-muted-foreground">O chat do agente vive aqui.</div>
+        </div>
+      }
+    >
+      <div className="m-4 flex-1 rounded-lg border border-dashed border-border p-10 text-center text-sm text-muted-foreground">
+        O conteúdo (preview, tabela, página).
+      </div>
+    </AppShell>
+  </div>,
+)
+```
+
+O shell não impõe fundo nem borda aos slots — ele é TRANSPARENTE: o canvas (cinza clarinho) vem do `body` (theme.css) e a sidebar o herda; um rail tipicamente traz `border-l bg-background`, como acima.
+
+## Chrome flush (linha de header contínua)
+
+`flush` tira o inset: a sidebar perde o padding do shell e o conteúdo vira full-bleed
+apartado por um filete à esquerda — o shell NÃO pinta fundo (o canvas do body aparece);
+superfície branca é decisão do conteúdo (`bg-background` no seu contêiner). Combine com `AppShellBar` — a faixa h-12 com `border-b` —
+uma na sidebar (a marca) e outra no topo do conteúdo (breadcrumb/ações): as alturas
+casam e a linha do header atravessa a tela inteira.
+
+```tsx preview col lg
+render(
+  <AppShell
+    className="h-96 rounded-lg border"
+    flush
+    sidebarHeader={
+      <AppShellBar>
+        <span className="grid h-6 w-6 place-items-center rounded-md bg-primary/10 text-sm text-primary">◆</span>
+        <span className="text-sm font-semibold tracking-tight">Grupo Vetra</span>
+      </AppShellBar>
+    }
+    sidebarNav={<nav className="p-2 text-sm text-muted-foreground">Relatórios…</nav>}
+  >
+    <AppShellBar>
+      <span className="text-muted-foreground">Vetra BI</span>
+      <span className="text-muted-foreground/40">›</span>
+      <span className="text-sm font-medium">Painel comercial</span>
+    </AppShellBar>
+    <div className="p-4 text-sm text-muted-foreground">Conteúdo full-bleed.</div>
+  </AppShell>,
+)
+```

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

@@ -0,0 +1,66 @@
+## Padrão (16/9)
+
+O `ratio` é a proporção entre largura e altura — 16/9 é o padrão de vídeo. Defina a largura no
+contêiner (o pai): a altura o componente deriva sozinho.
+
+```tsx preview col
+<div className="w-full max-w-md">
+  <AspectRatio ratio={16 / 9} className="overflow-hidden rounded-lg border bg-muted">
+    <div className="flex h-full w-full items-center justify-center text-sm text-muted-foreground">
+      Preview do worktree — Empresa X
+    </div>
+  </AspectRatio>
+</div>
+```
+
+## Quadrado (1/1)
+
+ratio={1} trava num quadrado — o formato dos avatares de agente e dos ícones de skill, onde a
+moldura precisa ser previsível.
+
+```tsx preview col-start
+<div className="w-40">
+  <AspectRatio ratio={1} className="overflow-hidden rounded-lg border bg-muted">
+    <div className="flex h-full w-full items-center justify-center text-sm font-medium text-muted-foreground">
+      developer
+    </div>
+  </AspectRatio>
+</div>
+```
+
+## Galeria de previews
+
+Mesmo ratio em vários cards: as molduras alinham antes mesmo do conteúdo chegar — sem o pulo de
+layout quando o preview carrega.
+
+```tsx preview col
+<div className="grid w-full grid-cols-3 gap-3">
+  {[
+    { ref: 'empresa-x-api', branch: 'feat/preview-pipeline' },
+    { ref: 'empresa-x-web', branch: 'fix/handoff-modal' },
+    { ref: 'empresa-x-infra', branch: 'chore/caddy-bump' },
+  ].map((session) => (
+    <AspectRatio
+      key={session.ref}
+      ratio={16 / 9}
+      className="overflow-hidden rounded-lg border bg-muted"
+    >
+      <div className="flex h-full w-full flex-col justify-end gap-1 p-2">
+        <span className="text-sm font-medium">{session.ref}</span>
+        <span className="flex items-center gap-1 text-xs text-muted-foreground">
+          <GitBranch className="size-3" />
+          {session.branch}
+        </span>
+      </div>
+    </AspectRatio>
+  ))}
+</div>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `ratio` | `number` | `1` | A razão largura/altura. 16/9 pra vídeo/preview, 1 pra quadrado, 4/3 pra clássico. |
+| `children` | `React.ReactNode` | | O conteúdo a enquadrar (img, iframe, div) — preencha com h-full w-full e object-cover. |
+| `className` | `string` | | Estilo do bloco — borda, rounded e overflow-hidden moram aqui, não no filho. |