@softize/opus 8.6.6

package/src/ui/docs/content/getting-started.md

@@ -0,0 +1,109 @@
+---
+title: Getting started
+---
+
+# Getting started
+
+O Opus é um SDK/protocolo spec-driven: o domínio **É** a aplicação (contratos +
+actions); front e back são cascas. Um projeto Opus-based pina o Opus, herda o runtime e segue os gates.
+
+## O modelo
+
+> Antes de qualquer arquivo: por que o Opus existe e o que ele assume.
+
+A aplicação é o **domínio** — entidades, dicts e contratos de action. A API e a web são cascas
+que consomem esse domínio: zero shape duplicado. O Opus entrega o núcleo (runtime, adapters, UI,
+CLI) e os gates que mantêm o padrão. O que cada projeto adiciona é o seu domínio; o resto vem pinado.
+
+## Começar do zero
+
+> Projeto novo não se monta à mão: o esqueleto canônico sai do `opus create`, com os
+> pré-requisitos do protocolo, da UI e do preview já plugados — e os gates verdes.
+
+O Opus mora no registry da Softize (não no npm público) — uma vez por máquina, ensine
+o escopo ao pnpm; dentro do projeto criado o `.npmrc` já cuida disso:
+
+```bash
+pnpm config set @softize:registry https://registry.softize.com.br/ --global  # 1x por máquina
+
+pnpm dlx @softize/opus create meu-app
+cd meu-app && git init && pnpm install && pnpm test
+```
+
+Máquina nova: se o pnpm reclamar que o diretório global de binários não está no PATH
+(o `dlx` exige), rode `pnpm setup` e reabra o terminal — também é 1x por máquina. Se o
+setup acusar seção pnpm antiga no shell rc (`ERR_PNPM_BAD_SHELL_SECTION`), é resquício
+de versão anterior: `pnpm setup --force` substitui só o bloco dele.
+
+Release recém-saída (menos de 24h): a quarentena do pnpm resolve o `dlx` pra versão
+ANTIGA em silêncio ("Comando desconhecido" = sintoma clássico). Fure com a versão
+explícita — `pnpm dlx @softize/opus@<versão> create meu-app` — ou com a flag
+`pnpm --config.minimum-release-age=0 dlx …`. Dentro de projeto o pnpm se resolve
+sozinho (auto-exclui o Opus da quarentena no install).
+
+Nasce com: `opus.config.ts` + domínio-exemplo canônico (0 violações, spec documentada),
+vite + react + tema do Opus (Tailwind v4 CSS-first), dev server na porta que o Maestro
+injeta no preview, `opus.json` (pin), `CLAUDE.md` (bloco gerenciado), `.claude/memory/`
+e o CI de fábrica.
+
+**Monorepo:** a raiz nasce do `--monorepo` e cada app nasce dentro dela — o create
+detecta o `pnpm-workspace.yaml` e gera só o que é do app (nada de `.npmrc`/workspace
+yaml aninhado), **avisando** o que a raiz precisa ter (glob de packages, escopo do
+registry, allowBuilds) sem tocar nos seus arquivos:
+
+```bash
+pnpm dlx @softize/opus create meu-cliente --monorepo   # a raiz do workspace
+cd meu-cliente && git init
+pnpm dlx @softize/opus create apps/portal              # o app (modo detectado)
+```
+
+## Carregar o Opus num projeto existente
+
+> O pin vive no `opus.json`; o setup grava o esqueleto local. Ausência de `opus.json` = projeto
+> não inicializado — não improvise, rode o setup.
+
+A versão do Opus fica pinada em `opus.json`. O `opus setup` é per-app: grava o `opus.json`,
+mantém o bloco gerenciado do `CLAUDE.md` (fora dele o arquivo é seu) e semeia o dia zero
+(`.claude/memory/`, CI) se faltarem. Os componentes e hooks vêm do barrel
+`@softize/opus/ui/react`; o tema, por CSS.
+
+```bash
+# Bootstrap per-app (idempotente): pin + bloco do CLAUDE.md + dia zero.
+npx @softize/opus setup
+
+# index.css do app — o tema canônico + os componentes do Opus no scan do Tailwind.
+@import '@softize/opus/ui/theme.css';
+@source '../node_modules/@softize/opus/src/ui/**/*.{ts,tsx}';
+```
+
+## A stack do runtime
+
+> `createRuntime` compõe a stack a partir de adapters plugáveis. Cada capacidade (data, auth,
+> audit…) é um adapter — troca a implementação sem tocar o domínio.
+
+```ts
+import { createRuntime } from '@softize/opus/core'
+import { kyselyData } from '@softize/opus/data/kysely'
+import { fastifyServer } from '@softize/opus/server/fastify'
+import { pgAudit } from '@softize/opus/audit/pg'
+
+const runtime = createRuntime({
+  server: fastifyServer({ app }),
+  data: kyselyData({ db }),       // Kysely + Postgres
+  auth: makeAuthAdapter(),        // gate (IdP)
+  audit: [pgAudit({ pool })],     // trilha de auditoria
+  config: { env, i18n: { defaultLocale: 'pt-BR' } },
+})
+
+// Domínios = grupos de actions. Não registrado = não existe.
+runtime.register([workspacesDomain, agentsDomain, skillsDomain])
+await runtime.start()
+```
+
+## Antes de mexer
+
+> O protocolo de leitura: a verdade local mora nos docs do repo, não nesta página.
+
+- `CLAUDE.md` do repo e do app — o índice local: mapa, gates, gotchas.
+- As `description` das entidades/actions — a spec de negócio, projetada no manifest pelo `opus gen`.
+- Gate de build: `opus check` (convenções das actions) + `opus db check` (drift entidade ↔ banco). Rode antes de entregar.

package/src/ui/docs/content/icon-picker.md

@@ -0,0 +1,51 @@
+O value é o **nome** do ícone (kebab-case, chave da paleta) — quem consome renderiza com a mesma paleta: `iconPickerIcons[name] ?? FallbackIcon`. Selecionar o já-escolhido desmarca (volta a `''`).
+
+## Básico
+
+```tsx preview col md
+const [icon, setIcon] = useState('chart-line')
+
+render(
+  <div className="grid gap-2">
+    <Label htmlFor="report-icon">Ícone do relatório</Label>
+    <IconPicker id="report-icon" value={icon} onChange={setIcon} />
+  </div>,
+)
+```
+
+## Renderizando o escolhido
+
+A paleta default é exportada (`iconPickerIcons`) — use-a pra desenhar o ícone salvo onde ele aparece (item de lista, card, árvore).
+
+```tsx preview col md
+const [icon, setIcon] = useState('store')
+const Icon = iconPickerIcons[icon] ?? FileText
+
+render(
+  <div className="flex items-center gap-3">
+    <IconPicker value={icon} onChange={setIcon} className="w-56" />
+    <span className="flex items-center gap-2 rounded-md border px-3 py-2 text-sm">
+      <Icon className="size-4 text-muted-foreground" />
+      Painel comercial
+    </span>
+  </div>,
+)
+```
+
+## Paleta própria
+
+`icons` troca o vocabulário (nome → componente lucide). A paleta default é curta de propósito — cada ícone importado entra no bundle; monte a sua com o que faz sentido no domínio.
+
+```tsx preview col md
+const [icon, setIcon] = useState('')
+
+render(
+  <IconPicker
+    value={icon}
+    onChange={setIcon}
+    icons={{ 'zap': Zap, 'star': Star, 'flag': Flag, 'heart': Heart }}
+    placeholder="Selecione um ícone…"
+    className="w-56"
+  />,
+)
+```

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

@@ -0,0 +1,78 @@
+> Só um **ícone leading**? Não precisa do InputGroup — é a prop `icon` do `Input` (a mesma do Select e do Alert). O InputGroup é pros casos que a prop não cobre: botão no fim, prefixo de texto, adorno em bloco, múltiplos.
+
+## Com ícone (addon)
+
+InputGroupAddon na borda (align inline-start por padrão) cola um ícone ao InputGroupInput dentro da mesma moldura. Clicar no addon foca o campo. Pra um leading simples, prefira `<Input icon={…} />`; aqui é quando o ícone convive com outros adornos.
+
+```tsx preview col
+<InputGroup>
+  <InputGroupAddon>
+    <Search />
+  </InputGroupAddon>
+  <InputGroupInput placeholder="Buscar sessões do workspace" />
+</InputGroup>
+```
+
+## Ícone + ação juntos (o caso do InputGroup)
+
+> Só uma ação no fim (um limpar, um mostrar-senha)? Isso é `<Input trailing={…} />` — não precisa do InputGroup. O InputGroup entra quando os adornos se ACUMULAM: aqui, um ícone leading E um botão no fim, na mesma moldura (a busca do `ActionList` é assim). `align=inline-end` joga o addon pro fim; `InputGroupButton` já vem ghost, tamanho `icon-xs`.
+
+```tsx preview col
+<InputGroup>
+  <InputGroupAddon>
+    <Search />
+  </InputGroupAddon>
+  <InputGroupInput placeholder="Buscar agente" defaultValue="reviewer" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupButton size="icon-xs" aria-label="Limpar filtro">
+      <X />
+    </InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+## Prefixo e sufixo
+
+InputGroupText é o rótulo inerte na borda — prefixo ou sufixo. Aqui emoldura o slug do repositório entre o host fixo e o sufixo .git.
+
+```tsx preview col
+<InputGroup>
+  <InputGroupAddon>
+    <GitBranch />
+    <InputGroupText>github.com/softize/</InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput placeholder="empresa-x-api" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupText>.git</InputGroupText>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+## Composer com rodapé
+
+Com InputGroupTextarea a moldura cresce; align=block-end empilha um rodapé de ações embaixo do campo — o padrão do composer de brief do agente.
+
+```tsx preview col
+<InputGroup>
+  <InputGroupTextarea placeholder="Descreva a task para o agente developer" rows={3} />
+  <InputGroupAddon align="block-end">
+    <InputGroupText>
+      <Sparkles />
+      Título gerado pela IA
+    </InputGroupText>
+    <InputGroupButton size="sm" variant="default" className="ml-auto" aria-label="Enviar brief">
+      Enviar
+      <ArrowUp />
+    </InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `align` (InputGroupAddon) | `'inline-start' \| 'inline-end' \| 'block-start' \| 'block-end'` | `'inline-start'` | Onde o addon ancora: inline nas laterais; block empilha (vira coluna) acima ou abaixo — block exige a moldura alta de um InputGroupTextarea. |
+| `size` (InputGroupButton) | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'` | `'xs'` | Tamanho do botão embutido. As variantes icon-* são quadradas, pra um botão só de ícone. |
+| `variant` (InputGroupButton) | `'default' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive' \| 'link'` | `'ghost'` | Intenção do botão (herda do Button). O padrão ghost some na moldura; use default pra a ação primária. |
+| `placeholder / defaultValue / value` (InputGroupInput, InputGroupTextarea) | `string` | | Props nativas do <input>/<textarea> repassadas ao controle. Controle como faria com Input/Textarea (value + onChange). |

package/src/ui/docs/content/input-otp.md

@@ -0,0 +1,72 @@
+## Básico
+
+maxLength define quantas casas existem; cada InputOTPSlot recebe o index da sua posição. Um InputOTPGroup envolve as casas.
+
+```tsx preview
+<InputOTP maxLength={6}>
+  <InputOTPGroup>
+    <InputOTPSlot index={0} />
+    <InputOTPSlot index={1} />
+    <InputOTPSlot index={2} />
+    <InputOTPSlot index={3} />
+    <InputOTPSlot index={4} />
+    <InputOTPSlot index={5} />
+  </InputOTPGroup>
+</InputOTP>
+```
+
+## Com separador
+
+Vários grupos com InputOTPSeparator entre eles quebram o código em blocos — os index seguem contínuos (0–5) por cima da divisão visual.
+
+```tsx preview
+<InputOTP maxLength={6}>
+  <InputOTPGroup>
+    <InputOTPSlot index={0} />
+    <InputOTPSlot index={1} />
+    <InputOTPSlot index={2} />
+  </InputOTPGroup>
+  <InputOTPSeparator />
+  <InputOTPGroup>
+    <InputOTPSlot index={3} />
+    <InputOTPSlot index={4} />
+    <InputOTPSlot index={5} />
+  </InputOTPGroup>
+</InputOTP>
+```
+
+## Controlado
+
+value + onChange deixam o código no seu estado — bom pra liberar a ação só quando todas as casas estão preenchidas.
+
+```tsx preview col-start
+const [code, setCode] = useState('')
+
+render(
+  <>
+    <InputOTP maxLength={6} value={code} onChange={setCode}>
+      <InputOTPGroup>
+        <InputOTPSlot index={0} />
+        <InputOTPSlot index={1} />
+        <InputOTPSlot index={2} />
+        <InputOTPSlot index={3} />
+        <InputOTPSlot index={4} />
+        <InputOTPSlot index={5} />
+      </InputOTPGroup>
+    </InputOTP>
+    <p className="text-sm text-muted-foreground">
+      {code.length === 6 ? 'Código pronto pra confirmar o acesso ao workspace.' : 'Digite o código de 6 dígitos.'}
+    </p>
+  </>,
+)
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `maxLength` (InputOTP) | `number` | | Quantas casas o código tem — defina um InputOTPSlot por posição. |
+| `value` (InputOTP) | `string` | | O código no modo controlado — parear com onChange. |
+| `onChange` (InputOTP) | `(value: string) => void` | | Chamado a cada dígito; recebe o código acumulado. |
+| `disabled` (InputOTP) | `boolean` | `false` | Esmaece e bloqueia a digitação do conjunto inteiro. |
+| `index` (InputOTPSlot) | `number` | | A posição da casa (0-based); liga o slot ao dígito correspondente. |

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

@@ -0,0 +1,78 @@
+## Básico
+
+Placeholder orienta o formato, não substitui o rótulo — em formulário de verdade, pareie com Label.
+
+```tsx preview col md
+<Input placeholder="Ex.: empresa-x" />
+```
+
+## Ícone dentro do campo
+
+`icon` põe um ícone LEADING dentro do campo — identidade (calendário na data, prédio na filial). É a MESMA prop do Select e do Alert: adorno de campo é **prop**, não composição à mão nem ícone jogado ao lado (que desalinha na quebra de linha e some no responsivo). Decorativo — quem nomeia é o Label.
+
+```tsx preview col md
+<div className="grid gap-2">
+  <Label htmlFor="filial">Filial</Label>
+  <Input id="filial" icon={<Building2 />} placeholder="Ex.: Matriz" />
+</div>
+```
+
+Pra mais que um ícone — um botão no fim, um prefixo de texto, adorno em bloco — aí é `InputGroup` (a composição rica). Só o ícone leading é a prop.
+
+
+## Ação no fim do campo (trailing)
+
+`trailing` é o par do `icon`: uma ação DENTRO do campo, no fim — um botão que age sobre o valor (limpar, mostrar senha). Igual ao Select. Diferente do ícone (decorativo), o trailing é interativo.
+
+```tsx preview col md
+function Demo() {
+  const [q, setQ] = useState('preview pipeline')
+  return (
+    <Input
+      icon={<Search />}
+      value={q}
+      onChange={(e) => setQ(e.target.value)}
+      trailing={
+        q ? (
+          <Button variant="ghost" size="icon-xs" onClick={() => setQ('')}>
+            <X />
+          </Button>
+        ) : undefined
+      }
+    />
+  )
+}
+render(<Demo />)
+```
+
+Pra MAIS de um adorno junto (ícone + botão + prefixo de texto), aí é `InputGroup`. Um ícone e/ou uma ação → props.
+
+## Com Label
+
+htmlFor aponta pro id do campo — clicar no rótulo foca o input.
+
+```tsx preview col md
+<div className="grid gap-2">
+  <Label htmlFor="client-name">Nome do cliente</Label>
+  <Input id="client-name" defaultValue="Empresa X" />
+</div>
+```
+
+## Tipos nativos
+
+type é o atributo nativo de <input> — teclado, máscara e validação vêm do browser de graça.
+
+```tsx preview col md
+<Input type="email" placeholder="Ex.: joao@softize.com.br" />
+<Input type="password" placeholder="Token de serviço" />
+<Input type="number" placeholder="Porta do dev server" />
+```
+
+## Estados
+
+Inválido é aria-invalid (borda e anel destructive) — semântica e visual na mesma prop, sem classe de erro à parte. disabled esmaece e bloqueia.
+
+```tsx preview col md
+<Input aria-invalid defaultValue="empresa x" placeholder="Slug do workspace" />
+<Input disabled defaultValue="softize-multica" />
+```

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

@@ -0,0 +1,84 @@
+## Básico
+
+A composição completa: ItemMedia à esquerda, ItemContent (ItemTitle + ItemDescription) ocupando o meio e ItemActions à direita. variant=outline desenha a borda.
+
+```tsx preview col
+<Item variant="outline">
+  <ItemMedia variant="icon">
+    <FolderGit2 />
+  </ItemMedia>
+  <ItemContent>
+    <ItemTitle>empresa-x-api</ItemTitle>
+    <ItemDescription>Repositório do backend do workspace Empresa X.</ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Button size="sm" variant="outline">Abrir</Button>
+  </ItemActions>
+</Item>
+```
+
+## Lista
+
+Empilhe vários Item num ItemGroup e separe com ItemSeparator — o padrão pra listas de repositórios, agentes ou sessões.
+
+```tsx preview col
+<ItemGroup>
+  <Item>
+    <ItemMedia variant="icon">
+      <GitBranch />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>empresa-x-web</ItemTitle>
+      <ItemDescription>Front do workspace Empresa X.</ItemDescription>
+    </ItemContent>
+    <ItemActions>
+      <Badge variant="success">sincronizado</Badge>
+    </ItemActions>
+  </Item>
+  <ItemSeparator />
+  <Item>
+    <ItemMedia variant="icon">
+      <GitBranch />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>empresa-x-api</ItemTitle>
+      <ItemDescription>Backend do workspace Empresa X.</ItemDescription>
+    </ItemContent>
+    <ItemActions>
+      <Badge variant="warning">3 sessões</Badge>
+    </ItemActions>
+  </Item>
+</ItemGroup>
+```
+
+## Clicável e compacto
+
+asChild funde o Item num <a> — a linha inteira vira alvo (hover no fundo). size=sm aperta o respiro; ItemMedia variant=image ancora um avatar.
+
+```tsx preview col
+<Item asChild size="sm" variant="outline">
+  <a href="#empresa-x">
+    <ItemMedia>
+      <Avatar>
+        <AvatarFallback>AL</AvatarFallback>
+      </Avatar>
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>Empresa X</ItemTitle>
+      <ItemDescription>Workspace com 2 repositórios e 3 agentes.</ItemDescription>
+    </ItemContent>
+    <ItemActions>
+      <ChevronRight className="size-4 text-muted-foreground" />
+    </ItemActions>
+  </a>
+</Item>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `variant` (Item) | `'default' \| 'outline' \| 'muted'` | `'default'` | O fundo da linha — default transparente, outline com borda, muted levemente tingido. |
+| `size` (Item) | `'default' \| 'sm'` | `'default'` | O respiro interno — sm aperta o padding pra listas densas. |
+| `asChild` (Item) | `boolean` | `false` | Funde o Item no filho (ex.: <a> ou <button>) — a linha inteira vira o alvo. |
+| `variant` (ItemMedia) | `'default' \| 'icon' \| 'image'` | `'default'` | A moldura da mídia — icon dá caixa quadrada com borda; image recorta a imagem; default sem moldura. |

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

@@ -0,0 +1,62 @@
+## Básico
+
+Uma tecla por Kbd. É só visual — quem escuta o atalho é o seu handler, não o componente.
+
+```tsx preview
+<Kbd>Esc</Kbd>
+```
+
+## Combinação
+
+Envolva as teclas num KbdGroup e ponha o conector (+) como texto entre elas — o padrão pra paleta de comandos do Maestro.
+
+```tsx preview
+<KbdGroup>
+  <Kbd>⌘</Kbd>
+  <span className="text-xs text-muted-foreground">+</span>
+  <Kbd>K</Kbd>
+</KbdGroup>
+```
+
+## Com ícone
+
+Um ícone (lucide) como filho do Kbd ganha size-3 automático — bom pra ⌘ e Enter, onde o glifo lê melhor que a letra.
+
+```tsx preview col-start
+<KbdGroup>
+  <Kbd>
+    <Command />
+  </Kbd>
+  <Kbd>
+    <CornerDownLeft />
+  </Kbd>
+</KbdGroup>
+```
+
+## No tooltip
+
+Dentro de um TooltipContent o Kbd inverte o tom sozinho (fundo claro sobre o balão escuro) — anuncie o atalho da ação ao passar o mouse.
+
+```tsx preview
+<Tooltip>
+  <TooltipTrigger className="text-sm text-muted-foreground underline underline-offset-4">
+    Abrir paleta de comandos
+  </TooltipTrigger>
+  <TooltipContent className="flex items-center gap-2">
+    Buscar workspace
+    <KbdGroup>
+      <Kbd>⌘</Kbd>
+      <Kbd>K</Kbd>
+    </KbdGroup>
+  </TooltipContent>
+</Tooltip>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `children (Kbd)` | `React.ReactNode` | | A tecla — texto (Esc, ⌘, K) ou um ícone lucide, que recebe size-3 automático. |
+| `className (Kbd)` | `string` | | Classes extras na tecla, mescladas com cn — pra ajustar tamanho ou cor pontualmente. |
+| `children (KbdGroup)` | `React.ReactNode` | | As teclas do combo, mais o conector (ex.: "+") como texto entre elas. |
+| `className (KbdGroup)` | `string` | | Classes extras no agrupador (inline-flex + gap-1), mescladas com cn. |

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

@@ -0,0 +1,32 @@
+## Com campo de texto
+
+htmlFor aponta pro id do controle — clicar no rótulo foca o campo.
+
+```tsx preview col md
+<div className="grid gap-2">
+  <Label htmlFor="workspace-name">Nome do workspace</Label>
+  <Input id="workspace-name" placeholder="Ex.: empresa-x" />
+</div>
+```
+
+## Com Checkbox
+
+O Label já é flex com gap — controle inline entra sem wrapper extra; clicar no texto alterna a caixa.
+
+```tsx preview
+<div className="flex items-center gap-2">
+  <Checkbox id="notify-reviewer" defaultChecked />
+  <Label htmlFor="notify-reviewer">Avisar o revisor ao abrir o handoff</Label>
+</div>
+```
+
+## Par desabilitado
+
+Controle disabled esmaece o rótulo junto (peer-disabled) — o par inteiro comunica o estado, sem classe manual.
+
+```tsx preview
+<div className="flex items-center gap-2">
+  <Checkbox id="archive-workspace" disabled />
+  <Label htmlFor="archive-workspace">Arquivar o workspace</Label>
+</div>
+```

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

@@ -0,0 +1,55 @@
+---
+title: Log
+---
+
+# Log
+
+Log estruturado que chega no handler já com contexto (per-request, per-action) via
+`ctx.log`. O contrato é o `LoggerAdapter` — a mesma interface `Logger` que o core usa por
+dentro, então o seu log e o do runtime saem no mesmo lugar, no mesmo formato.
+
+## O contrato
+
+```ts
+interface Logger {
+  trace(msg: string, meta?: object): void
+  debug(msg: string, meta?: object): void
+  info(msg: string, meta?: object): void
+  warn(msg: string, meta?: object): void
+  error(msg: string, meta?: object): void
+  fatal(msg: string, meta?: object): void
+  child(bindings: object): Logger   // logger derivado com bindings fixos
+}
+```
+
+## Driver
+
+```ts
+import pino from 'pino'
+import { pinoLogger } from '@softize/opus/log/pino'
+
+const logger = pinoLogger({ logger: pino({ level: 'info' }) })
+```
+
+O `pino` é seu (nível, transport, redact) — o driver só faz a ponte. Peer opcional: quem
+não usa o driver não instala o `pino`.
+
+## No runtime
+
+```ts
+const runtime = createRuntime({
+  // …server/data…
+  logger,
+})
+
+// No handler: ctx.log já vem com o requestId/action injetados (via child()).
+handler: async (ctx, input) => {
+  ctx.log.info('emitindo nota', { valor: input.valor })
+  return repo.create(input)
+}
+```
+
+## Limites (por enquanto)
+
+Superfície mínima de níveis + `child`. Sem sampling nem transports próprios — isso mora no
+`pino` que você passa. Drivers hoje: `pino`; outros entram por reincidência.

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

@@ -0,0 +1,41 @@
+## Fonte e resultado
+
+Uso: <Markdown content={fonte} />. No palco, o resultado; no bloco abaixo, a fonte markdown que o produziu. O componente recebe só content: string.
+
+```tsx preview col 2xl
+const sample = [
+  '# Markdown na Softize',
+  '',
+  'Renderiza **doc técnica** e mensagem de chat — `SKILL.md`, síntese de papel, resposta de agente.',
+  'O motor é o markdown-it, o MESMO que renderiza estas páginas.',
+  '',
+  '## Sintaxe coberta',
+  '',
+  '- Headings de `#` a `####`',
+  '- Listas com `-` ou numeradas',
+  '- **Negrito**, código inline e [links](https://softize.com.br)',
+  '',
+  '1. Primeiro passo',
+  '2. Segundo passo',
+  '',
+  '> Citação calma, pro tom certo.',
+  '',
+  '---',
+  '',
+  '```ts',
+  'function ola(): string {',
+  "  return 'mundo'",
+  '}',
+  '```',
+].join('\n')
+
+render(<Markdown content={sample} />)
+```
+
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `content` | `string` | | O markdown cru (CommonMark + tabela GFM, via markdown-it). HTML no fonte é **escapado**, não interpretado — por isso serve pra texto vindo de gente ou de modelo. |
+| `className` | `string` | | Classes do wrapper. |