@softize/opus 12.10.0 → 13.0.0

package/package.json

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

package/registry/instructions/opus.md

@@ -15,6 +15,11 @@ artefatos de agentes fica em `base.json`; cada app Opus mantém seu marcador `op
 - Manter contrato compartilhável separado de banco, segredo e driver server-only; usar
   `defineContract` com `bindAction` quando cliente e servidor consomem a mesma action.
 - Não duplicar schemas, tipos de transporte, validação ou fetch que o contrato já fornece.
+- Em UI semântica, declarar primeiro `context` (`neutral`, `primary`, `info`, `success`, `warning`
+  ou `danger`) e usar `variant` somente para o tratamento visual (`solid`, `subtle`, `outline`,
+  `ghost` ou `link`). Dicionários de status e estágio declaram `context`; `tone` e variantes
+  semânticas antigas são apenas compatibilidade de migração. `destructive` permanece uma
+  propriedade comportamental de actions e se projeta visualmente como `danger`.
 - Declarar datasets persistentes com `defineSeed` + `bindSeed`, registrá-los em `opus.config.ts`
   e operá-los por `opus seed`; não criar comandos de seed paralelos nem reset implícito.
 - Regenerar o inventário com `opus copy` quando mudar copy em contrato ou componente Opus

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

@@ -19,46 +19,54 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
    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
+3. Em componentes semânticos, declarar `context` antes de escolher `variant`: `context` comunica
+   `neutral`, `primary`, `info`, `success`, `warning` ou `danger`; `variant` descreve somente o
+   tratamento `solid`, `subtle`, `outline`, `ghost` ou `link`, conforme o subconjunto aceito pelo
+   componente. Não usar `variant="success"`, `variant="destructive"` nem `tone` em código novo.
+   `destructive` permanece metadata comportamental de action e se projeta como `context="danger"`.
+4. 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:
+   em badge `context + subtle`, `plain` em texto). Não escolher badge, contexto 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
+5. 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á
+6. 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
+7. 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.
-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.
-8. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas
+8. Compor superfícies pela gramática estrutural do catálogo: `Page` contém `PageHeader` e
+   `PageBody`; `Content` contém `ContentHeader` e `ContentBody`; Card, Drawer e Pane usam seus
+   respectivos `*Body`. Para o caso direto, usar a sintaxe abreviada de `Page` ou `Content` com
+   `title`, `description`, `meta` e `actions`; não misturá-la com o header explícito. Ajustar o
+   nível do heading pela hierarquia semântica, não pelo destaque visual. O `Page` mantém seu teto
+   centralizado padrão de `80rem`.
+9. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas
    seu interior.
-9. Não definir a fonte raiz em uma biblioteca ou componente. O navegador e a aplicação são
+10. 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.
-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:
+11. Evoluir um pattern compartilhado apenas quando a recorrência e o contrato estiverem claros.
+12. 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.
-12. Usar diretamente a escala `rounded-*`; não criar radius por nome de componente quando
+13. 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.
-13. Distinguir uma região disponível para criação ou vínculo, representada por `Empty` com
+14. 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.
-14. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
+15. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
 
 ## Verificação
 
@@ -76,8 +84,11 @@ 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
+- Não inferir apresentação de dicionário: nem badge para todo valor, nem contexto ou ícone
   inventados, nem tooltip que repete o rótulo.
+- Não usar nomes de compatibilidade (`tone`, `variant="success"`, `variant="destructive"`) em
+  código novo; consultar a página “Contexto & Variante” do catálogo quando a combinação não estiver
+  clara.
 - 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

@@ -3,11 +3,14 @@
 - Dispara: “Monte a tela de edição usando a form action do Opus.”
 - Não dispara: “Ajuste o CSS de um e-mail estático.”
 - Execução: implementar uma lista com modal roteável e provar loading, erro, vazio e back.
-- Execução estrutural: montar uma página de relatório com `Page`, `ContentHeader` em uma seção,
-  `ActionFilterBar` separado do renderer, `ItemGroup` para uma coleção secundária e um
-  `ActionFormDialog`; provar teto padrão de `72rem`, hierarquia por `level`, vazio estrutural
-  sólido, `Empty` apenas para criação ou vínculo, números sem alinhamento inferido e cancelamento
-  `ghost` no modal.
+- Execução estrutural: montar uma página de relatório com `Page > PageHeader + PageBody`, uma seção
+  `Content > ContentHeader + ContentBody`, `ActionFilterBar` separado do renderer, `ItemGroup` para
+  uma coleção secundária e um `ActionFormDialog`; provar teto padrão de `80rem`, hierarquia por
+  `level`, vazio estrutural sólido, `Empty` apenas para criação ou vínculo, números sem alinhamento
+  inferido e cancelamento `ghost` no modal.
+- Execução abreviada: montar outra página com `<Page title description actions>` e uma seção com
+  `<Content title description actions>`, provando que ambas produzem a mesma anatomia e que o lint
+  rejeita a mistura entre props abreviadas e headers explícitos.
 - Execução de forma: compor uma tabela dentro de Card sem moldura duplicada, manter a moldura
   estrutural standalone em `rounded-lg` e os controles internos em `rounded-md`.
 - Reprova: criar uma casca `bg-card` que herda o texto global ou introduzir `rounded-widget`
@@ -17,11 +20,19 @@
 - 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.
+- Reprova: deixar `ContentHeader` fora de `Content`, omitir `PageBody`/`ContentBody` na composição
+  explícita, usar `CardContent`/`PaneContent` em código novo ou tratar `DialogContent` como Body.
 - 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.
+- Execução de contexto: montar ações, badges, alertas e indicadores com o mesmo estado `warning`;
+  exigir `context="warning"`, variantes visuais coerentes por componente e tokens da mesma família.
+  Uma exclusão continua `destructive` no contrato, mas usa `context="danger"` na projeção visual.
+- Reprova: usar `tone` em componente novo, `variant="success"`, `variant="warning"` ou
+  `variant="destructive"`; usar `light`/`dark` como contexto; ou tratar `secondary` como sinônimo
+  de estado neutro.
 - 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

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

@@ -4,12 +4,24 @@
 - Campos, labels, mensagens e invalidações pertencem ao contrato quando são parte da
   operação, não a uma tela isolada.
 - URL representa estado que precisa sobreviver a refresh, deep link ou histórico.
-- `Page` fornece o `<main>`, o container centralizado com teto padrão de `72rem` e o header
-  de página. Alterar `className` apenas quando a superfície tiver uma necessidade real de
-  largura; não reconstruir esse container em cada rota.
-- `ContentHeader` compartilha a composição de título, descrição, metadados e ações entre
-  páginas e seções. `variant` define o destaque visual; `level` preserva separadamente a
-  hierarquia semântica do heading.
+- `Page` fornece o `<main>` e o container centralizado com teto padrão de `80rem`. Sua forma
+  explícita é `Page > PageHeader (PageTitle, PageDescription, PageMeta, PageActions) + PageBody`;
+  `title`, `description`, `meta` e `actions` no próprio `Page` são a abreviação para o caso direto.
+  Não misturar as duas formas. Alterar `className` apenas quando a superfície tiver uma necessidade
+  real de largura; não reconstruir esse container em cada rota.
+- `PageState` substitui todo o conteúdo principal quando a página carrega, falha ou está vazia. Na
+  forma curta ele pode ser escrito como filho direto de `Page`, que cria o `PageBody`; na forma
+  explícita, fica dentro de `PageBody`. O cabeçalho permanece visível. Estados de seção ou coleção
+  continuam em `DataState`, `ActionView`, `ActionList` ou `Alert`; não elevar uma falha parcial a
+  estado da página.
+- `Content` delimita uma seção e segue a mesma anatomia: `Content > ContentHeader (ContentTitle,
+  ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader` nunca fica
+  solto. `title`, `description`, `meta` e `actions` no `Content` são a abreviação para o caso
+  direto e não podem ser misturados ao header explícito. `level` preserva a hierarquia semântica
+  do heading.
+- Card, Drawer e Pane nomeiam a região principal como `CardBody`, `DrawerBody` e `PaneBody`.
+  `*Content` permanece reservado a raízes técnicas ou painéis cujo papel não é o corpo de uma
+  estrutura, como `DialogContent`, `PopoverContent` e `TabsContent`.
 - Componentes compartilhados não impõem margem externa; páginas e shells compõem layout.
 - A fonte raiz pertence ao navegador e à aplicação. Medidas escaláveis usam `rem` ou a escala
   relativa do Tailwind; `px` fica restrito a hairlines e compensações ligadas a essas bordas.
@@ -55,18 +67,23 @@
   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.
+- Em componentes semânticos, `context` responde por que há destaque e `variant` responde como ele
+  aparece. O vocabulário canônico é `neutral | primary | info | success | warning | danger`; as
+  variantes visuais são `solid | subtle | outline | ghost | link`, limitadas por componente.
+  `light`/`dark` são temas, `secondary` não substitui estado neutro e `destructive` é comportamento
+  de action projetado visualmente como `danger`.
 
 ## 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 |
+| Papel declarado | Exemplos | Forma | Contexto | Variante | Ícone | Tooltip |
+|---|---|---|---|---|---|---|
+| `classification` | Tipo de cliente, categoria, natureza | Badge | `neutral` | `outline`; ignora `context` da entrada | se a entrada declara `icon` do catálogo | se `description` acrescenta ao rótulo |
+| `status` | Aberto, resolvido, degradado | Badge | pela entrada; `neutral` por padrão | `subtle`; nunca `outline` | idem | idem |
+| `stage` | Prospect, cliente; etapa do funil | Badge | igual a `status` | `subtle` | idem | idem |
+| `plain` ou ausente | Fonte, formato, período | Texto | — | — | idem | idem |
 
 Regras que não dependem da tabela:
 
@@ -88,7 +105,7 @@ export const customerKindDict = t.dict(
   { doc: 'Natureza da parte no cadastro global.', presentation: 'classification' },
 )
 export const customerStageDict = t.dict(
-  { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', tone: 'success' } },
+  { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', context: 'success' } },
   { doc: 'Estágio comercial atual da parte.', presentation: 'stage' },
 )
 // contrato:
@@ -112,7 +129,7 @@ cells={{
   ),
   stage: (item) =>
     item.stage === 'customer'
-      ? <Badge variant="secondary">Cliente</Badge>
+      ? <Badge context="neutral" variant="solid">Cliente</Badge>
       : <Badge variant="outline">Prospect</Badge>,
 }}
 
@@ -124,7 +141,13 @@ cells={{
 
 // Tooltip que repete o rótulo; cor como único sinal.
 <Tooltip>
-  <TooltipTrigger><Dot variant="success" /></TooltipTrigger>
+  <TooltipTrigger><Dot context="success" /></TooltipTrigger>
   <TooltipContent>Cliente</TooltipContent>
 </Tooltip>
+
+// Contexto semântico usado como variante: a IA perdeu um eixo da API.
+<Badge variant="success">Concluído</Badge>
+
+// Risco comportamental usado como nome visual.
+<Button variant="destructive">Excluir</Button>
 ```

package/registry/skills/maintain-opus-docs/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: maintain-opus-docs
+description: Cria, reorganiza e revisa a documentação publicada do Opus, incluindo páginas conceituais, famílias de componentes, exemplos vivos, props, navegação e redirects. Use ao documentar ou revisar o catálogo e os guias de @softize/opus.
+---
+
+# Manter documentação Opus
+
+## Resultado
+
+Entregar documentação que ajuda a pessoa a escolher e usar o recurso pelo caminho canônico,
+preserva a relação entre páginas, catálogo e API pública e continua verificável pelos gates do
+repositório.
+
+## Entradas
+
+Identificar o público, a tarefa que levou a pessoa à página e o conjunto de APIs públicas coberto.
+Ler [padrão editorial](references/editorial-standard.md) antes de escrever. Inspecionar o componente,
+seus testes, metadata, exportações e páginas relacionadas; a documentação não define um contrato que
+o código não sustenta.
+
+## Procedimento
+
+1. Inventariar as páginas, componentes e rotas afetadas antes de alterar a organização.
+2. Decidir a unidade da página pelo conceito ensinado. Manter componentes compostos da mesma família
+   na mesma página quando compartilham decisão de uso e vocabulário; separar conceitos independentes.
+3. Conduzir a leitura do caso comum para o específico: situação reconhecível, escolha recomendada,
+   exemplo mínimo, composição, variações, comportamentos e referência.
+4. Escrever cada seção para funcionar por link direto, repetindo apenas o contexto indispensável.
+5. Usar exemplos pequenos, executáveis e coerentes entre si. Explicar antes o que observar e depois
+   o comportamento automático ou a consequência que não esteja evidente no código.
+6. Manter uma tabela de propriedades identificada para cada componente público coberto pela página.
+   Não usar uma tabela genérica para contratos diferentes.
+7. Ao renomear ou agrupar páginas, atualizar registry, metadata, navegação e links; preservar slugs
+   publicados por redirect ou alias quando o endereço canônico mudar.
+8. Reler todo o texto no fluxo renderizado e aplicar o checklist do padrão editorial linha por linha.
+9. Atualizar testes, inventário de copy e projeções afetadas pelo mesmo conjunto de mudanças.
+
+## Decisões
+
+- A página ensina uma decisão de uso; a tabela de props documenta o contrato. Nenhuma substitui a
+  outra.
+- O exemplo canônico aparece antes da enumeração de possibilidades. Alternativas entram no ponto em
+  que a pessoa precisa escolher entre elas.
+- Defaults, efeitos automáticos, limites e riscos ficam próximos do exemplo em que se tornam
+  relevantes.
+- Páginas conceituais podem ser extensas quando constroem um fluxo completo; páginas de componente
+  permanecem compactas e usam previews para carregar parte da explicação.
+- Inspiração editorial externa orienta progressão e clareza, não autoriza copiar texto, idioma,
+  personalidade promocional ou convenções incompatíveis com o Opus.
+
+## Verificação
+
+Executar `node scripts/audit-docs.mjs "$(git rev-parse --show-toplevel)"` a partir do diretório
+desta skill e, depois, os testes do renderer e do catálogo, typecheck, `opus check` e
+`opus copy --check`. Conferir
+que todos os previews renderizam, que cada API pública documentada possui sua própria referência,
+que nenhum arquivo publicado ficou órfão e que links e redirects chegam à página esperada. Fazer uma
+passada visual nas páginas alteradas e registrar qualquer limitação que o gate automático não cubra.
+
+## Saída
+
+Informar páginas criadas, agrupadas ou reescritas, decisões editoriais aplicadas, verificações
+executadas e pendências reais. Em revisão ampla, fornecer o inventário coberto para tornar explícito
+o significado de “toda a documentação”.
+
+## Limites
+
+- Não inventar comportamento, prop, default ou recomendação a partir do nome do componente.
+- Não transformar a documentação em sequência de tabelas nem antecipar a referência antes do modelo
+  mental necessário.
+- Não criar uma página por exportação quando os símbolos formam uma única família de uso.
+- Não esconder APIs públicas de uma família em uma tabela de props compartilhada.
+- Não editar projeção gerada quando existe fonte canônica.
+- Não promover alteração de documentação a release, publicação ou push sem autorização específica.
+
+## Recursos
+
+- Ler [padrão editorial](references/editorial-standard.md) para anatomia, tom e revisão linha por
+  linha.
+- Usar [avaliações](references/evaluations.md) ao criar ou alterar substancialmente esta skill.
+- Usar `scripts/audit-docs.mjs [raiz-do-repositório]` para detectar páginas órfãs, fences
+  incompletos, saltos de heading e nomes genéricos de referência. O script complementa a leitura;
+  não decide clareza, progressão ou exatidão técnica.

package/registry/skills/maintain-opus-docs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Manter documentação Opus"
+  short_description: "Escreve e revisa as docs publicadas do Opus"
+  default_prompt: "Use $maintain-opus-docs para revisar esta documentação do Opus."

package/registry/skills/maintain-opus-docs/references/editorial-standard.md

@@ -0,0 +1,85 @@
+# Padrão editorial da documentação Opus
+
+## Anatomia da página
+
+Adotar a menor sequência que forme o modelo mental necessário:
+
+1. **Situação e escolha:** dizer o que o recurso resolve e quando escolhê-lo. Contrastar com o
+   componente vizinho apenas quando essa distinção evita uma decisão errada.
+2. **Exemplo canônico:** mostrar o menor uso realista e funcional antes das opções.
+3. **Composição:** nomear as partes públicas e explicar a relação entre elas.
+4. **Variações:** introduzir uma variação por necessidade observável, não por enumeração da API.
+5. **Comportamentos e cuidados:** explicitar defaults, efeitos automáticos, acessibilidade, limites e
+   consequências perto do exemplo relevante.
+6. **Referência:** terminar com uma seção identificada por componente público, sem fundir contratos
+   diferentes numa única tabela.
+
+Nem toda página precisa de todas as seções. Remover a seção vazia em vez de preenchê-la com prosa
+genérica.
+
+## Voz
+
+- Partir do objetivo da pessoa: “Use `Alert` para manter uma informação visível no contexto da
+  página.”
+- Preferir verbo concreto e voz ativa: “O `PageHeader` organiza título e ações.”
+- Apresentar o caminho recomendado com segurança; usar “pode” somente quando a alternativa é de
+  fato opcional.
+- Introduzir termos técnicos em linguagem comum antes de depender deles.
+- Manter tom próximo, sóbrio e profissional. Evitar propaganda, slogans, superlativos e entusiasmo
+  artificial.
+- Evitar começar pela implementação: substituir “O componente é responsável por renderizar...”
+  pela decisão ou resultado que importa a quem usa.
+- Usar frases e parágrafos curtos, sem fragmentar relações necessárias nem recorrer a abreviações.
+
+## Exemplos
+
+- Preparar o exemplo com uma frase que indique o objetivo ou o que deve ser observado.
+- Manter exemplos executáveis, focados e coerentes com o caminho recomendado.
+- Preferir uma pequena narrativa contínua a exemplos isolados que trocam de domínio sem necessidade.
+- Não demonstrar combinações inválidas apenas para listar props.
+- Depois do código, explicar somente efeitos que não sejam óbvios pela leitura: default aplicado,
+  estado controlado, ação automática, limite ou consequência.
+- Usar preview para comportamento visual e bloco de código para integração sem palco executável.
+
+## Famílias e referência
+
+- Agrupar componentes quando a pessoa precisa compreendê-los em conjunto para realizar uma tarefa,
+  como `Button` e `ButtonGroup` ou `Page`, `PageHeader`, `PageBody` e `PageState`.
+- Manter títulos e âncoras explícitos para cada membro da família.
+- Criar `## Propriedades de ComponentName` para cada componente público que possui contrato próprio.
+- Omitir tabela apenas para export sem props próprias ou alias cuja equivalência esteja declarada.
+- Posicionar tipos compartilhados depois dos componentes que os utilizam ou numa seção claramente
+  nomeada.
+
+## Links e navegação
+
+- Inserir links no ponto da decisão: ao recomendar `Toast` como alternativa efêmera, ligar a palavra
+  à página correspondente.
+- Não depender de uma seção genérica de “Veja também” para relações essenciais.
+- Ao consolidar páginas, escolher um endereço canônico e preservar os anteriores com redirect.
+- Conferir título visível, slug, registry, metadata e links como uma única identidade editorial.
+
+## Revisão linha por linha
+
+Para cada título, parágrafo, item, exemplo e célula de tabela, verificar:
+
+1. A pessoa entende por que esta linha existe neste ponto da leitura?
+2. A linha começa pela necessidade ou introduz detalhe interno cedo demais?
+3. A afirmação é sustentada pelo código, teste ou decisão registrada?
+4. Está claro se é default, obrigação, recomendação, alternativa ou exceção?
+5. Há termo ainda não apresentado, pronome ambíguo ou contexto que só existe na cabeça de quem
+   implementou?
+6. A frase pode ficar menor sem perder relação, condição ou consequência?
+7. O exemplo mostra o caminho recomendado e continua compilável?
+8. O texto ao redor do exemplo explica intenção e comportamento, sem narrar cada linha do código?
+9. O título permite localizar a informação pela tarefa, inclusive por link direto?
+10. Pontuação, capitalização, concordância e paralelismo estão consistentes?
+
+Ao terminar cada página, reler a sequência inteira. Linhas corretas isoladamente ainda podem formar
+uma página repetitiva, invertida ou sem progressão.
+
+## Referência de estilo
+
+O padrão absorve da documentação do Laravel a progressão do caso comum para os detalhes, os exemplos
+como eixo narrativo, a explicação dos comportamentos automáticos e a navegação por decisões. O Opus
+mantém sua própria voz em pt-BR: mais compacta, menos promocional e apoiada em previews visuais.

package/registry/skills/maintain-opus-docs/references/evaluations.md

@@ -0,0 +1,34 @@
+# Avaliações
+
+## Deve disparar
+
+“Agrupe Button Group na página de Button, preserve a rota antiga e documente as props dos dois.”
+
+“Revise toda a documentação publicada do Opus linha por linha e corrija a escrita.”
+
+## Não deve disparar
+
+“Escreva a regra de reembolso na documentação interna do produto.” Esse texto não pertence à
+documentação publicada do SDK Opus.
+
+“Corrija o alinhamento do ícone no Alert.” Uma mudança somente no componente pertence à
+implementação de UI; esta skill entra apenas se a documentação também for criada ou alterada.
+
+## Execução real
+
+Fornecer uma página de família que começa pela lista completa de props, usa a mesma tabela para dois
+componentes, mantém exemplos isolados sem objetivo, descreve implementação antes da decisão de uso e
+remove a rota publicada do componente agrupado. Pedir a reorganização sem informar a resposta
+esperada.
+
+Aprovar somente quando a página começar pela situação e escolha, apresentar um exemplo canônico
+executável, explicar defaults ou consequências no ponto relevante, criar referência identificada
+para cada contrato público e preservar a rota anterior por redirect ou alias. Exigir que a escrita
+seja próxima, direta e sóbria, sem copiar formulações da referência externa nem adotar tom
+promocional.
+
+Na revisão ampla, fornecer registry, metadata, componentes, testes e todas as páginas publicadas.
+Exigir inventário explícito, leitura linha por linha, correção na fonte canônica, verificação dos
+previews, typecheck, gates de copy e confirmação de que não restaram páginas órfãs. Reprovar se a
+execução se limitar às páginas mais longas, fizer apenas busca por padrões ou declarar cobertura
+total sem listar o universo revisado.

package/registry/skills/maintain-opus-docs/scripts/audit-docs.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+
+const repoRoot = resolve(process.argv[2] ?? process.cwd());
+const contentDir = resolve(repoRoot, "packages/opus/src/ui/docs/content");
+const registryPath = resolve(repoRoot, "packages/opus/src/ui/docs/registry.tsx");
+
+if (!existsSync(contentDir) || !existsSync(registryPath)) {
+  console.error(
+    "Não encontrei packages/opus/src/ui/docs/content e registry.tsx. Passe a raiz do repositório Opus.",
+  );
+  process.exit(2);
+}
+
+const registry = readFileSync(registryPath, "utf8");
+const importedFiles = new Set(
+  [...registry.matchAll(/\.\/content\/([^"']+\.md)\?raw/g)].map((match) => match[1]),
+);
+const files = readdirSync(contentDir)
+  .filter((file) => file.endsWith(".md"))
+  .sort();
+const findings = [];
+
+for (const file of files) {
+  const source = readFileSync(resolve(contentDir, file), "utf8");
+  const lines = source.split("\n");
+
+  if (!importedFiles.has(file)) {
+    findings.push(`${file}: página órfã; não há import no registry`);
+  }
+
+  let inFence = false;
+  let previousHeading = 0;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const lineNumber = index + 1;
+
+    if (/^```/.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+
+    const heading = /^(#{1,6})\s+/.exec(line);
+    if (heading) {
+      const level = heading[1].length;
+      if (previousHeading > 0 && level > previousHeading + 1) {
+        findings.push(`${file}:${lineNumber}: heading salta de h${previousHeading} para h${level}`);
+      }
+      previousHeading = level;
+    }
+
+    if (/^#{2,6}\s+Props(?:\s|$)/i.test(line)) {
+      findings.push(`${file}:${lineNumber}: nomeie a referência como “Propriedades de Componente”`);
+    }
+    if (/^\|\s*Prop\s*\|/i.test(line) || /\|\s*Default\s*\|/.test(line)) {
+      findings.push(`${file}:${lineNumber}: use “Propriedade” e “Padrão” no cabeçalho da tabela`);
+    }
+    if (/\b(?:pra|pro|pros|numa)\b/i.test(line)) {
+      findings.push(`${file}:${lineNumber}: abreviação coloquial na prosa`);
+    }
+  }
+
+  if (inFence) findings.push(`${file}: fence de código sem fechamento`);
+}
+
+for (const importedFile of importedFiles) {
+  if (!files.includes(importedFile)) {
+    findings.push(`${importedFile}: importado pelo registry, mas o arquivo não existe`);
+  }
+}
+
+if (findings.length > 0) {
+  console.error(findings.join("\n"));
+  console.error(`\n${findings.length} problema(s) estrutural(is) encontrado(s).`);
+  process.exit(1);
+}
+
+console.log(`${files.length} páginas auditadas; nenhuma inconsistência estrutural encontrada.`);

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

@@ -35,7 +35,8 @@ da mesma instância, sem catálogo repetido em enum, opção estática ou format
    - **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
+   Por entrada, declarar `context` somente em status e estágio, usando `neutral`, `info`, `success`,
+   `warning` ou `danger`; `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
@@ -68,7 +69,8 @@ contrato ou componente mapeado, regenerar com `opus copy` e executar os checks d
 - 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
+- Não declarar `context` em classificação, nem usar o alias legado `tone` em código novo, nem
+  `icon` fora do catálogo, nem `description` que
   repita o rótulo.
 
 ## Recursos

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

@@ -11,8 +11,9 @@
   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`
+  como `stage` com `context` explícito, sem `description` que repita o rótulo; provar que o manifest
+  projeta `presentation` e `context` e que `t.dict` rejeita valores fora do vocabulário.
+- Reprova: declarar `context` em uma classificação, usar o alias legado `tone` em código novo,
+  inventar `icon` fora do catálogo, copiar `doc`
   para `description` ou deixar `presentation` ausente em um status esperando que a tela infira o
   badge.

package/registry/templates/app/src/App.tsx

@@ -26,7 +26,7 @@ export function App(): React.ReactElement {
             {items.map((t) => (
               <li key={t.id} className="flex items-center justify-between gap-2 text-sm">
                 <span>{t.title}</span>
-                <Badge variant={t.done ? 'default' : 'secondary'}>{t.done ? 'Feita' : 'Aberta'}</Badge>
+                <Badge context={t.done ? 'success' : 'neutral'}>{t.done ? 'Feita' : 'Aberta'}</Badge>
               </li>
             ))}
           </ul>