@softize/opus 8.6.6

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

@@ -0,0 +1,110 @@
+---
+title: Customização
+---
+
+# Customização
+
+Cinco alavancas, do global ao pontual — e um limite de propósito. O caminho previsto é compor
+e configurar, nunca forkar componente: o que não cabe nas alavancas evolui no Opus (com
+divergência declarada), pra valer pra casa toda.
+
+## 1 · Identidade por tokens
+
+> O jeito canônico de vestir a marca. Sobrescreva as vars no `:root` depois de importar o
+> `theme.css` — todos os componentes acompanham, sem forkar nada. Dark incluso (a classe `.dark`
+> re-declara as vars).
+
+```css
+/* index.css do app — depois do import do tema. */
+@import '@softize/opus/ui/theme.css';
+
+:root {
+  --primary: hsl(262 83% 58%); /* A cor da marca do projeto. */
+  --ring: hsl(262 83% 58%);
+  --radius: 0.5rem;            /* Cantos mais retos, se for a praia do projeto. */
+}
+```
+
+## 2 · className em tudo
+
+> Todo componente termina em `cn(base, className)` com tailwind-merge: o utilitário do consumidor
+> vence o conflito. Pra layout local (largura, margem, grid) — não pra repintar o visual da casa.
+
+```tsx
+<Button className="w-full">Salvar</Button>
+<Card className="max-w-sm" />
+<DialogContent className="sm:max-w-2xl" />
+```
+
+## 3 · Recomposição estrutural
+
+> Os componentes são explodidos em slots. `asChild` (Radix Slot) renderiza como outro elemento
+> mantendo estilo e comportamento; os `*Variants` aplicam a cara da casa num elemento arbitrário.
+
+```tsx preview
+<Button asChild variant="outline">
+  <a href="#" onClick={(e) => e.preventDefault()}>Âncora com cara de botão</a>
+</Button>
+```
+
+```tsx
+// Slots: só o que a tela pede.
+<Card>
+  <CardHeader><CardTitle>Workspace</CardTitle></CardHeader>
+  <CardContent>…</CardContent>
+</Card>
+
+// asChild: o filho VIRA o botão (sem forkar estilo).
+<Button asChild><a href="/docs">Abrir documentação</a></Button>
+
+// buttonVariants: a cara da casa num elemento qualquer.
+<a className={buttonVariants({ variant: 'outline' })}>Link estilizado</a>
+```
+
+## 4 · Comportamento por props
+
+> Modo controlado em tudo que abre ou seleciona (`open`/`onOpenChange`, `value`/`onValueChange`),
+> posicionamento (`align`/`side`/`sideOffset`), `showCloseButton`, `delayDuration`… A orquestração
+> é do implementador; o visual continua o da casa.
+
+```tsx
+const [open, setOpen] = useState(false)
+
+<Dialog open={open} onOpenChange={setOpen}>…</Dialog>
+<DialogContent showCloseButton={false} />     {/* modal que exige ação */}
+<PopoverContent align="start" sideOffset={8} />
+<TooltipProvider delayDuration={200}>…
+```
+
+## 5 · Nos patterns, o contrato é a customização
+
+> Os patterns (ActionForm/Search/View/Trigger): o spec dirige. `fields`/`widget`/`showWhen`/
+> `fieldOptions` no form, `columns` no search, render prop no view. O caminho previsto é a feature
+> EMBRULHAR o pattern — nunca forkar.
+
+```tsx
+// O form NASCE do contrato; a tela só ajusta o que é seu.
+<ActionForm
+  action={workspaceCreateContract}
+  fieldOptions={{ skillIds: skillsDoWorkspace }}
+  onSuccess={(d) => navigate(`/workspaces/${d.id}`)}
+/>
+
+// O search recebe as colunas; a célula é render livre.
+<ActionList action={listAction} input={{ q }} columns={[
+  { key: 'name', header: 'Workspace', cell: (w) => w.name },
+]} />
+```
+
+## O limite — de propósito
+
+> O look curado não é customizável no app: rodapé-faixa do dialog, elevação no dark, `active:scale`
+> do botão, a seta do tooltip — é identidade da casa, igual em todo projeto.
+
+```tsx preview
+<Badge variant="success">Cabe nas alavancas</Badge>
+```
+
+Se uma necessidade real não cabe nas alavancas (tokens · className · slots/asChild · props ·
+contrato), o movimento não é dialeto local: é evoluir o componente **no Opus**, com a divergência
+declarada (skill `opus`) — assim a mudança vale pra casa toda, e esta doc passa a mostrá-la.

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

@@ -0,0 +1,34 @@
+# Evolução contínua
+
+O Opus cresce por **reincidência, nunca por especulação**. Quando o mesmo comportamento genérico reaparece em mais de um projeto, ele vira candidato a peça do Opus — e o projeto troca a implementação local pelo import. Estilo e conveniência não entram; comportamento que se repete, sim.
+
+## Onde você aponta
+
+No seu projeto, uma linha por apontamento em `.opus/issues.jsonl` na raiz do repo. Dois tipos:
+
+- **`enhancement`** — código genérico que o Opus deveria ganhar (serviria a qualquer projeto). Antes de apontar, confira o que o Opus já tem (o inventário de componentes, os exports, esta doc): se já existe, use.
+- **`bug`** — um defeito ou limitação no próprio Opus, achado usando-o.
+
+```json
+{"type": "enhancement", "behavior": "o comportamento em uma frase.", "file": "src/onde-vive.ts", "kind": "ui|sdk|driver|infra"}
+{"type": "bug", "behavior": "o que quebra ou falta.", "file": "onde se manifesta.", "note": "repro + o workaround aplicado."}
+```
+
+## Não trave esperando
+
+O ponto do ciclo é **não bloquear a entrega**. Bateu num gap ou num bug do Opus:
+
+1. **Contorne local** — componha um wrapper no seu projeto. O Opus entrega _source_, então dá pra embrulhar qualquer superfície dele. Nunca edite `node_modules` (some no próximo install).
+2. **Entregue** a feature com o workaround.
+3. **Aponte** no `.opus/issues.jsonl` e siga em frente.
+
+O "depois" — o conserto no Opus — corre em paralelo. Ele não segura o seu trabalho; o único custo de demorar é o workaround viver um pouco mais.
+
+## Como fecha
+
+O apontamento é colhido e abre uma **Issue no repositório do Opus**, onde a triagem acontece (deduplicada — re-apontar o mesmo é idempotente):
+
+- **Enhancement** aceito (com reincidência) → implementado no Opus → sai num _bump_ → seu projeto atualiza o pin (`opus.json`) e troca o workaround pelo import.
+- **Bug** → vira _fix_ + entrada no `CHANGELOG` → no _bump_, o workaround sai.
+
+A régua e a decisão ficam com quem mantém o Opus — hoje, a **Softize**. O registro curado das promoções vive no `PROMOTED.md` do pacote.

package/src/ui/docs/content/data-state.md

@@ -0,0 +1,47 @@
+## Estados
+
+Um lugar só pro erro/carregando/vazio/conteúdo de uma carga. Carregando = Spinner centralizado;
+vazio = texto; erro = aviso calmo (a mensagem técnica não vai pra tela). É o "antes" do conteúdo —
+pro "depois" (ação em andamento), use o busy do Button.
+
+```tsx preview col
+<div className="w-full space-y-3">
+  <DataState loading>
+    <div />
+  </DataState>
+  <DataState empty emptyText="Nenhum papel.">
+    <div />
+  </DataState>
+  <DataState error={{ message: 'detalhe técnico fica no console' }}>
+    <div />
+  </DataState>
+</div>
+```
+
+## Em tabela (colSpan)
+
+Em lista de tabela, passe colSpan: o estado vira UMA linha de largura cheia (`<tr><td colSpan>`)
+que cabe direto no `<tbody>`; o conteúdo são as `<tr>` dos itens.
+
+```tsx preview col
+<table className="w-full overflow-hidden rounded-lg border border-border text-sm">
+  <tbody>
+    <DataState empty emptyText="Nenhum usuário." colSpan={3}>
+      <tr>
+        <td />
+      </tr>
+    </DataState>
+  </tbody>
+</table>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `loading` | `boolean` | | Carregando (antes do conteúdo) — mostra o Spinner centralizado. |
+| `empty` | `boolean` | | Sem itens — mostra o emptyText. |
+| `emptyText` | `string` | | Texto do vazio (pt-BR, ex.: "Nenhum papel."). |
+| `error` | `{ message?: string } \| null` | | Erro da carga — aviso calmo. A mensagem técnica NÃO vai pra tela (use errorText). |
+| `errorText` | `string` | `'Não foi possível carregar.'` | Aviso de erro, orientado ao usuário. |
+| `colSpan` | `number` | | Em tabela: renderiza o estado como `<tr><td colSpan>` (cabe direto no tbody). |

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

@@ -0,0 +1,99 @@
+---
+title: Camada de dados
+---
+
+# Camada de dados
+
+A entidade é a spec do armazenamento; o manifest a projeta. As queries falam Kysely tipado.
+Uma regra firme atravessa tudo: o código fala camelCase, o banco fala snake — e o
+`CamelCasePlugin` faz a ponte.
+
+## Entidade e manifest
+
+> `defineEntity` declara o storage (campos + tipos lógicos `t.*`). A `description` de cada
+> entidade/action é a spec de negócio, projetada no manifest pelo `opus gen`; `opus db check`
+> acusa drift entidade ↔ banco.
+
+```ts
+import { defineEntity } from '@softize/opus/schema'
+import { t } from '@softize/opus/schema/zod'
+
+export const SkillEntity = defineEntity({
+  name: 'skill',
+  fields: {
+    id: t.uuid().pk(),
+    slug: t.slug(),
+    name: t.string(),
+    content: t.text(),
+    createdAt: t.datetime(),
+  },
+})
+```
+
+## Código camelCase, banco snake
+
+> Regra dura (skill `code-style`): uma camada em snake e outra em camel é defeito — não tem meio-termo.
+
+O schema tipado do Kysely e **toda** query (select/insert/update/where) usam camelCase
+(`workspaceId`, `ghRepo`). O banco é snake (a DDL no schema idempotente — `db/schema.sql`).
+O `CamelCasePlugin` no runtime faz a ponte camel↔snake nas queries E nos resultados — o
+mesmo que o prepare já faz.
+Única exceção: um sink escrito por fora do Kysely-com-plugin (ex.: o `audit_log` do Opus, pelo
+pool) fica snake.
+
+```ts
+import { CamelCasePlugin, Kysely, PostgresDialect } from 'kysely'
+
+const db = new Kysely<AdminDB>({
+  dialect: new PostgresDialect({ pool }),
+  plugins: [new CamelCasePlugin()], // camel no código → snake no SQL → camel no resultado
+})
+
+await db.selectFrom('agents').select(['isDefault', 'roleId']).where('workspaceId', '=', id).execute()
+```
+
+## Migrações · prepare · seed
+
+> Três coisas distintas — não confundir o que roda em prod.
+
+- `opus db migrate` — aplica o **schema idempotente** (`config.schema`, um script SQL
+  evolutivo: `IF NOT EXISTS` + guards cobrem nascer do zero e upgrade no mesmo artefato)
+  e roda o drift-check entidade ↔ banco na sequência (exit ≠ 0 se divergir).
+- `prepare` — backfill estrutural, prod-safe e idempotente; roda no deploy (depois do migrate).
+- `seed` — fixtures de desenvolvimento. **Não** roda em prod.
+
+## Campo `t.json()`: objeto entra, objeto sai
+
+> A dupla `ColumnType<unknown, string, never>` + `JSON.stringify` na mão está aposentada
+> no caminho do `kyselyRepo`.
+
+O `kyselyRepo` serializa campo `t.json()` na ESCRITA (insert/update), guiado pela
+declaração. Sem isso, o pg até stringifica objeto plano — mas **array vira literal de
+array do PG** (errado pra jsonb) sem quebrar typecheck. String passa direto (quem já
+mandava pré-serializado segue valendo); na leitura o pg devolve objeto. Query à mão
+(fora do repo) continua responsável pelo próprio stringify.
+
+## SQL escrito por LLM: `readOnlyContextPool`
+
+> Action `ai: true` que executa SQL livre precisa das **quatro defesas** — todas no
+> BANCO, nenhuma em regex sobre o texto da query.
+
+```ts
+import { Pool } from 'pg'
+import { readOnlyContextPool } from '@softize/opus/data/readonly-pool'
+
+const bi = readOnlyContextPool({ pool: new Pool({ connectionString, max: 4 }) })
+const { rows } = await bi.query(sqlDoLlm, { role: roleFor(ctx) })
+```
+
+1. **Pool com teto** (`max` do pool e/ou `maxConcurrent`) — query de LLM não esgota as
+   conexões do app;
+2. **`BEGIN TRANSACTION READ ONLY`** — escrita morre no servidor;
+3. **`SET LOCAL ROLE` por transação** — o alcance é do CONTEXTO (crie os roles com grants
+   default-fechado nas suas migrações: sem isso, `sales_read` leria `hr_employees`);
+4. **Protocolo estendido** — o SQL roda sempre com array de valores; multi-sentença
+   (`SELECT 1; DROP …`) é recusada pelo próprio protocolo.
+
+Saindo, `DISCARD ALL` devolve a conexão limpa; se a limpeza falhar, a conexão é
+destruída — nunca volta suja pro pool. `statement_timeout` local por transação
+(default 15s) segura a query fugitiva.

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

@@ -0,0 +1,60 @@
+## Composição
+
+Content é superfície pura; o espaço mora nos slots (body p-5; header/footer px-5 py-4): DialogHeader (fixo, com divisor), DialogBody (rola) e DialogFooter (faixa da casa — borda + fundo muted). DialogClose fecha sem estado manual.
+
+```tsx preview
+<Dialog>
+  <DialogTrigger asChild>
+    <Button variant="outline">Novo workspace</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Novo workspace</DialogTitle>
+      <DialogDescription>O workspace agrupa os repositórios e agentes do cliente.</DialogDescription>
+    </DialogHeader>
+    <DialogBody className="space-y-2">
+      <Label htmlFor="ws-nome">Nome</Label>
+      <Input id="ws-nome" placeholder="Ex.: Empresa X" />
+    </DialogBody>
+    <DialogFooter>
+      <DialogClose asChild>
+        <Button variant="outline" size="sm">Cancelar</Button>
+      </DialogClose>
+      <Button size="sm">Criar</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+## Sem o X (ação obrigatória)
+
+showCloseButton={false} esconde o X: o usuário decide pelos botões — pra confirmação que não pode ser dispensada no escuro.
+
+```tsx preview
+<Dialog>
+  <DialogTrigger asChild>
+    <Button variant="destructive">Excluir sessão</Button>
+  </DialogTrigger>
+  <DialogContent showCloseButton={false}>
+    <DialogHeader>
+      <DialogTitle>Excluir a sessão?</DialogTitle>
+      <DialogDescription>O worktree e o preview desta sessão serão removidos.</DialogDescription>
+    </DialogHeader>
+    <DialogFooter>
+      <DialogClose asChild>
+        <Button variant="outline" size="sm">Cancelar</Button>
+      </DialogClose>
+      <DialogClose asChild>
+        <Button variant="destructive" size="sm">Excluir</Button>
+      </DialogClose>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `Dialog.open / onOpenChange` | `boolean / (open: boolean) => void` | | Modo controlado (Radix) — pra abrir por código (ex.: depois de uma action). |
+| `DialogContent.showCloseButton` | `boolean` | `true` | Mostra o X de fechar no canto. Desligue pra modal que exige ação explícita. |

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

@@ -0,0 +1,55 @@
+## Painel de detalhe (à direita)
+
+O painel que desliza de uma borda da tela — modal, com overlay, trap de foco e ESC (o motor é o Dialog do Radix). A régua contra o irmão: conteúdo curto e CENTRADO → `Dialog`; painel na borda que preserva o contexto atrás → `Drawer`.
+
+side='right' desliza da borda direita. ESC, clique no overlay e o X fecham — sem estado manual. É o lugar de detalhe/edição lateral sem sair do contexto.
+
+```tsx preview
+<Drawer>
+  <DrawerTrigger asChild>
+    <Button variant="outline">Ver detalhe</Button>
+  </DrawerTrigger>
+  <DrawerContent side="right">
+    <DrawerHeader>
+      <DrawerTitle>criarTicket</DrawerTitle>
+      <DrawerDescription>Ação · domínio Suporte</DrawerDescription>
+    </DrawerHeader>
+    <div className="px-4 text-sm text-muted-foreground">Campos, entrada/saída, arquivo…</div>
+  </DrawerContent>
+</Drawer>
+```
+
+## Edição com rodapé (à esquerda)
+
+side aceita top|right|bottom|left. DrawerFooter ancora as ações no rodapé; DrawerClose fecha sem estado manual.
+
+```tsx preview
+<Drawer>
+  <DrawerTrigger asChild>
+    <Button variant="outline">Editar</Button>
+  </DrawerTrigger>
+  <DrawerContent side="left">
+    <DrawerHeader>
+      <DrawerTitle>Editar workspace</DrawerTitle>
+    </DrawerHeader>
+    <div className="space-y-2 px-4">
+      <Label htmlFor="ws-nome">Nome</Label>
+      <Input id="ws-nome" defaultValue="Empresa X" />
+    </div>
+    <DrawerFooter>
+      <DrawerClose asChild>
+        <Button variant="outline" size="sm">Cancelar</Button>
+      </DrawerClose>
+      <Button size="sm">Salvar</Button>
+    </DrawerFooter>
+  </DrawerContent>
+</Drawer>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `DrawerContent.side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | Borda de onde o painel desliza. |
+| `DrawerContent.showCloseButton` | `boolean` | `true` | Mostra o X de fechar no canto. Desligue pra painel que exige ação explícita. |
+| `Drawer.open / onOpenChange` | `boolean / (open: boolean) => void` | | Modo controlado (Radix) — pra abrir/fechar por código (ex.: detalhe de um item selecionado). |

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

@@ -0,0 +1,66 @@
+## Com ícone
+
+EmptyMedia variant=icon desenha o quadrado de fundo muted atrás do ícone; o EmptyHeader agrupa mídia, título e descrição no centro.
+
+```tsx preview col
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <FolderGit2 />
+    </EmptyMedia>
+    <EmptyTitle>Nenhum repositório vinculado</EmptyTitle>
+    <EmptyDescription>
+      O workspace Empresa X ainda não tem repositórios. Vincule um pra abrir sessões.
+    </EmptyDescription>
+  </EmptyHeader>
+</Empty>
+```
+
+## Com ação
+
+EmptyContent guarda os botões abaixo do header — é o lugar da chamada pra ação que resolve o vazio.
+
+```tsx preview col
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <Sparkles />
+    </EmptyMedia>
+    <EmptyTitle>Sem skills neste agente</EmptyTitle>
+    <EmptyDescription>
+      O agente developer não tem skills anexadas. Adicione clean-code ou test pra começar.
+    </EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent>
+    <Button>
+      <Plus />
+      Anexar skill
+    </Button>
+  </EmptyContent>
+</Empty>
+```
+
+## Mídia default
+
+EmptyMedia variant=default (o padrão) não desenha fundo — bom pra uma ilustração ou um ícone maior que se sustenta sozinho.
+
+```tsx preview col
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia className="text-muted-foreground">
+      <FolderGit2 className="size-12" />
+    </EmptyMedia>
+    <EmptyTitle>Nenhuma sessão por aqui</EmptyTitle>
+    <EmptyDescription>
+      Este repositório ainda não teve sessões. A primeira aparece assim que um agente começar a trabalhar.
+    </EmptyDescription>
+  </EmptyHeader>
+</Empty>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `variant (EmptyMedia)` | `'default' \| 'icon'` | `'default'` | icon desenha o quadrado de fundo muted atrás da mídia; default não desenha fundo. |
+| `className (Empty)` | `string` | | A moldura já vem tracejada e centrada — ajuste espaçamento ou borda por aqui. |

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

@@ -0,0 +1,61 @@
+---
+title: Eventos
+---
+
+# Eventos
+
+O handler anuncia que algo aconteceu (`ctx.emit`) sem saber quem escuta. Reactions (e
+integrações) assinam e reagem. O barramento é um adapter do core (`EventBusAdapter`); o
+formato do evento é preservado de ponta a ponta.
+
+## O contrato
+
+```ts
+interface EventBusAdapter {
+  publish(event: DomainEvent): Promise<void> | void
+  subscribe?(pattern: string, listener: (event: DomainEvent) => void): Unsubscribe
+}
+
+interface DomainEvent<T = unknown> {
+  type: string                                   // 'nota.emitida'
+  id: string
+  timestamp: string
+  actor: { id: string | null; type?: 'user' | 'system' | 'integration' }
+  tenant?: string | null
+  data: T
+  source: { action: string; actionId: string; correlation?: string }
+}
+```
+
+## Driver
+
+```ts
+import { mittEvents } from '@softize/opus/events/mitt'
+
+const bus = mittEvents()   // in-process (mesmo processo do runtime)
+```
+
+## No runtime
+
+```ts
+const runtime = createRuntime({
+  // …server/data…
+  eventBus: bus,
+})
+
+// No handler: emite pelo tipo declarado; o core preenche id/timestamp/actor/source.
+handler: async (ctx, input) => {
+  const nota = await repo.create(input)
+  ctx.emit('nota.emitida', { id: nota.id, valor: nota.valor })
+  return nota
+}
+```
+
+Actions declaram no contrato o que emitem (`emits: ['nota.emitida']`); o runtime avisa se
+o handler emitir algo não-declarado (`emitMode`). Uma reaction assina `nota.emitida` e roda
+como sua própria action rastreável (provenance `reaction`).
+
+## Limites (por enquanto)
+
+O driver `mitt` é in-process — sem durabilidade nem entre-processos. Barramentos duráveis/
+distribuídos (Redis, NATS…) entram por reincidência de caso real.

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

@@ -0,0 +1,58 @@
+## Campo vertical
+
+A composição base: FieldLabel (htmlFor↔id), o controle e FieldDescription como ajuda — empilhados, com o respiro do Field.
+
+```tsx preview col md
+<Field>
+  <FieldLabel htmlFor="workspace-slug">Slug do workspace</FieldLabel>
+  <Input id="workspace-slug" defaultValue="empresa-x" />
+  <FieldDescription>Vira o subdomínio do preview: empresa-x.preview.softize.com.br.</FieldDescription>
+</Field>
+```
+
+## Horizontal com toggle
+
+orientation=horizontal põe o controle na lateral e a label à esquerda. FieldContent agrupa título e descrição num bloco; FieldTitle é o rótulo de texto quando o controle não é um <label>.
+
+```tsx preview col md
+<Field orientation="horizontal">
+  <FieldContent>
+    <FieldTitle>Acionar o revisor no handoff</FieldTitle>
+    <FieldDescription>Ao abrir o handoff, o agente reviewer entra na sessão automaticamente.</FieldDescription>
+  </FieldContent>
+  <Switch id="auto-review" defaultChecked />
+</Field>
+```
+
+## Conjunto com legenda e erro
+
+FieldSet agrupa campos sob uma FieldLegend; FieldGroup dá o espaçamento entre eles; FieldSeparator marca uma divisão. FieldError mostra a mensagem só quando há erro (aria-invalid no controle casa o visual).
+
+```tsx preview col md
+<FieldSet>
+  <FieldLegend>Novo agente</FieldLegend>
+  <FieldGroup>
+    <Field>
+      <FieldLabel htmlFor="agent-name">Nome</FieldLabel>
+      <Input id="agent-name" defaultValue="" aria-invalid placeholder="Ex.: developer" />
+      <FieldError>Informe um nome pro agente.</FieldError>
+    </Field>
+    <FieldSeparator />
+    <Field>
+      <FieldLabel htmlFor="agent-prompt">Prompt</FieldLabel>
+      <Textarea id="agent-prompt" rows={3} defaultValue="Veste o papel de developer no workspace Empresa X." />
+      <FieldDescription>A síntese vira a primeira mensagem da sessão.</FieldDescription>
+    </Field>
+  </FieldGroup>
+</FieldSet>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `orientation` (Field) | `'vertical' \| 'horizontal' \| 'responsive'` | `'vertical'` | Direção do campo: vertical empilha; horizontal põe o controle ao lado (bom pra toggle); responsive vira horizontal a partir de @md. |
+| `variant` (FieldLegend) | `'legend' \| 'label'` | `'legend'` | Tamanho da legenda do FieldSet — legend é o título da seção; label encolhe pro porte de rótulo. |
+| `errors` (FieldError) | `Array<{ message?: string }>` | | Lista de erros (ex.: do react-hook-form) — deduplica e vira uma lista. Sem children e sem erros, o FieldError não renderiza. |
+| `children` (FieldError) | `React.ReactNode` | | Mensagem de erro literal — tem prioridade sobre errors quando passada. |
+| `children` (FieldSeparator) | `React.ReactNode` | | Rótulo opcional no meio da linha divisória (ex.: "ou") — sem filhos, é só a linha. |