@softize/opus 12.7.1 → 12.8.0

package/CHANGELOG.md

@@ -7,6 +7,73 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 12.8.0 — 2026-09-02
+
+A apresentação de um dicionário passa a ser declarada no próprio `t.dict`, e não inferida por
+quem desenha a tela (ADR 0003). `t.dict(entries, { presentation })` aceita `classification`,
+`status`, `stage` ou `plain`; cada entrada pode declarar `tone` (`neutral` · `info` · `success` ·
+`warning` · `danger`), `icon` (nome do catálogo `iconPickerIcons`) e `description` (texto curto
+para a pessoa, usado em tooltip). `doc` continua sendo o entendimento de negócio para manifest e
+Lens. `presentation` inválido, `tone` inválido ou `tone` fora de status e estágio falham na
+construção do dicionário. O manifest projeta
+`presentation` ao lado de `doc`, e os stubs de `opus gen` preservam as opções.
+
+`@softize/opus/ui/react` exporta `DictionaryValue`, o renderer compartilhado: classificação vira
+`Badge` `outline`, status e estágio viram `Badge` tonal pelo `tone` da entrada (`neutral` sem tom,
+nunca `outline`), `plain` ou sem papel vira texto. Ícone só quando declarado e presente no
+catálogo; tooltip só quando `description` acrescenta ao rótulo; o texto está sempre presente.
+Overrides explícitos por `presentation`, `variant`, `icon`, `icons`, `tooltip` e `fallback`. O
+core ganha `presentDictionaryValue` e `dictionaryDescriptor` (sem React) e o tipo
+`DictEntryMeta` passa a morar em `@softize/opus/core`, reexportado pelo driver Zod. `Badge` ganha
+a variante tonal `danger`.
+
+`ActionList` reconhece colunas de dicionário sem configuração duplicada: campo de saída com a meta
+de `t.dict` renderiza `DictionaryValue`, e `ListColumnSpec.dictionary` nomeia um dicionário do
+provider para campos de string comum. `cells` continua vencendo. Dicionários sem `presentation`
+continuam como texto; a única mudança sem opt-in é que uma coluna de dicionário sem célula custom
+passa a mostrar o rótulo em vez do código, inclusive no chip de `type: 'badge'`.
+
+Valor ausente ganha representação padrão. `EmptyValue` mostra o travessão com “Não informado” à
+leitura assistiva em célula compacta e o rótulo em texto corrido; `label` dá o significado do
+domínio. `isAbsentValue` define a regra: `null`, `undefined`, string vazia ou só espaços; `0`,
+`false` e coleções vazias são valores. Colunas escalares de `ActionList` deixam de ficar em branco
+e passam a usar essa representação, com `ListColumnSpec.empty` para o texto do domínio (array e
+objeto sem `cells` seguem sem representação padrão); `DetailField` mostra “Não informado” ou
+`empty`. Condicionais locais de `—` podem ser removidas.
+
+`Pagination` deixa de ser byte-fiel ao shadcn: os números têm altura fixa e largura mínima
+quadrada que cresce com os dígitos (`h-9 min-w-9 w-auto tabular-nums`), `page` dá o conteúdo e o
+nome acessível “Página N”, sem `href` o link vira `<button>` com foco e `disabled`, e as setas
+falam pt-BR (`label` localiza, `iconOnly` deixa só a seta quadrada, `iconClassName` dimensiona o
+svg). `ActionList` compõe essa primitiva no rodapé e remove o paginador paralelo montado com
+`Button`; 5726 e 5727 já não se sobrepõem. **Breaking:** o default de `size` em `PaginationLink`
+passa de `icon` para `default`; quem dependia do quadrado fixo `size-9` num número declara
+`size="icon"`. Quem usava `PaginationPrevious`/`PaginationNext` com o texto em inglês passa a ver
+“Página anterior”/“Próxima página”, e a elipse deixa de carregar texto assistivo morto.
+
+Selects inline de `ActionFilterBar` passam a ter largura fixa e previsível (`w-40`; lookup e
+múltiplo `w-52`): a label trunca em vez de alargar o filtro e o valor selecionado trunca no
+trigger, com a opção inteira na lista. O modal de filtros avançados continua com `w-full`.
+
+As skills `model-opus-dictionary` e `build-opus-ui` passam a exigir a classificação do papel de
+apresentação e trazem a tabela de decisão, exemplos e avaliações que reprovam badge indiscriminado,
+dimensões independentes misturadas na mesma célula, status apresentado como classificação, tooltip
+que repete o rótulo, ícone inventado, comunicação somente por cor ou ícone, fallback de ausência
+repetido à mão, paginador paralelo, número de página preso a largura fixa e select inline
+dimensionado pelo conteúdo.
+
+## 12.7.2 — 2026-09-01
+
+`opus check` deixa de exigir modo `755` exato nos executáveis de `.githooks/`. O Git rastreia só o
+bit de execução, então um checkout com umask `002` nasce com `775` e o gate acusava drift onde não
+havia — um falso vermelho em toda worktree nova. O check agora aceita qualquer modo executável pelo
+dono; o que o `opus setup` grava (criação e reparo) continua saindo com `755` canônico, mas um
+executável existente com modo válido não é mais reescrito.
+
+O registry inclui a skill `model-opus-dictionary`: modelagem de vocabulário fechado com `t.dict`,
+schema derivado por `.zod()`, registro em `defineDomain({ dicts })` e a decisão dicionário ×
+lookup × discriminante local. `implement-opus-change` e `build-opus-ui` passam a rotear para ela.
+
 ## 12.7.1 — 2026-09-01
 
 No tema escuro, o item ativo de `Tabs` volta a usar uma superfície opaca, destacando a seleção

package/bin/lib/gen-dicts.mjs

@@ -102,10 +102,20 @@ function renderDict(name, dict) {
     const entry = values[key]
     lines.push(`  ${formatKey(key)}: ${renderEntry(entry)},`)
   }
-  lines.push('})')
+  const opts = renderDictOpts(dict)
+  lines.push(opts === null ? '})' : `}, ${opts})`)
   return lines
 }
 
+/** Opções do dict (`doc`, `presentation`) — preservadas no stub pra que o front leia o
+ *  mesmo papel de apresentação que o servidor declarou. */
+function renderDictOpts(dict) {
+  const parts = []
+  if (typeof dict.doc === 'string') parts.push(`doc: ${JSON.stringify(dict.doc)}`)
+  if (typeof dict.presentation === 'string') parts.push(`presentation: ${JSON.stringify(dict.presentation)}`)
+  return parts.length === 0 ? null : `{ ${parts.join(', ')} }`
+}
+
 /**
  * Emite a chave como identifier nu (`open`) quando for válido em TS,
  * senão como literal string (`'foo-bar'`).

package/bin/lib/gen-runner.mjs

@@ -250,8 +250,14 @@ function serializeDicts(dicts) {
       for (const k of keys) {
         values[k] = entries[k] ?? null
       }
-      // `doc` = entendimento do vocabulário inteiro (o que esse dict representa).
-      out[name] = { keys, values, doc: typeof params.doc === 'string' ? params.doc : null }
+      // `doc` = entendimento do vocabulário inteiro (o que esse dict representa);
+      // `presentation` = papel de apresentação declarado (ADR 0003) — null quando ausente.
+      out[name] = {
+        keys,
+        values,
+        doc: typeof params.doc === 'string' ? params.doc : null,
+        presentation: typeof params.presentation === 'string' ? params.presentation : null,
+      }
       continue
     }
     // Fallback: dict-like com `keys()` + `metaFor()`.

package/bin/lib/materialize.mjs

@@ -355,7 +355,10 @@ function reconcileFile(root, destination, item, mode, errors, changes) {
   if (currentFile === null) return
   const executable = destination.startsWith('.githooks/')
   const requiredMode = executable ? 0o755 : undefined
-  const modeIsCurrent = !executable || (currentFile.mode & 0o777) === requiredMode
+  // O Git rastreia só o bit de execução; o modo efetivo vem do umask do checkout (755 com 022,
+  // 775 com 002). Exigir 755 exato reprovava worktrees legítimas — o check aceita qualquer modo
+  // executável pelo dono, e a correção continua gravando 755 canônico.
+  const modeIsCurrent = !executable || (currentFile.mode & 0o100) !== 0
   const contentIsCurrent =
     currentFile.exists &&
     (executable ? currentFile.content === item.output : managedTextEquivalent(currentFile.content, item.output))
@@ -601,7 +604,7 @@ function reconcileSharedPrePush(root, mode, errors, changes) {
     }
     return
   }
-  if ((current.mode & 0o777) !== 0o755) {
+  if ((current.mode & 0o100) === 0) {
     if (mode === 'check') errors.push(`${destination}: modo executável incorreto.`)
     else if (replaceMaterializedFile(root, destination, expected, current, errors, { mode: 0o755 })) {
       changes.push(`corrigido modo executável de ${destination}`)

package/docs/adr/0003-dictionary-presentation-is-declared.md

@@ -0,0 +1,160 @@
+# ADR 0003 — A apresentação de um dicionário é declarada, não inferida
+
+- Status: aceita
+- Data: 2026-09-02
+
+## Contexto e forças
+
+`t.dict` declara vocabulário fechado uma única vez: código estável, rótulo, documentação de
+negócio e metadata livre por entrada. O manifest projeta esse vocabulário, a interface obtém
+rótulos por `labelFor`/`metaFor` e os campos e filtros resolvem opções por
+`options: { kind: 'dictionary', ref }` ou pela meta que viaja no schema do contrato.
+
+O que o dicionário não declara é como o valor deve aparecer. Cada tela decide sozinha se o valor
+vira texto, badge `outline`, badge tonal, ícone ou tooltip. Quando um agente gera a interface,
+ele infere essa apresentação a partir do nome do dicionário e do gosto do momento. Na Grand
+Brasil, “Pessoa física/Empresa” apareceu como texto secundário sob o nome enquanto
+“Prospect/Cliente” apareceu como badge: duas dimensões independentes (tipo e estágio) foram lidas
+como uma hierarquia, e a pessoa interpretou o tipo como explicação do estágio.
+
+O problema não pertence a essa tela. Ele se repete em toda coleção com mais de um dicionário,
+porque a única informação disponível para a interface é “este valor vem de um dicionário”, o que
+não distingue classificação de status, nem status de estágio. As forças em tensão:
+
+- o vocabulário precisa continuar declarado uma única vez, sem catálogo paralelo de cores e
+  ícones em cada tela;
+- o core do Opus precisa continuar isomórfico e sem React, porque o contrato viaja para servidor,
+  manifest, Lens e agentes;
+- dicionários existentes não podem mudar de aparência sem opt-in, e um dicionário sem metadata
+  precisa de um comportamento seguro;
+- ícone e cor não podem ser a única forma de comunicar um valor;
+- a orientação para agentes precisa ser verificável por avaliações, não apenas por prosa.
+
+## Alternativas consideradas
+
+### Manter a apresentação em cada tela
+
+É o estado atual. Preserva flexibilidade total, mas mantém a inferência como regra: cada agente
+decide de novo, e o mesmo dicionário aparece de formas diferentes em telas vizinhas. A observação
+registrada na Grand Brasil é a segunda ocorrência do mesmo defeito em superfícies distintas.
+Rejeitada.
+
+### Inferir o papel pelo nome ou pelas chaves
+
+Nomes como `Status` ou chaves como `open`/`closed` sugerem um status, mas `kind`, `type`,
+`category` e `stage` não se distinguem por convenção de nome, e a inferência falha justamente nos
+casos ambíguos que causaram o problema. Também moveria uma decisão de domínio para uma heurística
+do SDK. Rejeitada.
+
+### Tratar toda entrada de dicionário como badge
+
+Resolve a inconsistência ao custo de ruído: tabelas densas ficam cheias de chips, e a diferença
+entre classificação e estado desaparece. A convenção da casa reserva o badge tonal para estado
+semântico. Rejeitada.
+
+### Declarar o papel no dicionário e concentrar os defaults em um renderer
+
+O dicionário declara seu papel de apresentação; cada entrada pode declarar tom, ícone e uma
+descrição curta; um renderer compartilhado aplica os defaults e aceita override explícito. O
+manifest projeta a metadata e a skill de UI orienta o agente a partir dela. Aceita.
+
+## Decisão
+
+### Contrato
+
+O core ganha o módulo `dictionary` com o vocabulário fechado de apresentação, independente de
+React:
+
+- `DictPresentation = 'classification' | 'status' | 'stage' | 'plain'`, declarado no nível do
+  dicionário em `t.dict(entries, { presentation })`;
+- `DictTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger'`, declarado por entrada em
+  `tone`, explícito e restrito a status e estágios;
+- `icon` por entrada continua uma string, agora definida como identificador estável do catálogo
+  de ícones do Opus (`iconPickerIcons`); nome fora do catálogo não renderiza ícone;
+- `description` por entrada é o texto curto voltado à pessoa, usado pelo tooltip. `doc` continua
+  sendo o entendimento de negócio para manifest, Lens e agentes e não vira tooltip.
+
+`t.dict` valida `presentation` e `tone` em tempo de construção e falha com mensagem clara,
+inclusive quando `tone` aparece fora de status e estágio. A meta
+lógica passa a carregar `params.presentation`, e o manifest projeta `presentation` ao lado de
+`doc`. O tipo `DictEntryMeta` migra para o core e é reexportado pelo driver Zod; a API pública não
+muda.
+
+### Defaults de apresentação
+
+O core expõe `presentDictionaryValue(descriptor, value)`, a função pura que aplica a tabela de
+decisão:
+
+| Papel | Forma | Variante | Ícone | Tooltip |
+| --- | --- | --- | --- | --- |
+| `classification` | badge | `outline` | se declarado | se `description` acrescentar |
+| `status` | badge | tonal por `tone`, `neutral` sem tom | se declarado | se `description` acrescentar |
+| `stage` | badge | tonal por `tone`, `neutral` sem tom | se declarado | se `description` acrescentar |
+| `plain` ou ausente | texto | — | se declarado | se `description` acrescentar |
+
+Status e estágio nunca usam `outline`. Classificação não aceita `tone` (o construtor rejeita, e
+metadata vinda de fora é ignorada), porque a diferença visual entre classificação e estado é o
+que permite ler duas dimensões como independentes. Valor fora do dicionário é texto mesmo com
+`variant` sobreposto. Tooltip só
+existe quando `description` está presente e difere do rótulo. Valor fora do dicionário renderiza
+o código como texto, sem badge, sem ícone e sem tooltip.
+
+### Renderer
+
+`@softize/opus/ui/react` exporta `DictionaryValue`, que recebe o dicionário e o valor e aplica os
+defaults acima. Overrides são explícitos por props: `presentation`, `variant`, `icon`, `icons`,
+`tooltip` e `fallback`. O rótulo é sempre renderizado como texto; o ícone é decorativo
+(`aria-hidden`) e o badge com tooltip é focável para que a descrição alcance o teclado. O
+`Badge` ganha a variante tonal `danger`, completando a família `success`/`warning`/`info` sem
+reutilizar o `destructive` sólido.
+
+### Colunas declarativas
+
+`ActionList` passa a reconhecer que uma coluna do contrato mostra um dicionário por dois
+caminhos, sem configuração duplicada:
+
+1. zero-config: a coluna cujo campo no schema de saída carrega a meta de `t.dict` renderiza
+   `DictionaryValue` a partir dessa meta;
+2. explícito: `ListColumnSpec.dictionary` nomeia a referência registrada em
+   `TbdlibProvider dicts`, para colunas cujo schema de saída é uma string comum.
+
+`cells` continua vencendo qualquer coluna derivada. A única mudança de comportamento sem opt-in é
+que uma coluna de dicionário sem célula custom passa a mostrar o rótulo em vez do código; a
+apresentação visual (badge, tom, ícone, tooltip) exige `presentation` declarado. `type: 'badge'`
+continua funcionando como chip `outline`, agora com o rótulo quando a coluna é dicionário.
+
+### Orientação
+
+A skill `model-opus-dictionary` passa a exigir a classificação do papel de apresentação junto com
+a decisão dicionário × lookup × discriminante. A skill `build-opus-ui` ganha a tabela de decisão,
+exemplos positivos e negativos e avaliações que reprovam badge indiscriminado, dimensões
+misturadas na mesma célula, status apresentado como classificação, classificação tratada como
+metadado irrelevante, tooltip que repete o rótulo, ícone inventado, comunicação somente por cor ou
+ícone e excesso de badges em tabelas densas.
+
+## Consequências
+
+Dicionários existentes continuam renderizando como hoje até declararem `presentation`. Um
+dicionário com `color` livre não recebe tom automático: `color` permanece metadata livre, lida
+pela Lens, e o renderer honra apenas `tone`. Projetos que já usam `description` como texto de
+apoio em opções passam a ter o mesmo campo alimentando o tooltip, o que é o uso pretendido.
+
+O catálogo de ícones do Opus torna-se a fronteira do que um agente pode declarar. Vocabulário
+fora dele exige extensão do catálogo ou `icons` no renderer, nunca um nome inventado.
+
+A Lens ainda lê apenas `label` e `color` das entradas; projetar `presentation`, `tone` e `icon`
+no inspetor é evolução separada. Selects de formulário continuam mostrando somente rótulos.
+
+## Verificação
+
+- testes do core para a tabela de decisão nos quatro papéis, tom, ícone, descrição igual ao
+  rótulo e valor desconhecido;
+- testes de `t.dict` para validação de `presentation` e `tone` e para a meta projetada;
+- testes de React para `DictionaryValue` cobrindo os quatro papéis, overrides, texto sempre
+  presente, ícone decorativo e tooltip focável;
+- testes de `ActionList` para coluna zero-config, coluna com `dictionary` explícito, precedência
+  de `cells` e compatibilidade de `type: 'badge'`;
+- teste de manifest provando `presentation` projetado e entradas com `tone`, `icon` e
+  `description`;
+- validação das skills com casos positivo, negativo e de execução;
+- typecheck, suíte do pacote, `opus check`, `opus copy --check` e gates de materialização.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "12.7.1",
+  "version": "12.8.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/registry/skills/build-opus-ui/SKILL.md

@@ -2,6 +2,7 @@
 name: build-opus-ui
 description: Constrói interface contract-driven com hooks, forms, listas, views e componentes de @softize/opus/ui. Use ao implementar ou alterar telas que consomem actions Opus.
 ---
+<!-- softize-skill-route: $model-opus-dictionary -->
 
 # Construir UI Opus
 
@@ -14,33 +15,50 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
 
 1. Identificar o contrato e o kind da action; corrigir lacuna do contrato na fonte em vez
    de compensá-la com tipo ou validação na UI.
-2. Usar os hooks e componentes do catálogo `@softize/opus/ui/react` adequados ao kind.
-3. Tratar página, filtro, seleção e modal importante como estado navegável por URL quando
+2. Usar os hooks e componentes do catálogo `@softize/opus/ui/react` adequados ao kind. Rótulo e
+   mensagem de vocabulário fechado vêm do dicionário do domínio (`labelFor`/`metaFor`); ao
+   encontrar catálogo repetido à mão ou vocabulário ainda sem dicionário, carregar
+   `$model-opus-dictionary`.
+3. Apresentar valor de dicionário por `DictionaryValue` ou pela coluna de `ActionList`, que
+   aplicam o papel declarado em `presentation` (classificação em badge `outline`, status e estágio
+   em badge tonal, `plain` em texto). Não escolher badge, tom ou ícone pelo nome do dicionário:
+   dicionário sem papel declarado renderiza texto e pede classificação por
+   `$model-opus-dictionary` antes de qualquer destaque visual. Sobrepor os defaults só com motivo
+   explícito nas props do renderer.
+4. Dar a cada dimensão independente usada para comparação ou filtro um campo, coluna ou espaço
+   identificável próprio, com rótulo. Hierarquia tipográfica (texto secundário sob um nome) não
+   pode fazer uma dimensão parecer explicação de outra. Cor e ícone reforçam; o texto do valor
+   permanece sempre presente.
+5. Deixar ausência, paginação e largura de filtro com o pattern: célula e `DetailField` já
+   representam valor ausente (`EmptyValue`, `empty` para o significado do domínio); listas
+   paginam pela primitiva `Pagination`; selects inline de filtro têm largura fixa. Não reescrever
+   esses defaults na tela.
+6. Tratar página, filtro, seleção e modal importante como estado navegável por URL quando
    o produto precisa de deep link, back/forward ou refresh.
-4. Compor páginas com `Page` e seu teto centralizado padrão de `72rem`. Usar
+7. Compor páginas com `Page` e seu teto centralizado padrão de `72rem`. Usar
    `ContentHeader` em seções que precisam da mesma estrutura de título, descrição,
    metadados e ações; ajustar `level` pela hierarquia semântica, não pelo destaque visual.
-5. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas
+8. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas
    seu interior.
-6. Não definir a fonte raiz em uma biblioteca ou componente. O navegador e a aplicação são
+9. Não definir a fonte raiz em uma biblioteca ou componente. O navegador e a aplicação são
    responsáveis por `font-size` em `html`; medidas escaláveis da UI usam `rem` ou a escala
    relativa do Tailwind. Reservar `px` a hairlines e compensações presas à geometria da borda,
    com justificativa e cobertura explícitas.
-7. Evoluir um pattern compartilhado apenas quando a recorrência e o contrato estiverem claros.
-8. Tratar tokens de superfície como pares indivisíveis no mesmo fragmento de classes:
+10. Evoluir um pattern compartilhado apenas quando a recorrência e o contrato estiverem claros.
+11. Tratar tokens de superfície como pares indivisíveis no mesmo fragmento de classes:
    `bg-card text-card-foreground` e `bg-popover text-popover-foreground`. Não depender da
    igualdade atual com `--foreground`, porque o app pode sobrescrever cada par.
-9. Usar diretamente a escala `rounded-*`; não criar radius por nome de componente quando
+12. Usar diretamente a escala `rounded-*`; não criar radius por nome de componente quando
    `rounded-xs` a `rounded-2xl` já expressam a forma. Escolher o degrau pela escala visual:
    detalhes e itens internos tendem a `xs`/`sm`, controles e flutuantes compactos a `md`,
    molduras estruturais a `lg`, e superfícies principais ou modais a `xl`. Essa associação
    orienta o default, não cria uma restrição semântica. Em aninhamento, evitar moldura dupla e
    reduzir o raio interno; em grupos conectados, remover os raios das arestas internas. Tamanho
    e forma permanecem eixos separados; usar `shape="pill"` quando a pílula for intencional.
-10. Distinguir uma região disponível para criação ou vínculo, representada por `Empty` com
+13. Distinguir uma região disponível para criação ou vínculo, representada por `Empty` com
     moldura tracejada, de um resultado vazio dentro de uma estrutura existente, que preserva
     a moldura sólida dessa estrutura.
-11. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
+14. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
 
 ## Verificação
 
@@ -58,6 +76,9 @@ Inspecionar visualmente a rota real e validar navegação por URL quando aplicá
 - Não criar fetch, schema ou tipo paralelo ao contrato.
 - Não copiar componente da lib para customizar sem antes verificar extensão/composição.
 - Não forçar modal roteável quando o estado é efêmero e sem valor de navegação.
+- Não inferir apresentação de dicionário: nem badge para todo valor, nem tom ou ícone
+  inventados, nem tooltip que repete o rótulo.
+- Não repetir fallback de ausência, paginador ou largura de filtro que o pattern já resolve.
 
 ## Recursos
 

package/registry/skills/build-opus-ui/references/evaluations.md

@@ -17,3 +17,28 @@
 - Reprova: reconstruir manualmente o container de página, usar `Empty` tracejado como vazio de
   tabela, alinhar toda coluna numérica à direita por inferência ou destacar “Cancelar” como ação
   primária em modal.
+- Execução de dicionários: montar a lista de clientes com “Pessoa física/Empresa” e
+  “Prospect/Cliente”; provar que o tipo ocupa a coluna “Tipo” como classificação (badge `outline`
+  com os ícones declarados `user` e `building`), que o estágio ocupa a coluna “Estágio” como badge
+  tonal sem `outline`, que nenhuma das duas usa `cells`, que o texto do valor está presente e que
+  não há tooltip em “Pessoa física/Empresa” quando a descrição não acrescenta ao rótulo.
+- Reprova: envolver todo valor de dicionário em badge sem papel declarado, ou escolher a variante
+  pelo nome do dicionário.
+- Reprova: colocar duas dimensões independentes na mesma célula sem identificação, como o tipo em
+  texto secundário sob o nome enquanto o estágio ganha badge.
+- Reprova: apresentar status ou estágio com `outline`, ou tratar uma classificação como metadado
+  irrelevante em texto muted quando ela é dimensão de comparação ou filtro.
+- Reprova: tooltip cuja descrição apenas repete o rótulo, ou `doc` de negócio exibido como tooltip.
+- Reprova: ícone inferido ou inventado pela IA, fora do catálogo `iconPickerIcons` ou não declarado
+  na entrada do dicionário.
+- Reprova: comunicar um valor somente por cor ou ícone (`Dot` sem texto, badge vazio).
+- Reprova: tabela densa com badge em todas as colunas de dicionário quando só status e estágio
+  pedem destaque.
+- Reprova: repetir à mão o fallback de valor ausente (`item.email === '' ? '—' : item.email`) em
+  células ou campos quando a coluna, o `DetailField` ou `EmptyValue` já representam a ausência.
+- Reprova: montar um paginador paralelo com `Button` dentro de `ActionList` ou de outra lista em
+  vez de compor `Pagination`.
+- Reprova: prender o número de página a largura fixa (`size-7 p-0`), fazendo 5726 e 5727 se
+  sobreporem.
+- Reprova: dimensionar select inline de filtro pelo conteúdo ou pela label (`min-w-*` solto,
+  largura calculada), em vez da largura fixa do pattern.

package/registry/skills/build-opus-ui/references/ui-patterns.md

@@ -42,4 +42,89 @@
   Quando uma tabela, card ou grupo existente apenas não tem resultados, manter sua moldura
   sólida e renderizar o vazio estrutural dentro dela; não trocar toda ausência de dados por
   `Empty`.
+- Valor de dicionário é apresentado por `DictionaryValue` ou pela coluna de `ActionList`; o
+  papel vem de `presentation` no `t.dict`, nunca do nome do dicionário nem do gosto da tela.
+- Valor ausente (`null`, `undefined`, vazio, só espaços) tem representação padrão: coluna de
+  `ActionList` e `DetailField` já mostram travessão ou “Não informado”; o significado do domínio
+  entra por `ListColumnSpec.empty` ou `DetailField empty`, e renderer customizado usa
+  `EmptyValue`. `0` e `false` são valores. Não repetir a condicional de `—` em cada célula.
+- Paginação é a primitiva `Pagination`, inclusive dentro de `ActionList`. Número de página tem
+  largura mínima e cresce com os dígitos; só as setas são quadradas. Não montar paginador com
+  `Button` nem prender números a `size-*`.
+- Select inline de filtro tem largura fixa (`w-40`; lookup e múltiplo `w-52`): a label trunca, o
+  valor trunca no trigger e a opção inteira fica na lista. Não dimensionar filtro pelo conteúdo
+  nem pela label; o modal usa `w-full`.
 - Catálogo e API efetivos vêm dos exports da versão instalada, não de memória ou exemplo antigo.
+
+## Dicionários e dimensões
+
+O dicionário declara o papel; a tela só escolhe onde o valor fica. Tabela de decisão aplicada
+por `DictionaryValue` e pelas colunas de `ActionList`:
+
+| Papel declarado | Exemplos | Forma | Variante | Ícone | Tooltip |
+|---|---|---|---|---|---|
+| `classification` | Tipo de cliente, categoria, natureza | Badge | `outline`; ignora `tone` | se a entrada declara `icon` do catálogo | se `description` acrescenta ao rótulo |
+| `status` | Aberto, resolvido, degradado | Badge | tonal pelo `tone`; `neutral` sem tom; nunca `outline` | idem | idem |
+| `stage` | Prospect, cliente; etapa do funil | Badge | igual a `status` | idem | idem |
+| `plain` ou ausente | Fonte, formato, período | Texto | — | idem | idem |
+
+Regras que não dependem da tabela:
+
+- Dimensão independente usada para comparação ou filtro ocupa coluna, campo ou espaço
+  identificável próprio, com rótulo. Duas dimensões na mesma célula sem identificação viram
+  hierarquia falsa.
+- O texto do valor está sempre presente; cor e ícone reforçam, não substituem.
+- Tabela densa com várias colunas de dicionário mantém badge só nas dimensões de status e estágio;
+  classificações secundárias podem ficar em texto (`presentation="plain"` na ocorrência) quando o
+  excesso de chips prejudica a leitura.
+- Sem `presentation` declarado, o valor é texto. A correção é classificar o dicionário
+  (`$model-opus-dictionary`), não escolher uma variante na tela.
+
+Exemplo correto — tipo e estágio em colunas próprias, apresentação do dicionário:
+
+```ts
+export const customerKindDict = t.dict(
+  { pf: { label: 'Pessoa física', icon: 'user' }, pj: { label: 'Empresa', icon: 'building' } },
+  { doc: 'Natureza da parte no cadastro global.', presentation: 'classification' },
+)
+export const customerStageDict = t.dict(
+  { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', tone: 'success' } },
+  { doc: 'Estágio comercial atual da parte.', presentation: 'stage' },
+)
+// contrato:
+//   columns: [{ key: 'name' }, { key: 'kind', label: 'Tipo' }, { key: 'stage', label: 'Estágio' }]
+//   output: z.object({ kind: customerKindDict.zod(), stage: customerStageDict.zod() })
+// tela: <ActionList action={customerListContract} input={{}} /> — sem cells para kind e stage
+```
+
+Exemplos incorretos:
+
+```tsx
+// Dimensões misturadas: o tipo vira "explicação" do nome; o estágio vira badge à mão.
+cells={{
+  name: (item) => (
+    <div>
+      <p className="font-medium">{item.name}</p>
+      <span className="text-xs text-muted-foreground">
+        {item.kind === 'pj' ? 'Empresa' : 'Pessoa física'}
+      </span>
+    </div>
+  ),
+  stage: (item) =>
+    item.stage === 'customer'
+      ? <Badge variant="secondary">Cliente</Badge>
+      : <Badge variant="outline">Prospect</Badge>,
+}}
+
+// Badge para tudo: fonte, formato e período viram chips sem papel declarado.
+<Badge variant="outline">{reportFormatDict.labelFor(item.format)}</Badge>
+
+// Status apresentado como classificação (outline) e ícone inventado fora do catálogo.
+<Badge variant="outline"><Sparkles /> {statusDict.labelFor(item.status)}</Badge>
+
+// Tooltip que repete o rótulo; cor como único sinal.
+<Tooltip>
+  <TooltipTrigger><Dot variant="success" /></TooltipTrigger>
+  <TooltipContent>Cliente</TooltipContent>
+</Tooltip>
+```

package/registry/skills/implement-opus-change/SKILL.md

@@ -6,6 +6,7 @@ description: Implementa uma mudança em projeto baseado no Opus preservando cont
 <!-- softize-skill-route: $test-opus-action -->
 <!-- softize-skill-route: $build-opus-ui -->
 <!-- softize-skill-route: $create-opus-seed -->
+<!-- softize-skill-route: $model-opus-dictionary -->
 
 # Implementar mudança Opus
 
@@ -26,9 +27,9 @@ dependências server-only, bindings registrados, testes e gates verdes.
 2. Modelar primeiro o contrato observável: nome, descrição, input, output, erros e metadata.
 3. Manter código compartilhável fora de banco, segredo, filesystem e drivers server-only.
 4. Implementar o binding e registrar o `ActionDef` no domínio/runtime conforme a topologia local.
-5. Carregar e seguir `$create-opus-action`, `$test-opus-action`, `$build-opus-ui` ou
-   `$create-opus-seed` antes
-   do passo correspondente quando a mudança entrar nesses workflows especializados.
+5. Carregar e seguir `$create-opus-action`, `$test-opus-action`, `$build-opus-ui`,
+   `$create-opus-seed` ou `$model-opus-dictionary` antes do passo correspondente quando a
+   mudança entrar nesses workflows especializados.
 6. Atualizar manifest, docs geradas e exemplos somente pelos comandos do repo.
 
 ## Verificação

package/registry/skills/model-opus-dictionary/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: model-opus-dictionary
+description: Modela vocabulário fechado de domínio com t.dict, schema derivado e registro no domínio, decidindo entre dicionário, lookup e discriminante local. Use ao introduzir ou migrar códigos estáveis que contrato, regra, interface ou auditoria reutilizam.
+---
+
+# Modelar dicionário Opus
+
+## Resultado
+
+Entregar o vocabulário declarado uma única vez: códigos estáveis com rótulo e documentação em
+`t.dict`, schema derivado por `.zod()`, registro em `defineDomain({ dicts })` e consumidores lendo
+da mesma instância, sem catálogo repetido em enum, opção estática ou formatador local.
+
+## Entradas
+
+- códigos, rótulos e significado de negócio do vocabulário, com quem os reutiliza;
+- contrato, regra, interface ou auditoria que hoje repetem o catálogo;
+- gates do projeto para representações legadas (baseline de `z.enum`/opções estáticas), quando
+  existirem.
+
+## Procedimento
+
+1. Classificar o vocabulário antes de codificar:
+   - **dicionário** — fechado nesta versão, códigos estáveis, significado de domínio reutilizado
+     por mais de um consumidor;
+   - **lookup** — administrável, pesquisável, autorizável ou vindo do banco: expor por action
+     `kind: 'list'`/lookup, nunca por opção estática;
+   - **discriminante local** — enum ou literal privado de transporte/controle que não repete um
+     catálogo apresentado nem uma regra compartilhada: permanece local e fora do dicionário.
+2. Declarar o dicionário com `t.dict`, no módulo de dicionários do domínio: chave é código de
+   máquina persistível; rótulo, documentação e demais metadata evoluem sem migração de dados.
+3. Classificar o papel de apresentação e declará-lo em `presentation`, porque a interface não o
+   infere:
+   - **classification** — tipo, categoria ou natureza: dimensão estável de comparação;
+   - **status** — situação operacional que muda com o tempo;
+   - **stage** — etapa de um ciclo ou funil;
+   - **plain** — valor que só precisa ser legível (o mesmo efeito de omitir).
+   Por entrada, declarar `tone` somente em status e estágio, `icon` somente com nome existente no
+   catálogo `iconPickerIcons`, e `description` somente quando acrescentar algo ao rótulo. `doc`
+   continua sendo o entendimento de negócio para manifest e Lens; não é tooltip.
+4. Derivar o schema por `.zod()` e usá-lo em todo contrato que valide o código; não redeclarar a
+   união em `z.enum` nem em tipo literal paralelo.
+5. Registrar o dicionário em `defineDomain({ dicts })` para que manifest e Lens o projetem.
+6. Migrar os consumidores para a mesma instância: `DictionaryValue` ou a coluna de `ActionList`
+   para apresentar o valor, `labelFor`/`metaFor` nas mensagens; remover o catálogo repetido de
+   formatadores, selects, mapas de variante de badge e comparações.
+7. Manter autorização e invariantes no servidor: metadata de dicionário orienta a interface, mas
+   não é barreira de integridade. Quando auditoria precisar preservar o que a pessoa viu,
+   armazenar o código e um snapshot do texto no momento do evento.
+8. Ao reduzir uma representação legada coberta por baseline de gate, apertar o baseline no mesmo
+   diff. Ao introduzir uma nova ocorrência fora do dicionário, classificá-la e justificá-la no
+   próprio diff; atualizar baseline não é correção automática.
+
+## Verificação
+
+Rodar `opus check`, typecheck e os testes afetados; conferir no manifest que o domínio projeta o
+dicionário com `presentation`; provar que o schema rejeita código fora do catálogo e que a
+interface obtém rótulo e apresentação da mesma instância. Se a mudança alterou texto humano de
+contrato ou componente mapeado, regenerar com `opus copy` e executar os checks de copy do projeto.
+
+## Limites
+
+- Não migrar todos os enums de uma vez; a adoção é incremental e cada ocorrência exige
+  classificação própria.
+- Não transformar discriminante local legítimo em dicionário por semelhança superficial.
+- Não usar tabela ou action de lookup para valores compilados e estáveis; nem dicionário para
+  dados administráveis de runtime.
+- Não tratar metadata de dicionário como autorização ou invariante de integridade.
+- Não omitir `presentation` esperando que a tela deduza o papel pelo nome do dicionário; sem
+  papel declarado, o valor é texto.
+- Não declarar `tone` em classificação, nem `icon` fora do catálogo, nem `description` que
+  repita o rótulo.
+
+## Recursos
+
+- Use [avaliações](references/evaluations.md) ao evoluir esta skill.

package/registry/skills/model-opus-dictionary/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Modelar dicionário Opus"
+  short_description: "Declara vocabulário fechado uma única vez com t.dict"
+  default_prompt: "Use $model-opus-dictionary para introduzir ou migrar este vocabulário fechado."

package/registry/skills/model-opus-dictionary/references/evaluations.md

@@ -0,0 +1,18 @@
+# Avaliações
+
+- Positiva: “Os motivos de conflito de clientes aparecem repetidos no contrato, na UI e nas
+  mensagens; centralize esse vocabulário.” Deve disparar, declarar `t.dict`, derivar `.zod()`,
+  registrar em `defineDomain({ dicts })` e migrar os consumidores para a mesma instância.
+- Negativa: “Adicione um campo de status interno `pending | done` ao envelope de transporte desta
+  fila.” Não deve disparar quando o par é discriminante privado que não repete catálogo
+  apresentado nem regra compartilhada.
+- Execução: migrar um `z.enum` legado coberto por baseline, apertar o baseline no mesmo diff e
+  provar que manifest projeta o dicionário, que o schema rejeita código fora do catálogo e que a
+  interface lê rótulos por `labelFor`/`metaFor`.
+- Execução de apresentação: dado um cadastro com “Pessoa física/Empresa” e “Prospect/Cliente”,
+  declarar o primeiro como `classification` com ícones `user` e `building` do catálogo e o segundo
+  como `stage` com `tone` explícito, sem `description` que repita o rótulo; provar que o manifest
+  projeta `presentation` e que `t.dict` rejeita `presentation` ou `tone` fora do vocabulário.
+- Reprova: declarar `tone` em uma classificação, inventar `icon` fora do catálogo, copiar `doc`
+  para `description` ou deixar `presentation` ausente em um status esperando que a tela infira o
+  badge.