@softize/opus 8.6.6

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

@@ -0,0 +1,171 @@
+---
+title: Tokens & Tema
+---
+
+# Tokens & Tema
+
+O tema canônico vive no Opus (`theme.css`): tokens com a cor inteira na var, mapeados pro
+Tailwind via `@theme inline`. Os swatches abaixo leem as vars **ao vivo** — troque o tema do app
+e a página acompanha.
+
+## Superfícies e intenções
+
+> Cada token de superfície tem o seu par de texto (`-foreground`). Use o par, nunca uma cor solta.
+
+```tsx preview
+const SURFACES = [
+  ['background', 'foreground', 'O fundo da página e o texto padrão.'],
+  ['card', 'card-foreground', 'Superfície elevada (Card, painéis).'],
+  ['popover', 'popover-foreground', 'Superfície flutuante (menus, popovers, dialogs).'],
+  ['muted', 'muted-foreground', 'Fundo discreto e texto secundário.'],
+  ['accent', 'accent-foreground', 'Hover e seleção.'],
+  ['secondary', 'secondary-foreground', 'Ação secundária.'],
+  ['primary', 'primary-foreground', 'A ação principal — alto contraste.'],
+  ['destructive', 'destructive-foreground', 'Ação destrutiva e erro.'],
+]
+render(
+  <div className="w-full overflow-hidden rounded-lg border border-border">
+    {SURFACES.map(([token, fg, desc]) => (
+      <div key={token} className="flex items-center gap-4 border-b border-border px-4 py-3 last:border-b-0">
+        <div
+          className="flex h-10 w-28 shrink-0 items-center justify-center rounded-md border border-border text-xs font-medium"
+          style={{ backgroundColor: `var(--${token})`, color: `var(--${fg})` }}
+        >
+          Texto
+        </div>
+        <div className="min-w-0">
+          <div className="font-mono text-xs">--{token} · --{fg}</div>
+          <div className="text-xs text-muted-foreground">{desc}</div>
+        </div>
+      </div>
+    ))}
+  </div>,
+)
+```
+
+## Linhas e foco
+
+> Bordas e o anel de foco também são tokens — nada de cinza hardcoded. A aresta de superfície
+> elevada (`--edge`) mora na seção Elevação por papel.
+
+```tsx preview
+const LINES = [
+  ['border', 'Bordas de contêineres (cards, tabelas, separadores).'],
+  ['input', 'Borda de campos de formulário.'],
+  ['ring', 'O anel de foco (focus-visible).'],
+]
+render(
+  <div className="w-full overflow-hidden rounded-lg border border-border">
+    {LINES.map(([token, desc]) => (
+      <div key={token} className="flex items-center gap-4 border-b border-border px-4 py-3 last:border-b-0">
+        <div className="h-10 w-28 shrink-0 rounded-md border-2" style={{ borderColor: `var(--${token})` }} />
+        <div className="min-w-0">
+          <div className="font-mono text-xs">--{token}</div>
+          <div className="text-xs text-muted-foreground">{desc}</div>
+        </div>
+      </div>
+    ))}
+  </div>,
+)
+```
+
+## Elevação por papel
+
+> A sombra segue o mesmo desenho das cores: token por PAPEL, não por tamanho — o papel de
+> superfície carrega cor, elevação e forma (`bg-card` · `shadow-card` · `rounded-card`). Em superfície elevada, a aresta é o anel hairline `ring-1 ring-edge`
+> no lugar da borda (nunca os dois juntos); borda sólida fica onde é affordance de interação
+> (inputs, controles — que são flat). Os defaults `shadow-*` do Tailwind seguem intactos: um
+> `shadow-md` cru no código é sinal de review, não vocabulário da casa.
+
+```tsx preview
+const ROLES = [
+  ['card', 'Conteúdo em repouso (Card, composer do Chat).'],
+  ['popover', 'Flutuante leve (menus, selects, popovers).'],
+  ['dialog', 'Flutuante modal (dialogs, sheets).'],
+]
+render(
+  <div className="flex flex-wrap gap-8 py-4">
+    {ROLES.map(([role, desc]) => (
+      <div key={role} className="flex flex-col items-center gap-3">
+        <div
+          className={'flex h-24 w-40 items-center justify-center bg-card text-xs ring-1 ring-edge rounded-' + role + ' shadow-' + role}
+        >
+          Texto
+        </div>
+        <div className="text-center">
+          <div className="font-mono text-xs">shadow-{role}</div>
+          <div className="max-w-44 text-xs text-muted-foreground">{desc}</div>
+        </div>
+      </div>
+    ))}
+  </div>,
+)
+```
+
+## Densidade
+
+> A base é 15px: o `html` da casa fixa o rem, e TODA a escala (texto, spacing, radius) deriva
+> dele — a UI densifica ~6% vs o default do browser (16px). Nada de font-size solto em px nos
+> componentes; quem quiser outra densidade sobrescreve o `html` no app.
+
+## Radius
+
+> Escala mapeada no `@theme inline` preservando o sentido pré-v4 dos utilitários `rounded-*`
+> (neutraliza o rename do Tailwind v4). E a forma também tem papel: `rounded-card/popover/dialog`
+> são a forma das superfícies elevadas (par do `bg-*`/`shadow-*`), derivados de `--radius` — a
+> identidade por app escala tudo junto. Controles (botões, inputs) seguem na escala sm–xl.
+
+```tsx preview
+render(
+  <div className="flex flex-wrap gap-4">
+    {[
+      ['rounded-sm', 'radius − 4px'],
+      ['rounded-md', 'radius − 2px'],
+      ['rounded-lg', 'radius (0.625rem)'],
+      ['rounded-xl', 'radius + 4px'],
+      ['rounded-popover', 'papel popover (radius − 2px)'],
+      ['rounded-dialog', 'papel dialog (radius + 6px)'],
+      ['rounded-card', 'papel card (radius + 6px)'],
+    ].map(([cls, calc]) => (
+      <div key={cls} className="flex items-center gap-3">
+        <div className={'h-12 w-12 border-2 border-foreground/30 bg-muted ' + cls} />
+        <div>
+          <div className="font-mono text-xs">{cls}</div>
+          <div className="text-xs text-muted-foreground">{calc}</div>
+        </div>
+      </div>
+    ))}
+  </div>,
+)
+```
+
+## Divergências declaradas vs shadcn
+
+> A regra anti-drift: o que não está declarado aqui (e no `theme.css`) é drift e deve ser
+> sincronizado — skill `opus`.
+
+1. Formato HSL nos tokens (o upstream migrou pra oklch) — legibilidade e ferramentas nossas; os
+   valores acompanham o upstream, só o formato difere.
+2. Elevação no dark: `--card`/`--popover` ficam ACIMA de `--background` (10% vs 3.9%) — identidade
+   da casa; dialog e card "sobem" da página de verdade.
+3. Radius mapeado (sm/md/lg/xl) preservando o sentido pré-v4 dos utilitários `rounded-*`.
+
+(A antiga nº 4 — escala `shadow-*` sobrescrita — foi aposentada: a elevação da casa vive em
+namespace próprio, `shadow-card/popover/dialog` + `ring-edge`, sem tocar os defaults do Tailwind.)
+
+5. Bordas mais leves no light: `--border`/`--input` em 92.5% (upstream 89.8%) — par do canvas
+   quase-branco do body; a aresta de superfície elevada já é o `ring-edge`.
+
+## Identidade por app
+
+> O tema do Opus é a base; cada app sobrescreve as vars pra ter a própria identidade sem forkar componente.
+
+```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%);
+}
+```

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

@@ -0,0 +1,50 @@
+## Básico
+
+Texto auxiliar, nunca essencial — quem navega por toque não vê tooltip. Em botão só de ícone, o aria-label continua obrigatório.
+
+```tsx preview
+<Tooltip>
+  <TooltipTrigger asChild>
+    <Button variant="ghost" size="icon" aria-label="Nova sessão"><Plus /></Button>
+  </TooltipTrigger>
+  <TooltipContent>Nova sessão.</TooltipContent>
+</Tooltip>
+```
+
+## Lados
+
+side escolhe o lado preferido; o Radix inverte sozinho quando falta espaço.
+
+```tsx preview
+<Tooltip>
+  <TooltipTrigger asChild><Button variant="ghost">Em cima</Button></TooltipTrigger>
+  <TooltipContent side="top">Lado padrão.</TooltipContent>
+</Tooltip>
+<Tooltip>
+  <TooltipTrigger asChild><Button variant="ghost">Direita</Button></TooltipTrigger>
+  <TooltipContent side="right">side=&quot;right&quot;.</TooltipContent>
+</Tooltip>
+<Tooltip>
+  <TooltipTrigger asChild><Button variant="ghost">Embaixo</Button></TooltipTrigger>
+  <TooltipContent side="bottom">side=&quot;bottom&quot;.</TooltipContent>
+</Tooltip>
+```
+
+## Provider no root
+
+O TooltipProvider embrulha o app uma vez (delay compartilhado); cada Tooltip dispensa provider próprio. Este app já monta o seu no main.tsx.
+
+```tsx
+/* main.tsx do app — uma vez, no root. */
+<TooltipProvider delayDuration={200}>
+  <App />
+</TooltipProvider>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `TooltipProvider.delayDuration` | `number` | `0` | Atraso (ms) até aparecer — compartilhado por todos os tooltips do app. |
+| `TooltipContent.side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Lado preferido; inverte sozinho sem espaço (Radix). |
+| `TooltipContent.sideOffset` | `number` | `4` | Distância (px) entre gatilho e dica. |

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

@@ -0,0 +1,37 @@
+## Básico
+
+Trunca numa linha e mostra tooltip **só quando o texto realmente corta** (medição do
+overflow, re-medida em resize). Texto que cabe não ganha dica — diferente do `title`
+sempre presente, que vira ruído.
+
+```tsx preview
+<div className="w-48 rounded-md border p-2">
+  <Truncate>relatorio-consolidado-vendas-pos-vendas-2026-julho-final-v3.xlsx</Truncate>
+</div>
+```
+
+## Quando cabe, nada acontece
+
+O mesmo componente, com espaço de sobra: sem tooltip, sem atributo, só o texto.
+
+```tsx preview
+<div className="w-96 rounded-md border p-2">
+  <Truncate>resumo.pdf</Truncate>
+</div>
+```
+
+## Conteúdo da dica
+
+`tooltip` sobrepõe o conteúdo mostrado no hover (default: os próprios children) — útil
+quando a dica precisa de mais contexto que o texto cortado.
+
+```tsx preview
+<div className="w-48 rounded-md border p-2">
+  <Truncate tooltip="apps/platform/src/domains/aftersales/actions/schedule-followup.ts">
+    schedule-followup.ts — apps/platform/src/domains/aftersales
+  </Truncate>
+</div>
+```
+
+Requer `TooltipProvider` na raiz (o esqueleto do `opus create` já monta). Largura vem do
+container ou de `className` (`max-w-*`) — o span é `block truncate`.

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

@@ -0,0 +1,40 @@
+---
+title: Como consumir
+---
+
+# Como consumir a UI
+
+A verdade visual da casa: os componentes do `@softize/opus/ui` renderizados com o nosso tema. O
+que você vê aqui é o que os apps entregam — a referência é esta doc, não o site do shadcn.
+
+## Por que esta doc existe
+
+> O site do shadcn é catálogo do que existe lá; os exemplos de lá decoram composições que não
+> existem no nosso registry. A expectativa visual e de uso nasce aqui.
+
+Cada página de componente mostra exemplos vivos por variante (renderizados com o tema da casa), o
+snippet de como se escreve e as props que importam. O texto de quando usar vem do próprio
+componente (o `meta` co-localizado na fonte) — a doc deriva, não duplica.
+
+## Como consumir
+
+> Um barrel só pra componentes e hooks; o tema entra por CSS. Nada de copiar componente pra dentro do app.
+
+```tsx
+// Componentes e hooks — tudo do mesmo barrel.
+import { Button, Dialog, useAction } from '@softize/opus/ui/react'
+
+/* index.css — 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';
+```
+
+## Origem e anti-drift
+
+> Cada componente declara de onde veio — e a regra de sincronização vem junto.
+
+- **Origem shadcn** — port curado do shadcn (Radix + cmdk). Toda divergência do upstream é
+  DECLARADA no componente ou no tema — o que diverge sem declaração é drift e deve ser
+  sincronizado (skill `opus`).
+- **Nativo do Opus** — nasceu aqui (os patterns de action). Não tem upstream pra acompanhar; a
+  referência é esta doc.

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

@@ -0,0 +1,48 @@
+---
+title: Atualizar o Opus
+---
+
+# Atualizar o Opus
+
+Projeto em produção fica meses sem tocar no Opus — e um dia precisa pular várias
+versões de uma vez. O ritual é o mesmo para humano e IA, e não depende de memória:
+cada peça do caminho está escrita ou é um gate que quebra alto.
+
+## 1. Saber que está atrás
+
+O **Maestro** compara o pin (`opus.json`) com a versão instalada e com a fonte a cada
+sessão — o alerta no rodapé diz a distância (`v2.9.0 → v2.15.2`) e o **Atualizar** faz
+a parte mecânica: bump da dependência, re-materialização da camada de IA (skills,
+hooks, agentes) e re-sync do bloco gerenciado do CLAUDE.md. Fora do Maestro:
+`pnpm outdated @softize/opus`.
+
+## 2. Saber o que mudou
+
+O changelog **viaja no pacote** — depois do bump, está em
+`node_modules/@softize/opus/CHANGELOG.md`. Uma entrada por versão; quando quebra,
+a seção **Breaking** diz a migração (o que renomeou, o que fazer no seu código).
+A esteira de release **recusa** publicar versão sem entrada — o arquivo não defasa.
+
+- **minor** (2.9 → 2.10): compatível; leia por curiosidade.
+- **major** (2.x → 3.0): pare nas seções Breaking de cada versão pulada, na ordem.
+
+## 3. Deixar os gates cobrarem o resto
+
+O Opus ship source: o que quebrou aparece com arquivo e linha. Rode, na ordem:
+
+```bash
+pnpm typecheck        # a API nova cobra os tipos
+pnpm exec opus check  # convenções (regras novas inclusas)
+pnpm test             # comportamento
+pnpm manifest:check   # a spec projetada ficou fresca?
+opus db migrate       # schema em dia (drift-check embutido)
+```
+
+Verde em tudo = atualizado de verdade. O bump entra no PR como qualquer mudança de
+código — atualização de base passa por review, não por fé.
+
+## Pulou muitas versões?
+
+O ritual não muda, só o volume: leia as seções Breaking acumuladas (o changelog é
+uma lista, não um diff), aplique na ordem e deixe os gates validarem o conjunto.
+Não há caminho especial — é o mesmo laço, com mais iterações.

package/src/ui/docs/doc-client.tsx

@@ -0,0 +1,214 @@
+/**
+ * doc-client.tsx — o PALCO dos exemplos vivos dos patterns. Client fake + contratos
+ * de mentira pra doc demonstrar ActionForm/Search/View/Trigger sem servidor.
+ * Nada daqui vai pra produção: no app real, o contrato vem do spec compartilhado e o
+ * client fala com a API (ver apps/admin/web/src/adapter.ts, o consumidor canônico).
+ */
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { z } from 'zod'
+import { defineContract, error } from '../../core/index.ts'
+import type { ActionDef, ActionResult, ClientAdapter, Paginated } from '../../core/index.ts'
+import { TbdlibProvider } from '../react.tsx'
+
+// — Dados enlatados (domínio da casa) —
+export interface DocBrowserWorkspace {
+  id: string
+  name: string
+  client: string
+  status: 'active' | 'onboarding' | 'paused'
+  agents: number
+}
+
+const WORKSPACES: DocBrowserWorkspace[] = [
+  { id: 'empresa-x', name: 'Empresa X', client: 'Empresa X', status: 'active', agents: 3 },
+  { id: 'empresa-w', name: 'Empresa W', client: 'Empresa W', status: 'active', agents: 4 },
+  { id: 'empresa-y', name: 'Empresa Y', client: 'Empresa Y', status: 'onboarding', agents: 1 },
+  { id: 'empresa-z', name: 'Empresa Z', client: 'Empresa Z', status: 'paused', agents: 2 },
+]
+
+const STATUS = ['active', 'onboarding', 'paused'] as const
+
+// — Contratos fake (mesmo shape dos reais; ver apps/admin/shared/src/workspaces.ts) —
+export const docWorkspaceCreate = defineContract({
+  name: 'workspace.create',
+  kind: 'form',
+  label: 'Novo workspace',
+  messages: { success: 'Workspace criado', error: 'Falha ao criar workspace' },
+  input: z.object({
+    name: z.string().min(2).max(120),
+    status: z.enum(STATUS).default('onboarding'),
+    contact: z.string().max(200).optional(),
+    notes: z.string().max(2000).optional(),
+  }),
+  output: z.object({ id: z.string() }),
+  fields: {
+    name: { label: 'Nome', placeholder: 'Ex.: Empresa X', hint: 'Digite "Softize" pra ver o erro de servidor.' },
+    status: { label: 'Status' },
+    contact: { label: 'Contato', placeholder: 'email@cliente.com' },
+    notes: { label: 'Observações', placeholder: 'Contexto do onboarding…' },
+  },
+  invalidates: ['workspace.list'],
+})
+
+export const docWorkspaceList = defineContract({
+  name: 'workspace.list',
+  kind: 'list',
+  summary: 'Lista os workspaces do palco da doc',
+  input: z.object({
+    q: z.string().optional(),
+    sort: z.string().optional(),
+    status: z.enum(STATUS).optional(),
+    client: z.string().optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+  }),
+  output: z.object({
+    id: z.string(),
+    name: z.string(),
+    client: z.string(),
+    status: z.enum(STATUS),
+    agents: z.number(),
+  }),
+  // O modo DECLARATIVO do ActionList: a tabela e a toolbar derivam daqui.
+  columns: [
+    { key: 'name', label: 'Workspace', sortable: true },
+    { key: 'client', label: 'Cliente' },
+    { key: 'status', label: 'Status', type: 'badge', fit: true },
+    { key: 'agents', label: 'Agentes', type: 'number', fit: true },
+  ],
+  filters: {
+    status: {
+      label: 'Status',
+      type: 'select',
+      options: {
+        kind: 'static',
+        items: [
+          { value: 'active', label: 'Ativo' },
+          { value: 'onboarding', label: 'Onboarding' },
+          { value: 'paused', label: 'Pausado' },
+        ],
+      },
+    },
+    client: { label: 'Cliente', type: 'text', advanced: true },
+  },
+  text: { fields: ['name'] },
+  sort: { fields: ['name'] },
+  paginate: 'cursor',
+})
+
+export const docWorkspaceView = defineContract({
+  name: 'workspace.view',
+  kind: 'view',
+  summary: 'Detalhe de um workspace do palco da doc',
+  input: z.object({ id: z.string() }),
+  output: z.object({
+    id: z.string(),
+    name: z.string(),
+    client: z.string(),
+    status: z.enum(STATUS),
+    agents: z.number(),
+  }),
+  projection: ['id', 'name', 'client', 'status', 'agents'],
+})
+
+export const docSessionArchive = defineContract({
+  name: 'session.archive',
+  kind: 'simple',
+  label: 'Arquivar sessão',
+  messages: { success: 'Sessão arquivada', error: 'Falha ao arquivar' },
+  input: z.object({ id: z.string() }),
+  output: z.object({ ok: z.boolean() }),
+})
+
+export const docSessionDelete = defineContract({
+  name: 'session.delete',
+  kind: 'simple',
+  label: 'Excluir sessão',
+  messages: { success: 'Sessão excluída', error: 'Falha ao excluir' },
+  // ConfirmSpec DECLARADO no contrato: o ActionTrigger monta o dialog sozinho.
+  confirm: {
+    title: 'Excluir a sessão?',
+    message: 'O worktree e o preview desta sessão serão removidos.',
+    confirmLabel: 'Excluir',
+    destructive: true,
+  },
+  input: z.object({ id: z.string() }),
+  output: z.object({ ok: z.boolean() }),
+})
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms))
+
+// — Client fake: pattern-match no action.name, latência pra dar tempo de VER o loading —
+const docClient: ClientAdapter = {
+  name: 'doc-client',
+  kind: 'client',
+  async run<T>(action: ActionDef, input: unknown): Promise<ActionResult<T>> {
+    await sleep(400)
+    const meta = { actionId: '', action: action.name, durationMs: 400 }
+    switch (action.name) {
+      case 'workspace.create': {
+        const { name } = input as { name: string }
+        // Caminho de erro demonstrável: o nome reservado simula conflito no servidor.
+        if (name.trim().toLowerCase() === 'softize') {
+          return {
+            ok: false,
+            error: error({ code: 'conflict', category: 'conflict', message: 'Já existe um workspace com este nome.' }),
+            meta,
+          }
+        }
+        return { ok: true, data: { id: name.toLowerCase().replace(/\s+/g, '-') } as T, meta }
+      }
+      case 'workspace.list': {
+        const { q, status, client, sort } = input as {
+          q?: string
+          status?: DocBrowserWorkspace['status']
+          client?: string
+          sort?: string
+        }
+        const items = WORKSPACES.filter(
+          (w) =>
+            (q === undefined || q === '' || w.name.toLowerCase().includes(q.toLowerCase())) &&
+            (status === undefined || w.status === status) &&
+            (client === undefined || client === '' || w.client.toLowerCase().includes(client.toLowerCase())),
+        )
+        // Convenção do sort declarativo: '<key>:<dir>' — o handler implementa o orderBy.
+        if (sort !== undefined) {
+          const [field, dir] = sort.split(':')
+          if (field === 'name') items.sort((a, b) => (dir === 'desc' ? b.name.localeCompare(a.name) : a.name.localeCompare(b.name)))
+        }
+        const page: Paginated<DocBrowserWorkspace> = { items, cursor: { next: null }, total: items.length }
+        return { ok: true, data: page as T, meta }
+      }
+      case 'workspace.view': {
+        const { id } = input as { id: string }
+        const ws = WORKSPACES.find((w) => w.id === id)
+        if (ws === undefined) {
+          return {
+            ok: false,
+            error: error({ code: 'not_found', category: 'not_found', message: 'Workspace não encontrado.' }),
+            meta,
+          }
+        }
+        return { ok: true, data: ws as T, meta }
+      }
+      case 'session.archive':
+      case 'session.delete':
+        return { ok: true, data: { ok: true } as T, meta }
+    }
+    return {
+      ok: false,
+      error: error({ code: 'not_found', category: 'not_found', message: 'Action sem resposta enlatada no palco da doc.' }),
+      meta,
+    }
+  },
+}
+
+const queryClient = new QueryClient()
+
+/** Embrulha os exemplos de pattern: react-query + driver do Opus com o client fake. */
+export function DocBrowserActionProvider({ children }: { children: React.ReactNode }): React.ReactElement {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <TbdlibProvider client={docClient}>{children}</TbdlibProvider>
+    </QueryClientProvider>
+  )
+}