@softize/opus 8.6.6

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

@@ -0,0 +1,86 @@
+## Padrão (single)
+
+`type=single` abre um painel por vez. `collapsible` deixa fechar o que está aberto — sem ele,
+sempre fica um item expandido. `defaultValue` deixa o estado com o componente.
+
+```tsx preview
+<Accordion type="single" collapsible defaultValue="overview" className="w-full">
+  <AccordionItem value="overview">
+    <AccordionTrigger>Visão geral</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-muted-foreground">Resumo do workspace Empresa X.</p>
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="agents">
+    <AccordionTrigger>Agentes</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-muted-foreground">developer, reviewer e designer ativos.</p>
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="repos">
+    <AccordionTrigger>Repositórios</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-muted-foreground">empresa-x-api e empresa-x-web vinculados.</p>
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+## Múltiplos abertos
+
+`type=multiple` permite vários painéis expandidos ao mesmo tempo — `defaultValue` vira um
+array com os itens abertos de saída.
+
+```tsx preview
+<Accordion type="multiple" defaultValue={['skills', 'prompt']} className="w-full">
+  <AccordionItem value="prompt">
+    <AccordionTrigger>Prompt</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-muted-foreground">O prompt do agente developer.</p>
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="skills">
+    <AccordionTrigger>Skills</AccordionTrigger>
+    <AccordionContent>
+      <p className="text-muted-foreground">clean-code, code-style, ddd e test vinculadas.</p>
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+## Controlado (com estado)
+
+No modo `single`, `value`/`onValueChange` tiram o estado do componente — dá pra abrir um item
+de fora. Exemplo **com estado** (o `render()` deixa o hook rodar):
+
+```tsx preview
+const [open, setOpen] = React.useState('developer')
+
+render(
+  <Accordion type="single" collapsible value={open} onValueChange={setOpen} className="w-full">
+    <AccordionItem value="developer">
+      <AccordionTrigger>Agente developer</AccordionTrigger>
+      <AccordionContent>
+        <p className="text-muted-foreground">Implementa a task no worktree da sessão.</p>
+      </AccordionContent>
+    </AccordionItem>
+    <AccordionItem value="reviewer">
+      <AccordionTrigger>Agente reviewer</AccordionTrigger>
+      <AccordionContent>
+        <p className="text-muted-foreground">Revisa o handoff e carimba o diff.</p>
+      </AccordionContent>
+    </AccordionItem>
+  </Accordion>,
+)
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `type` (Accordion) | `'single' \| 'multiple'` | | single abre um painel por vez; multiple permite vários. |
+| `collapsible` (Accordion) | `boolean` | `false` | Só no single — permite fechar o item aberto. |
+| `defaultValue` (Accordion) | `string \| string[]` | | Item(ns) aberto(s) no modo não controlado. |
+| `value` (Accordion) | `string \| string[]` | | Item(ns) aberto(s) no modo controlado — pareie com onValueChange. |
+| `onValueChange` (Accordion) | `(value) => void` | | Chamado quando o usuário abre ou fecha um item. |
+| `value` (AccordionItem) | `string` | | Identificador do item — é o que defaultValue/value referenciam. |

package/src/ui/docs/content/action-form-card.md

@@ -0,0 +1,24 @@
+## Form como card
+
+O ActionForm dentro de um Card — header, conteúdo e rodapé, no respiro do Card (sem divisor nem
+faixa de modal). Pra estruturar uma seção da página como painel. O título é opcional.
+
+```tsx preview col md
+<DocBrowserActionProvider>
+  <ActionFormCard
+    title="Editar workspace"
+    action={docWorkspaceCreate}
+    defaultValues={{ name: 'Empresa X', status: 'active' }}
+    submitLabel="Salvar"
+  />
+</DocBrowserActionProvider>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `title` | `string` | | Título do header (com divisor embaixo). Sem ele, o card começa direto no corpo. |
+| `description` | `string` | | Subtítulo opcional, abaixo do título. |
+| `action / defaultValues / fieldOptions / submitLabel / onSuccess / onCancel` | `— (iguais ao ActionForm)` | | O resto é o ActionForm — o card injeta o conteúdo (CardContent) e o rodapé (CardFooter) por baixo. |
+| `cardClassName` | `string` | | Classes da SUPERFÍCIE do card (ex.: largura). `className` vai pro `<form>`. |

package/src/ui/docs/content/action-form-dialog.md

@@ -0,0 +1,30 @@
+## Form em modal
+
+O open é de quem orquestra; o fechamento no sucesso é do pattern. Header e X fixos, os campos
+scrollam, o rodapé é a faixa da casa. O preview roda num client de mentira — no app, o contrato
+vem do spec.
+
+```tsx preview
+const [open, setOpen] = useState(false)
+
+render(
+  <DocBrowserActionProvider>
+    <Button onClick={() => setOpen(true)}><Plus /> Novo workspace</Button>
+    <ActionFormDialog
+      open={open}
+      onOpenChange={setOpen}
+      title="Novo workspace"
+      description="O workspace agrupa os repositórios e agentes do cliente."
+      action={docWorkspaceCreate}
+    />
+  </DocBrowserActionProvider>,
+)
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `open / onOpenChange` | `boolean / (open: boolean) => void` | | Controle do modal — o pattern chama onOpenChange(false) no sucesso e no Cancelar. |
+| `title / description` | `string` | | O DialogHeader fixo — description é opcional. |
+| `…ActionFormProps` | `action, defaultValues, onSuccess, fieldOptions…` | | Todo o resto desce pro ActionForm interno — mesma API da página dele. |

package/src/ui/docs/content/action-form.md

@@ -0,0 +1,125 @@
+## Form derivado do contrato
+
+Zero JSX de campo: enum vira Select, string longa vira Textarea, obrigatório ganha o asterisco. O
+preview roda num client de mentira — digite "Softize" no nome pra ver o erro de servidor inline; o
+submit só habilita com mudança real (dirty).
+
+```tsx preview col md
+<DocBrowserActionProvider>
+  <ActionForm action={docWorkspaceCreate} />
+</DocBrowserActionProvider>
+```
+
+## Composição (diagramação livre)
+
+Com children, o AUTO desliga e você diagrama: `<ActionFormField name />` coloca cada campo — com
+label, hint, widget, erro e asterisco derivados do contrato — onde quiser. Condicional é JSX;
+opções de runtime entram por prop no campo. O comportamento (submit, validação, toast,
+invalidação) continua encapsulado — e o espaçamento é 100% seu: o campo não impõe margem
+(quem diagrama usa grid/gap/space-y como quiser).
+
+```tsx preview col md
+<DocBrowserActionProvider>
+  <ActionForm action={docWorkspaceCreate}>
+    <div className="space-y-6">
+      <div className="grid grid-cols-2 gap-4">
+        <ActionFormField name="name" />
+        <ActionFormField name="status" />
+      </div>
+      <ActionFormField name="contact" />
+      <ActionFormField name="notes" />
+    </div>
+  </ActionForm>
+</DocBrowserActionProvider>
+```
+
+## Valores iniciais e rótulos
+
+defaultValues pré-carrega (modo edição); submitLabel/cancelLabel trocam o rodapé. O onCancel é de
+quem orquestra (fechar drawer, voltar…).
+
+```tsx preview col md
+<DocBrowserActionProvider>
+  <ActionForm
+    action={docWorkspaceCreate}
+    defaultValues={{ name: 'Empresa X', status: 'active' }}
+    submitLabel="Atualizar"
+    onCancel={() => undefined}
+  />
+</DocBrowserActionProvider>
+```
+
+## Pré-requisitos
+
+O driver precisa dos dois providers no root — exatamente o wiring do admin (o consumidor
+canônico).
+
+```tsx
+/* main.tsx do app. */
+<QueryClientProvider client={queryClient}>
+  <TbdlibProvider client={apiClient}>
+    <App />
+  </TbdlibProvider>
+</QueryClientProvider>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `action` | `FormContract<TInput, TData>` | | O contrato da FormAction — dele saem campos (input Zod + fields), mensagens e invalidação de cache. |
+| `defaultValues` | `Partial<TInput>` | | Valores iniciais — o modo edição de um update/patch. |
+| `onSuccess` | `(data: TData) => void` | | Pós-sucesso (o toast e a invalidação de cache já aconteceram). |
+| `submitLabel / cancelLabel / onCancel` | `string / string / () => void` | `'Salvar' / 'Cancelar'` | Rodapé do form — o Cancelar só aparece com onCancel. |
+| `fieldOptions` | `Record<string, SelectOption[]>` | | Opções de runtime por campo (ex.: ids de skills) — sobrepõe as inferidas do z.enum. |
+| `className / body / footer` | `string / (node) => node / (node) => node` | | className = classes do `<form>`. body/footer = SLOTS: recebem os campos / os botões e escolhem o invólucro — é como o ActionFormDialog injeta DialogBody/DialogFooter (scroll + faixa). |
+| `children` | `ReactNode` | | Modo COMPOSIÇÃO: diagrame com `<ActionFormField name />`. Sem children, o AUTO monta todos os campos na ordem do contrato. |
+
+## ActionFormField
+
+| Prop | Tipo | Descrição |
+|---|---|---|
+| `name` | `string` | O campo do contrato (chave em `fields`/schema). Fora do schema, não renderiza. |
+| `options` | `SelectOption[]` | Opções por id de runtime — sobrepõe o fieldOptions do form e o z.enum. |
+| `className` | `string` | Classes do invólucro (ex.: `col-span-2` numa grid). |
+
+## De onde vêm as opções de um select
+
+Precedência, da mais específica pra mais automática: **prop `options` do campo** >
+**`fieldOptions` do form** > **`options` do FieldSpec no contrato** (`{ kind: 'dictionary',
+ref }` resolve pelos dicts do `<TbdlibProvider dicts={{ ref: meuDict }}>` — o `DictType` do
+`t.dict` encaixa direto; `{ kind: 'static', items }` renderiza como declarado) > **meta do
+`t.dict` no schema** (zero-config: campo `meuDict.zod()` — ou multiselect com elemento dict —
+resolve value→label pela meta que viaja no contrato, sem registry) > **chaves cruas do
+z.enum**. Campo texto com opções declaradas (runtime ou spec) vira single-select por-id.
+
+## Controle custom: useActionFormContext
+
+Campo com UI própria (grade de permissões, canvas…) que nenhum widget cobre? No modo
+composição, o hook dá acesso ao form do contrato — o campo custom participa do submit
+sem abandonar o `<ActionForm>`:
+
+```tsx
+import { useActionFormContext } from '@softize/opus/ui/react'
+
+function PermissionGrid() {
+  const { form } = useActionFormContext()
+  const perms = (form.watch('permissions') as string[] | undefined) ?? []
+  const toggle = (p: string) =>
+    form.setValue(
+      'permissions',
+      perms.includes(p) ? perms.filter((x) => x !== p) : [...perms, p],
+      { shouldValidate: true, shouldDirty: true },
+    )
+  const error = form.formState.errors['permissions']
+  // …sua grade; zod-resolver, erro inline e submit continuam do contrato.
+}
+
+<ActionForm action={roleUpdate}>
+  <ActionFormField name="name" />
+  <PermissionGrid />
+</ActionForm>
+```
+
+O contexto também expõe `shape` (Zod por campo), `fields` (FieldSpec) e `fieldOptions`.
+Fora de um `<ActionForm>`, o hook explode com mensagem clara — igual ao `ActionFormField`.

package/src/ui/docs/content/action-list-dialog.md

@@ -0,0 +1,68 @@
+## ListAction em modal
+
+O modo modal da listagem, action-driven: a lista é query-backed (busca no mount, re-busca quando o input muda e refaz sozinha quando um form/trigger invalida a action), os estados derivam do fetch, e a nota da toolbar já vem com o "N no total". Children diagrama os itens — composição, como nos irmãos.
+
+```tsx preview col
+const [open, setOpen] = useState(false)
+
+render(
+  <DocBrowserActionProvider>
+    <Button onClick={() => setOpen(true)}>Workspaces</Button>
+    <ActionListDialog
+      action={docWorkspaceList}
+      input={{}}
+      open={open}
+      onOpenChange={setOpen}
+      title="Workspaces"
+      description="Back-office"
+      actions={
+        <Button size="sm" variant="outline">
+          <Plus /> Workspace
+        </Button>
+      }
+      emptyText="Nenhum workspace."
+    >
+      {(workspaces) => (
+        <div className="space-y-2">
+          {workspaces.map((w) => (
+            <div key={w.id} className="flex items-center gap-2 rounded-md border border-border p-3">
+              <span className="text-sm font-semibold">{w.name}</span>
+              <Badge variant={w.status === 'active' ? 'success' : 'warning'}>{w.status}</Badge>
+              <span className="ml-auto text-xs text-muted-foreground">{w.agents} agentes</span>
+            </div>
+          ))}
+        </div>
+      )}
+    </ActionListDialog>
+  </DocBrowserActionProvider>,
+)
+```
+
+## O que o contrato não sabe
+
+Dois escape hatches, pros casos em que o modal agrega mais de uma fonte: `loading` soma a carga de uma query irmã (ex.: os papéis que os cards precisam pra rotular) e `empty` sobrepõe o vazio derivado (ex.: com o form inline de criar aberto, a lista vazia mostra o form, não o emptyText).
+
+```tsx
+<ActionListDialog
+  action={agentListContract}
+  input={{ workspaceId }}
+  loading={rolesLoading}                                  // A query irmã.
+  empty={(repos) => repos.length === 0 && !adding}        // Form inline aberto ⇒ children.
+  ...
+/>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `action / input` | `ListAction / TInput` | | O contrato e os filtros — mudou o input, re-busca; `invalidates` de forms/triggers refaz sozinho. |
+| `open / onOpenChange` | `boolean / (open) => void` | | Controle do modal — de quem orquestra. |
+| `title / description` | `string` | | O DialogHeader fixo (em geral, o que é a lista e de quem). |
+| `children` | `(items, refetch) => ReactNode` | | O layout dos itens (cards/linhas) — os estados já saíram daqui. |
+| `note` | `ReactNode \| (items) => ReactNode` | `"N no total"` | Nota à esquerda da toolbar — o default é derivado dos itens. |
+| `actions` | `ReactNode` | | Ação à direita da toolbar — em geral o botão de criar. |
+| `empty` | `(items) => boolean` | `items.length === 0` | Sobrepõe o vazio derivado. |
+| `loading` | `boolean` | | Carga extra agregada à do fetch (query irmã). |
+| `emptyText / errorText` | `string` | | Textos dos estados (DataState). |
+| `className` | `string` | `sm:max-w-3xl` | Largura do DialogContent. |

package/src/ui/docs/content/action-list.md

@@ -0,0 +1,194 @@
+## Declarativo pelo contrato (a diagramação da casa)
+
+O contrato descreve, a UI deriva — zero configuração no call site. `columns` vira a tabela emoldurada (o datagrid da casa; tipos text/number/date/badge, `fit`, `hidden`, headers ordenáveis que escrevem `sort: 'chave:dir'` no input); `filters` vira a toolbar (os não-avançados inline, os `advanced: true` no modal "Filtros" com contador); `text` liga a busca (param `q`); filtros do modal aplicados viram chips removíveis. A linha é RESPONSIVA: a busca tem largura auto (encolhe primeiro) e filtro inline que não cabe migra pro modal — medição real, re-avaliada no resize; só no caso extremo (nada mais a ceder) a linha quebra. O handler implementa o que o input diz (orderBy, where) — mesmo modelo do resto do Opus.
+
+```tsx preview col
+render(
+  <DocBrowserActionProvider>
+    <div className="w-full">
+      <ActionList action={docWorkspaceList} input={{}} emptyMessage="Nenhum workspace." />
+    </div>
+  </DocBrowserActionProvider>,
+)
+```
+
+## Células custom (cells)
+
+As colunas do contrato descrevem DADOS; apresentação especial entra por cima com `cells` (chave = key da coluna). É onde vivem chips coloridos por dict, links e a coluna de ações.
+
+```tsx preview col
+const STATUS_VARIANT = { active: 'success', onboarding: 'warning', paused: 'outline' }
+
+render(
+  <DocBrowserActionProvider>
+    <div className="w-full">
+      <ActionList
+        action={docWorkspaceList}
+        input={{}}
+        cells={{
+          status: (w) => <Badge variant={STATUS_VARIANT[w.status]}>{w.status}</Badge>,
+        }}
+      />
+    </div>
+  </DocBrowserActionProvider>,
+)
+```
+
+## Período (o campo dinâmico)
+
+Com `periods` no contrato, a toolbar ganha o controle de período: um popover com os presets e, no "Personalizado", o calendário de range ali mesmo. Período é recorte OBRIGATÓRIO do caso de uso: o default (o preset com `default: true`, ou o primeiro) já vem aplicado e não existe "sem período". O preset fica RELATIVO na URL (`?period=last7`; o default é omitido); no custom o range vai direto no param (`?period=2026-07-01..2026-07-07` — o "custom" é implícito). No fetch, o pattern materializa o range nos params `from`/`to` — o handler implementa o recorte.
+
+```tsx
+periods: [
+  { value: 'today', label: 'Hoje' },
+  { value: 'last7', label: 'Últimos 7 dias' },
+  { value: 'thisMonth', label: 'Este mês' },
+]
+// Presets computáveis: today · yesterday · last7 · last30 · thisMonth · lastMonth.
+```
+
+## Paginação e loading
+
+O pattern manda `limit` (= `pageSize`, default 50) e `page` no input; o handler implementa o OFFSET e devolve `total` no Paginated. O rodapé (Página X de Y · páginas numeradas com reticências · "N itens no total") aparece sempre que há total; mudar filtro/busca/sort/período volta pra página 1 (a página vive na URL: `?page=2`). No refetch com a lista já na tela, o corpo esmaece (`aria-busy`) até os dados chegarem — o skeleton é só do primeiro load.
+
+## Multi-seleção com can (batch)
+
+`batch` liga a coluna de checkbox na tabela. O `can(item)` é a fonte única de elegibilidade: linha inelegível não marca, o "selecionar todos" pega só os elegíveis, o botão mostra quantos dos selecionados valem e o `run` recebe apenas esses. Com `confirm`, um dialog pede confirmação; ao resolver, a seleção limpa e a lista refaz.
+
+```tsx
+<ActionList action={runList} input={{}}
+  batch={[{
+    label: 'Reprocessar',
+    can: (run) => run.status === 'failed',
+    confirm: { title: 'Reprocessar as execuções?' },
+    run: async (runs) => { await Promise.all(runs.map((r) => api.retry(r.id))) },
+  }]}
+/>
+```
+
+## Views (a mesma listagem, outro renderer)
+
+Nem toda listagem é tabela: board, galeria, lista, calendário… A view é APRESENTAÇÃO de quem chama (`render`); o pattern dá o segment na toolbar (ToggleGroup, ICON-ONLY: declare `icon` — o label vira title/aria; sem ícone cai pro texto), o estado (`view` na URL) e os dados — a mesma fonte, os mesmos filtros. A tabela ('Tabela') participa quando há columns.
+
+```tsx preview col
+render(
+  <DocBrowserActionProvider>
+    <div className="w-full">
+      <ActionList
+        action={docWorkspaceList}
+        input={{}}
+        views={{
+          gallery: {
+            label: 'Galeria',
+            icon: <LayoutGrid />,
+            render: (workspaces) => (
+              <div className="grid grid-cols-2 gap-3">
+                {workspaces.map((w) => (
+                  <div key={w.id} className="rounded-lg border border-border p-3">
+                    <div className="flex items-center gap-2">
+                      <span className="text-sm font-semibold">{w.name}</span>
+                      <Badge variant={w.status === 'active' ? 'success' : 'warning'}>{w.status}</Badge>
+                    </div>
+                    <p className="mt-1 text-xs text-muted-foreground">{w.agents} agentes.</p>
+                  </div>
+                ))}
+              </div>
+            ),
+          },
+        }}
+      />
+    </div>
+  </DocBrowserActionProvider>,
+)
+```
+
+## Filtros dependentes, dictionary e lookup
+
+Três recursos do FilterSpec que a toolbar honra:
+
+- **`depends: ['outroFiltro']`** — o filtro dependente fica DESABILITADO até o pai ter valor, e mudar o pai limpa o dependente em cascata (o recorte perde o sentido quando o pai muda). Vale inline e no modal.
+- **`options: { kind: 'dictionary', ref: 'sessionStatus' }`** — as opções vêm de um DICT registrado no `<TbdlibProvider dicts={{ sessionStatus: statusDict }}>` (o `DictType` do `t.dict` encaixa direto). Labels do vocabulário no filtro E nos chips; runtime (`filterOptions`) sobrepõe.
+- **`options: { kind: 'lookup', source: 'x.lookup' }`** — as opções vêm de uma ACTION (server-side): o campo vira Select typeahead que chama a `source` (debounced) com `{ q }` — e com os valores dos `depends` no input. Convenção: a action de lookup devolve itens `{ value, label }`. Com valor aplicado mas opções ainda não carregadas (URL, chip), o chip mostra o próprio value.
+
+```tsx
+filters: {
+  project: { label: 'Projeto', type: 'select', options: { kind: 'static', items: [...] } },
+  sprint: {
+    label: 'Sprint',
+    type: 'lookup',
+    depends: ['project'],
+    options: { kind: 'lookup', source: 'sprint.lookup', depends: ['project'] },
+  },
+}
+```
+
+## Exibição e URL sync
+
+O botão de exibição (engrenagem) abre o popover de configuração da listagem — presente em QUALQUER view: colunas (liga/desliga, incluindo as `hidden` do contrato; só com a tabela ativa) e itens por página (o default do caller fica fora da URL) — e é a casa do que vier depois. E o estado inteiro da toolbar (q, sort, filtros, view, colunas, limit) serializa pra querystring com os helpers padrão:
+
+```tsx
+<ActionList
+  action={contract}
+  input={{}}
+  state={listParamsToState(params, contract)}
+  onStateChange={(next) => navigate(`/rota${listStateToParams(next, contract)}`)}
+/>
+```
+
+Convenção compacta (defaults omitidos): `?q=…&sort=chave:dir&status=…&view=board&cols=a,b,c&limit=25`.
+
+## Composição (layout livre)
+
+Com children, a tabela sai de cena e o layout dos itens é seu (cards, grid, o que for) — a toolbar declarativa e os estados (skeleton/erro/vazio) seguem daqui. Mesmo princípio do ActionForm com children.
+
+```tsx preview col
+render(
+  <DocBrowserActionProvider>
+    <div className="w-full">
+      <ActionList action={docWorkspaceList} input={{}}>
+        {(workspaces) => (
+          <div className="grid w-full grid-cols-2 gap-3">
+            {workspaces.map((w) => (
+              <div key={w.id} className="rounded-lg border border-border p-3">
+                <div className="flex items-center gap-2">
+                  <span className="text-sm font-semibold">{w.name}</span>
+                  <Badge variant={w.status === 'active' ? 'success' : 'warning'}>{w.status}</Badge>
+                </div>
+                <p className="mt-1 text-xs text-muted-foreground">{w.agents} agentes.</p>
+              </div>
+            ))}
+          </div>
+        )}
+      </ActionList>
+    </div>
+  </DocBrowserActionProvider>,
+)
+```
+
+## No contrato (ListAction)
+
+| Chave | O que declara |
+|---|---|
+| `columns` | `{ key, label, type?, sortable?, fit?, hidden?, dateFormat? }` — a tabela. `hidden` fica fora (base do futuro column picker). |
+| `filters` | `{ [nome]: { label, type, options?, multiple?, advanced?, depends?, … } }` — a toolbar. `advanced` vai pro modal; `depends` desabilita/cascateia; options `kind: 'lookup'` busca numa action. Valor aplicado entra no input com o MESMO nome. |
+| `text` | `{ fields }` — liga a busca; convenção: param `q` no input. Com período/filtros no contrato ela fica à direita; sendo a ÚNICA forma de recorte, abre a linha. |
+| `sort` | `{ fields, default }` — ordenação inicial; header ordenável escreve `sort: 'chave:dir'`. |
+| `periods` | `{ value, label }[]` — o controle de período (presets + Personalizado com calendário); materializa em `from`/`to` no input. |
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `action` | `ListAction<TInput, TItem>` | | A ListAction do Opus (kind list, output = item, paginate cursor). |
+| `input` | `TInput` | | O ESCOPO BASE (ex.: { workspaceId }) — a toolbar soma por cima, nunca sobrescreve. |
+| `cells` | `Record<string, (item) => ReactNode>` | | Células custom por cima das colunas do contrato (chave = column.key). |
+| `filterOptions` | `Record<string, SelectOption[]>` | | Opções de runtime pros filtros select/lookup (chave = nome do filtro). |
+| `columns` | `ActionListColumn<TItem>[]` | | Tabela EXPLÍCITA — sobrepõe as colunas do contrato (escape hatch). |
+| `children` | `(items, refetch) => ReactNode` | | Modo COMPOSIÇÃO: layout livre; a toolbar segue. Tem precedência sobre columns. |
+| `batch` | `ActionListBatchAction[]` | | Ações em lote: `{ label, can?, run, confirm?, destructive? }` — liga a multi-seleção. |
+| `rowId` | `(item) => string` | `item.id` | Identidade da linha pra seleção. |
+| `pageSize` | `number` | `50` | Itens por página DEFAULT (vira `limit`/`page` no input; handler devolve `total`). O usuário troca no popover de exibição. |
+| `state / onStateChange` | `ActionListState / (next) => void` | interno | Estado da toolbar controlado — pra quem embala sincronizar com a URL. |
+| `emptyMessage` | `string` | `'Nenhum resultado.'` | O texto do estado vazio. |
+| `onRowClick` | `(item: TItem) => void` | | Clique na linha (ex.: navegar pro detalhe) — só na tabela. |
+| `rowActions` | `(item: TItem) => ReactNode` | | Ações por linha (coluna final, à direita) — apresentação de quem chama, como `cells`; cliques ali não disparam o `onRowClick`. |

package/src/ui/docs/content/action-trigger.md

@@ -0,0 +1,72 @@
+## Disparo direto
+
+Sem confirm, dispara no clique: desabilita enquanto roda e toca o toast do contrato
+(messages.success/error). O label default vem do action.label.
+
+```tsx preview
+<DocBrowserActionProvider>
+  <ActionTrigger action={docSessionArchive} input={{ id: 'onboarding-faturamento' }} variant="outline" />
+</DocBrowserActionProvider>
+```
+
+## Confirmação declarada no contrato
+
+O ConfirmSpec mora na action (title/message/destructive) — o pattern monta o Dialog sozinho e o
+destructive já tonaliza o botão. Prop confirm sobrepõe quando a tela precisar de outro texto.
+
+```tsx preview
+<DocBrowserActionProvider>
+  <ActionTrigger action={docSessionDelete} input={{ id: 'onboarding-faturamento' }} />
+</DocBrowserActionProvider>
+```
+
+```tsx
+// No contrato (spec):
+confirm: {
+  title: 'Excluir a sessão?',
+  message: 'O worktree e o preview desta sessão serão removidos.',
+  confirmLabel: 'Excluir',
+  destructive: true,
+}
+
+// Na tela — nada além do disparo:
+<ActionTrigger action={sessionDeleteContract} input={{ id: session.id }} />
+```
+
+## A ação que mora no item (icon)
+
+Com `icon`, o botão vira icon-only: o `label` (ou o `action.label`) migra pro tooltip e pro `aria-label`, o visual fica discreto (ghost, e vermelho no hover quando o contrato marca `destructive`) e o clique **não vaza** pro item em volta — é o que permite viver dentro de uma linha ou card clicável. `itemLabel` nomeia o alvo na pergunta.
+
+```tsx
+<ActionTrigger
+  action={unitDeleteContract}
+  input={{ id: unit.id }}
+  icon={<Trash2 />}
+  label="Excluir"
+  itemLabel={unit.name}
+/>
+```
+
+> Isto absorveu o antigo `DeleteButton` (7.0.0), que era exatamente este componente com uma lixeira dentro. Se você tinha `<DeleteButton action input itemLabel />`, troque por `<ActionTrigger … icon={<Trash2 />} />` — **e confira se o contrato declara `confirm`**: sem ele o disparo é direto, e o DeleteButton perguntava sempre.
+
+## Erro que a pessoa entende
+
+Quando a action falha, a frase do SERVIDOR só vence o rótulo do contrato se o erro for de negócio — `conflict`, `validation`, `not_found`:
+
+> Este agente tem 3 conversas — desabilite em vez de excluir.
+
+Isso é acionável. Erro inesperado carrega texto técnico cru: sem a allowlist, uma violação de FK viraria `violates foreign key constraint "user_unit_id_fkey"` no toast de quem só clicou num botão. Por isso allowlist e não denylist — categoria desconhecida cai no rótulo genérico, que é o lado seguro de errar.
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `action` | `SimpleContract<TInput, TData>` | | A SimpleAction do Opus — label, messages e confirm vêm do contrato. |
+| `input` | `TInput` | | O que a action recebe — geralmente { id }. |
+| `label` | `string` | `action.label` | Sobrepõe o texto do botão. |
+| `variant / size` | `variants do Button` | `'default' (ou 'destructive' se o confirm declarar) / 'default'` | Visual do botão — o destructive do ConfirmSpec já escolhe sozinho. |
+| `confirm` | `{ title, description?, actionLabel?, cancelLabel? }` | | Confirmação via prop — sobrepõe o ConfirmSpec do contrato. |
+| `onSuccess` | `(data: TData) => void` | | Pós-sucesso (cache já invalidado pelo action.invalidates). |
+| `icon` | `React.ReactNode` | | Torna o botão icon-only: rótulo no tooltip e no `aria-label`, clique que não vaza pro item. |
+| `itemLabel` | `string` | | Nome do alvo na pergunta (sai entre aspas, em destaque, antes da mensagem do contrato). |
+| `className` | `string` | | Classes do botão (ex.: apertar o tamanho numa linha densa). |

package/src/ui/docs/content/action-view.md

@@ -0,0 +1,47 @@
+## Detalhe com estados padronizados
+
+Troque o workspace pra ver o skeleton; o inexistente mostra o erro padrão com o Tentar de novo. O
+preview roda num client de mentira — no app, cada feature embrulha (TicketView…) delegando o
+fetching pra cá.
+
+```tsx preview col
+const [id, setId] = useState('empresa-x')
+
+render(
+  <DocBrowserActionProvider>
+    <div className="w-full space-y-3">
+      <div className="flex flex-wrap gap-2">
+        <Button variant="outline" size="sm" onClick={() => setId('empresa-x')}>Empresa X</Button>
+        <Button variant="outline" size="sm" onClick={() => setId('softize-multica')}>Softize · Multica</Button>
+        <Button variant="outline" size="sm" onClick={() => setId('sessao-fantasma')}>Inexistente (erro)</Button>
+      </div>
+      <div className="rounded-lg border border-border p-4">
+        <ActionView action={docWorkspaceView} input={{ id }}>
+          {(ws) => (
+            <div className="space-y-1.5">
+              <div className="flex items-center gap-2">
+                <h3 className="text-sm font-semibold">{ws.name}</h3>
+                <Badge variant={ws.status === 'active' ? 'success' : 'warning'}>{ws.status}</Badge>
+              </div>
+              <p className="text-sm text-muted-foreground">
+                Cliente {ws.client} · {ws.agents} agentes vinculados.
+              </p>
+            </div>
+          )}
+        </ActionView>
+      </div>
+    </div>
+  </DocBrowserActionProvider>,
+)
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `action` | `ViewAction<TInput, TData>` | | A ViewAction do Opus (kind view, 1 recurso). |
+| `input` | `TInput` | | Geralmente { id } — mudou, recarrega. |
+| `children` | `(data: TData, refetch) => ReactNode` | | O estado feliz — layout 100% do consumidor; refetch pra recarregar por código. |
+| `render` | `(data: TData, refetch) => ReactNode` | | Alias de children (a API original). Children tem precedência. |
+| `loading / empty` | `ReactNode` | `3 skeletons / nada` | Sobrescreve os estados padrão quando o contexto pedir. |
+| `error` | `(err, retry) => ReactNode` | `mensagem + Tentar de novo` | Sobrescreve o estado de erro padrão. |