@softize/opus 12.11.0 → 13.0.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@ 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.
 
+## 13.0.0 — 2026-09-07
+
+Dialogs passam a formar uma única família. `Dialog mode="alert"` oferece a semântica de
+`alertdialog`, exige uma resposta explícita e compartilha conteúdo, cabeçalho, mídia, corpo e rodapé
+com o modo padrão. `DialogClose` pode declarar `result` e foco inicial, enquanto `Dialog.onResult`
+recebe a escolha. A API imperativa mantém `alert`, `confirm` e `prompt` e acrescenta
+`dialog.choose({ actions })` para uma ou mais respostas nomeadas.
+
+Alerts, toasts, itens, estados vazios, dialogs e drawers alinham mídia e ações pela mesma anatomia.
+Molduras de ícone permanecem quadradas mesmo com descrições em várias linhas; ações ficam na região
+final da superfície e usam `Button` explicitamente. Toast aceita uma coleção ordenada em `actions`,
+com a última ação destacada por padrão. Drawer aproxima cabeçalho, corpo e rodapé do enquadramento de
+Dialog. Tabelas ganham respiro consistente, cabeçalhos muted e representação muted para valores
+ausentes. `Page` passa a usar teto padrão de `80rem`, e `SidebarTreeGroup` incorpora a guia visual
+para navegação hierárquica.
+
+A documentação publicada foi reorganizada por famílias de uso. Button Group, Input Group, Toggle
+Group e Page State passam a viver nas páginas dos componentes que os contextualizam, cada API com
+sua própria referência de propriedades. Dialog reúne os modos declarativo e imperativo, Sidebar
+documenta composição em árvore, e as categorias do catálogo ganham ícones próprios. A nova skill
+`maintain-opus-docs` registra o padrão editorial e os gates usados para manter esse catálogo.
+
+**Breaking:** os exports `AlertDialog*` foram removidos. Troque a raiz por
+`<Dialog mode="alert">`, os demais slots pelos equivalentes `Dialog*` e componha cada ação como
+`<DialogClose asChild><Button>…</Button></DialogClose>`. Para distinguir respostas, declare
+`result` em `DialogClose` e trate o valor em `Dialog.onResult`. Os campos `action` e `cancel` de
+Toast também foram removidos; use `actions`. `EmptyContent` foi removido; use `EmptyActions`.
+`SidebarNavGroup.subgroups` deixa de existir: componha níveis adicionais com `SidebarTreeGroup`.
+
 ## 12.11.0 — 2026-09-04
 
 A UI passa a separar intenção semântica de tratamento visual. `context` aceita `neutral`,

package/bin/lib/check.mjs

@@ -125,6 +125,7 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["DialogHeader", new Set(["DialogContent"])],
   ["DialogBody", new Set(["DialogContent"])],
   ["DialogFooter", new Set(["DialogContent"])],
+  ["DialogMedia", new Set(["DialogHeader"])],
   ["DialogTitle", new Set(["DialogHeader"])],
   ["DialogDescription", new Set(["DialogHeader"])],
   ["DrawerHeader", new Set(["DrawerContent"])],
@@ -149,15 +150,11 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["ItemTitle", new Set(["ItemHeader"])],
   ["ItemDescription", new Set(["ItemHeader"])],
   ["EmptyHeader", new Set(["Empty"])],
+  ["EmptyActions", new Set(["Empty"])],
   ["EmptyContent", new Set(["Empty"])],
   ["EmptyMedia", new Set(["EmptyHeader"])],
   ["EmptyTitle", new Set(["EmptyHeader"])],
   ["EmptyDescription", new Set(["EmptyHeader"])],
-  ["AlertDialogHeader", new Set(["AlertDialogContent"])],
-  ["AlertDialogFooter", new Set(["AlertDialogContent"])],
-  ["AlertDialogMedia", new Set(["AlertDialogHeader"])],
-  ["AlertDialogTitle", new Set(["AlertDialogHeader"])],
-  ["AlertDialogDescription", new Set(["AlertDialogHeader"])],
   ["PopoverHeader", new Set(["PopoverContent"])],
   ["PopoverTitle", new Set(["PopoverHeader"])],
   ["PopoverDescription", new Set(["PopoverHeader"])],
@@ -296,8 +293,6 @@ const UI_LEGACY_VARIANTS = new Map([
   ["MetricCard", new Set()],
   ["MenuItem", new Set(["default", "destructive"])],
   ["ActionTrigger", new Set(["default", "secondary", "destructive"])],
-  ["AlertDialogAction", new Set(["default", "secondary", "destructive"])],
-  ["AlertDialogCancel", new Set(["default", "secondary", "destructive"])],
 ]);
 
 /** Os três nomes que denotam action/contrato — o arquivo sem nenhum deles é pulado. */

package/bin/lib/copy.mjs

@@ -71,10 +71,6 @@ const JSX_CHILD_ROLES = new Map([
   ['ActionFormCard', 'message'],
   ['ActionFormDialog', 'message'],
   ['AlertDescription', 'message'],
-  ['AlertDialogAction', 'button'],
-  ['AlertDialogCancel', 'button'],
-  ['AlertDialogDescription', 'dialog-body'],
-  ['AlertDialogTitle', 'title'],
   ['AlertTitle', 'title'],
   ['Badge', 'badge'],
   ['BreadcrumbLink', 'breadcrumb'],
@@ -215,7 +211,7 @@ const JSX_PROP_STYLE = new Map([
 ])
 
 const JSX_PORTAL_BOUNDARIES = new Set([
-  'AlertDialogContent', 'DialogContent', 'DrawerContent', 'MenuContent', 'MenuSubContent',
+  'DialogContent', 'DrawerContent', 'MenuContent', 'MenuSubContent',
   'PopoverContent', 'TooltipContent',
 ])
 

package/docs/adr/0005-structural-surfaces-share-an-explicit-anatomy.md

@@ -30,6 +30,9 @@ As superfícies mantidas pela casa adotam a gramática `Root > Header + Body + F
 - `Dialog` permanece como referência porque já possui `DialogHeader` e `DialogBody`.
 - `Alert` oferece `AlertMedia`, `AlertHeader`, `AlertTitle`, `AlertDescription` e
   `AlertActions`; a forma curta por propriedades materializa esses mesmos slots.
+- `Empty` oferece `EmptyHeader`, `EmptyMedia`, `EmptyTitle`, `EmptyDescription` e
+  `EmptyActions`. `EmptyContent` permaneceu como alias legado durante a versão 12 e foi removido na
+  versão 13.
 - `Item` oferece `ItemMedia`, `ItemHeader`, `ItemTitle`, `ItemDescription`, `ItemBody`,
   `ItemActions` e `ItemFooter`. `ItemContent` permanece temporariamente como alias legado de
   corpo, mas deixa de envolver título e descrição no código novo.
@@ -44,13 +47,49 @@ explícita usa os slots da família.
 
 `Content` técnico mantém seu nome quando representa o contêiner montado por uma primitiva ou um
 painel controlado, como `DialogContent`, `PopoverContent`, `TabsContent` e `AccordionContent`.
-`EmptyContent` e `CarouselContent` também permanecem porque não representam o body de uma
-superfície estrutural.
-
-Nas superfícies horizontais, `Media` e `Header` formam a mesma linha estrutural. A região visual
-de `Media` tem largura estável e se estende pela altura útil do header, mantendo seu conteúdo
-centralizado. Assim, título e descrição de uma linha não deixam uma sobra inferior ao lado da
-moldura; conteúdo textual maior continua determinando naturalmente a altura da linha.
+`CarouselContent` também permanece porque representa o trilho técnico da primitiva, não o body de
+uma superfície estrutural. No `Empty`, a antiga região `EmptyContent` não é um body: como contém
+somente comandos, seu nome canônico passa a ser `EmptyActions`.
+
+As superfícies modais centralizadas pertencem a uma única família pública, `Dialog`. O modo padrão
+permite tarefas e conteúdo dispensáveis; `mode="alert"` exige uma resposta explícita e seleciona
+internamente a primitiva que emite `role="alertdialog"`, prende o foco e impede o fechamento pelo
+clique externo. O comportamento determina o papel de acessibilidade: `role` não é usado como chave
+de configuração. A família pública `AlertDialog` deixa de existir, enquanto os métodos imperativos
+`dialog.alert`, `dialog.confirm`, `dialog.prompt` e `dialog.choose` usam `Dialog mode="alert"`.
+
+Os dois modos usam o fundo base e o texto de primeiro plano, delimitados por borda semântica, raio
+`xl` e elevação. A anatomia interna continua responsável pelo espaçamento de cabeçalho, corpo e
+rodapé. O fundo base preserva o contraste com faixas internas, enquanto a borda torna o limite do
+modal reconhecível mesmo quando a página usa o mesmo fundo. No modo de alerta, `DialogMedia`
+oferece a moldura quadrada de mídia e o header e o footer adotam a composição compacta da resposta.
+
+`Drawer` preserva a moldura externa ancorada à borda da janela, mas compartilha com `Dialog` as
+faixas internas: o header recebe divisor inferior, o footer recebe divisor superior sobre fundo
+sutil e o body mantém o mesmo alinhamento horizontal. Essa aproximação não adiciona raio nem borda
+ao lado preso à janela.
+
+Primitives comportamentais não escolhem a aparência do controle. `DialogClose` e `DrawerClose`
+aplicam fechamento ao filho; `Button` define contexto, variante, tamanho e o efeito do clique. Em
+`Dialog mode="alert"`, `DialogClose initialFocus` marca a saída segura sem dividir fechamentos entre
+action e cancel. `result` identifica uma resposta para `Dialog onResult` quando o consumidor precisa
+observá-la. A composição com `asChild` mantém o elemento interativo único e torna a mesma regra
+previsível em diálogos comuns, drawers e diálogos que exigem resposta.
+
+A API imperativa mantém contratos semânticos curtos para reconhecimento, confirmação binária e
+entrada textual. Para escolhas simples com mais resultados, `dialog.choose` recebe uma coleção de
+ações e devolve a união dos valores de `result`, ou `null` quando a superfície fecha sem escolha.
+A coleção exige um único `initialFocus` habilitado e resultados únicos. Composição JSX permanece
+para fluxos cujo carregamento, validação, erro ou estado controlado precisa existir dentro do modal.
+
+Nas superfícies horizontais, `Media` e `Header` formam a mesma linha estrutural. Quando `Media`
+desenha uma moldura para ícone ou imagem, ela mantém largura e altura iguais e fica alinhada ao
+topo. O conteúdo textual determina naturalmente a altura da linha sem transformar a mídia em um
+retângulo quando a descrição ocupa mais linhas.
+
+Nas superfícies de feedback, `Actions` se alinha ao fim lógico da área útil e permanece centralizado
+verticalmente na mesma linha do conteúdo. `Alert` e `Toast` compartilham essa posição; descrições
+longas ocupam o espaço restante e quebram linha sem deslocar as ações para o rodapé.
 
 ## Consequências
 
@@ -60,11 +99,14 @@ moldura; conteúdo textual maior continua determinando naturalmente a altura da
   slots e `opus check` verifica a anatomia JSX completa. Nas famílias históricas, o lint reconhece
   wrappers transparentes e render props: reprova uma família visivelmente errada sem proibir que
   um slot seja encapsulado por um componente reutilizável.
-- Aliases históricos permanecem durante a versão 12 e podem ser removidos numa versão major.
+- Aliases históricos podem permanecer durante uma janela de migração e ser removidos numa versão
+  major; a versão 13 remove `EmptyContent` e mantém os demais aliases até uma decisão específica.
 - Consumidores precisam migrar `ContentHeader` solto para `Content` e podem migrar as demais formas
   gradualmente enquanto os aliases existirem.
 - Alertas e itens simples ganham uma hierarquia igual sem perder suas semânticas distintas:
   `Alert` comunica estado e `Item` representa uma entidade ou opção numa coleção.
+- Diálogos comuns e diálogos que exigem resposta compartilham nome, anatomia e moldura visual;
+  consumidores escolhem a diferença comportamental com `mode`, sem reconstruir a superfície.
 
 ## Alternativas consideradas
 
@@ -84,6 +126,39 @@ Nomes como `SectionHeader` pressupõem outro pai; nomes como `GenericHeader` des
 semântica; e `HeadingBlock` abandona a gramática das demais famílias. Foi descartada em favor de
 dar a `ContentHeader` um pai estrutural real.
 
+### Manter `DialogContent` como card sem borda
+
+Preservaria a diferença histórica entre `Dialog` e o antigo `AlertDialog`, mas faria superfícies com a mesma
+função modal responderem a fundos e limites diferentes. Foi descartada porque essa diferença não
+representa comportamento distinto e pode reduzir a percepção do contorno sobre páginas com fundo
+semelhante.
+
+### Manter `AlertDialog` como família pública separada
+
+Espelharia diretamente as duas primitives do Radix, mas duplicaria nomes estruturais e faria a API
+pública expressar um detalhe de implementação. Foi descartada porque `mode="alert"` preserva a
+semântica e as garantias comportamentais sem obrigar quem consome a reaprender outra família.
+
+### Usar `role="alertdialog"` para selecionar o comportamento
+
+Seguiria a API de alguns design systems, mas transformaria um atributo de acessibilidade em chave de
+comportamento, algo que o restante do Opus não faz. Foi descartada para que o `mode` selecione as
+garantias e o componente derive o `role` correto.
+
+### Expor action e cancel como primitives distintos no diálogo de alerta
+
+Preservaria os nomes do Radix, mas apresentaria um fechamento como “action” embora cancelar também
+seja uma ação. Os dois caminhos fecham a superfície; a única diferença técnica relevante é o
+registro do destino inicial do foco. Foi descartada em favor de `DialogClose`, cuja propriedade
+`initialFocus` expressa essa diferença sem criar duas categorias públicas.
+
+### Exigir composição JSX para toda escolha com mais de duas ações
+
+Manteria a API imperativa menor, mas obrigaria cada consumidor a reconstruir fila, fechamento,
+foco seguro e resolução para uma escolha sem estado próprio. Foi descartada porque `dialog.choose`
+consegue preservar essas garantias e devolver um resultado tipado sem absorver formulários ou ações
+assíncronas que precisam manter o modal aberto.
+
 ## Verificação
 
 - Testes de UI comparam DOM, acessibilidade e `data-slot` das formas curta e explícita.
@@ -91,7 +166,15 @@ dar a `ContentHeader` um pai estrutural real.
   família correspondente; essa relação entre elementos JSX não é representável somente pelo tipo
   de `children` do React.
 - `opus check` reprova relações JSX estruturais inválidas nos consumidores.
-- Testes de layout verificam que `AlertMedia` e `ItemMedia` se estendem pela linha do header e
-  centralizam o ícone, sem fixar a altura do conteúdo textual.
+- Testes de layout verificam que `AlertMedia` e `ItemMedia` mantêm molduras quadradas alinhadas ao
+  topo, sem fixar a altura do conteúdo textual.
+- Testes de estrutura verificam que os dois modos de `DialogContent` usam fundo base, texto de
+  primeiro plano, borda semântica, raio e elevação, sem retornar ao fundo de card.
+- Testes do `Drawer` verificam divisores, fundo do footer e alinhamento de padding entre header,
+  body e footer.
+- Testes de estrutura verificam que `DialogClose` não materializa `Button`, usa `result` somente como
+  resposta e aplica `initialFocus` à primitive que registra a saída segura no modo de alerta.
+- Testes do host verificam inferência dos resultados de `dialog.choose`, foco seguro, defaults
+  visuais, escolha explícita, fechamento sem escolha e entradas inválidas.
 - Documentação e metadados apresentam a forma curta como caminho comum e a composição explícita
   como caminho de extensão.

package/docs/adr/0007-toast-actions-form-an-ordered-collection.md

@@ -0,0 +1,63 @@
+# ADR 0007 — Ações de Toast formam uma coleção ordenada
+
+- Status: aceita
+- Data: 2026-09-05
+
+## Contexto
+
+O Opus exportava diretamente a API do Sonner, que distingue uma ação principal (`action`) de uma
+ação especializada de cancelamento (`cancel`). Essa divisão expõe uma decisão da dependência na API
+da casa e força uma semântica que não existe em toda notificação. Os demais componentes do Opus
+tratam ações como uma região ordenada, enquanto contexto e variante descrevem a hierarquia visual.
+
+A compatibilidade importa porque consumidores da versão 12 já podem usar os campos do Sonner. Ao
+mesmo tempo, manter os dois formatos indefinidamente deixaria a API ambígua e impediria que o Opus
+controlasse composição, estilos e comportamento de forma consistente.
+
+## Decisão
+
+O contrato canônico de Toast passa a aceitar `actions`, uma coleção ordenada de `ToastAction`.
+Cada entrada declara `label`, `onClick` e, quando necessário, `context`, `variant`, `disabled` e uma
+chave React. As ações são renderizadas com `Button size="sm"`: a última usa `primary + solid` por
+padrão e as anteriores usam `neutral + ghost`.
+
+Depois do handler, o Toast fecha, salvo quando o evento chama `preventDefault()`. `actions` não
+pode ser combinado com os campos antigos `action` ou `cancel`.
+
+`action` e `cancel` permaneceram aceitos e marcados como obsoletos durante a versão 12. A versão 13
+remove esses campos e a estilização de compatibilidade. Os consumidores dependem do contrato do
+Opus, sem expor a divisão especializada do Sonner.
+
+## Consequências
+
+- Uma notificação pode ter zero, uma ou mais ações sem inventar um papel de cancelamento.
+- A ordem da coleção comunica hierarquia e mantém o destaque principal no final, como nas demais
+  regiões de ação.
+- Consumidores da versão 12 tiveram uma janela de migração antes da remoção dos campos obsoletos.
+- `toast.promise` continua seguindo o contrato próprio do Sonner nesta etapa; a coleção canônica se
+  aplica aos disparos simples e tipados por estado.
+
+## Alternativas consideradas
+
+### Manter `action` e `cancel`
+
+Preservaria a API da dependência, mas manteria uma distinção semântica artificial e impediria uma
+composição uniforme. Foi descartada como contrato canônico.
+
+### Remover os campos antigos imediatamente
+
+Produziria uma API menor, mas quebraria consumidores dentro da mesma versão principal. Foi
+descartada em favor de uma janela explícita de migração.
+
+### Aceitar somente elementos React prontos
+
+Daria liberdade total de composição, mas transferiria geometria, hierarquia e fechamento para cada
+consumidor. Foi descartada porque ações declarativas cobrem o fluxo comum sem impedir personalização
+por contexto e variante.
+
+## Verificação
+
+- Testes de DOM verificam que `actions` produz uma região única com `Button` do Opus.
+- Testes de interação verificam ordem, defaults visuais, execução e fechamento.
+- Testes de contrato reprovam a mistura de `actions` com `action` ou `cancel`.
+- Documentação e metadata apresentam somente `actions` como caminho canônico.

package/docs/adr/0008-hierarchical-navigation-is-composed-at-the-consumer-boundary.md

@@ -0,0 +1,71 @@
+# ADR 0008 — Navegação hierárquica é composta na fronteira do consumidor
+
+- **Status:** aceita.
+- **Data:** 2026-09-06.
+
+## Contexto
+
+`SidebarNav` oferece `groups`, `items` e `subgroups`. O terceiro nível foi introduzido para
+preservar a estrutura seção → grupo → página do `DocBrowser`, mas não possui outro consumidor no
+Opus nem nos aplicativos conhecidos. A API geral passou a carregar uma topologia rígida criada por
+uma única tela.
+
+Ao mesmo tempo, `SidebarItem` já representa os comportamentos necessários para árvores: um destino
+principal, um controle irmão de expansão por `onToggle` e `expanded`, ações por item e indicadores
+de drop. O estado da árvore e a origem de seus nós variam por consumidor. Porém, o recuo e a guia
+vertical que comunicam descendência se repetiam nos aplicativos como a mesma combinação de classes,
+embora sejam parte da linguagem visual da sidebar.
+
+## Decisão
+
+`SidebarNav` mantém somente a estrutura plana `groups → items`. `SidebarNavSubgroup` e a
+propriedade `subgroups` deixam a API pública.
+
+Hierarquias são compostas pelo consumidor com `SidebarGroupLabel`, `SidebarItem` e
+`SidebarTreeGroup`. O consumidor controla expansão, ordem, profundidade e carregamento dos nós;
+`SidebarTreeGroup` aplica a guia e o recuo dos descendentes, enquanto `SidebarItem` mantém a
+apresentação e a acessibilidade de cada linha.
+
+O `DocBrowser` materializa sua árvore própria a partir de `DocSection[]`. Seções aparecem como
+rótulos, grupos nomeados viram nós expansíveis e páginas viram folhas. Grupos começam abertos para
+preservar a descoberta atual, podem ser recolhidos e voltam a abrir quando passam a conter a página
+ativa.
+
+## Consequências
+
+- A API geral deixa de prometer uma árvore limitada a exatamente três níveis.
+- A documentação continua preservando seção, grupo e página sem usar um contrato específico no
+  componente compartilhado.
+- Outros consumidores podem montar árvores rasas, recursivas, assíncronas ou arrastáveis com os
+  mesmos elementos, sem novas propriedades na `SidebarNav` nem classes locais para a guia.
+- Remover `SidebarNavSubgroup` e `subgroups` é uma mudança incompatível e exige uma versão major na
+  próxima publicação do pacote.
+- `DocBrowser` passa a possuir o estado de expansão de seus grupos.
+
+## Alternativas consideradas
+
+### Manter `subgroups`
+
+Preservaria compatibilidade, mas manteria na API geral uma topologia usada somente pela
+documentação. Foi descartada porque a composição existente já cobre o comportamento sem acoplar o
+componente à estrutura de uma tela.
+
+### Substituir por uma árvore recursiva em `SidebarNav`
+
+Aceitar `children` recursivos permitiria profundidade arbitrária, mas também exigiria que o
+componente decidisse expansão, carregamento, seleção e semântica de pastas para todos os produtos.
+Foi descartada até que consumidores independentes revelem um contrato comum.
+
+### Achatar a documentação
+
+Converter grupos em uma lista única simplificaria o renderer, mas perderia a classificação que
+também é produzida por pastas e pelo frontmatter das docs de projetos. Foi descartada porque a
+hierarquia tem significado para descoberta e localização.
+
+## Verificação
+
+- Um teste de API impede que `SidebarNavSubgroup` volte a ser exportado.
+- Testes de `SidebarNav` cobrem grupos planos, seleção e omissão de grupos vazios.
+- Um teste de `SidebarTreeGroup` protege a guia, o recuo e o espaçamento entre descendentes.
+- Testes de `DocBrowser` cobrem os três níveis, expansão e reabertura do grupo da página ativa.
+- A documentação do Sidebar demonstra árvore com `SidebarTreeGroup` e não menciona `subgroups`.

package/docs/radius-scale.md

@@ -27,7 +27,7 @@ voltaria a acoplar forma e tipo de componente, problema removido na versão 10.0
   token semântico por componente.
 - Superfícies aninhadas evitam moldura dupla e normalmente usam um degrau menor que o contêiner.
   Elementos conectados removem os raios nas arestas internas.
-- Card, Dialog e AlertDialog permanecem em `xl`. Molduras estruturais com cantos, como a tabela
+- Card e os dois modos de Dialog permanecem em `xl`. Molduras estruturais com cantos, como a tabela
   standalone, permanecem em `lg`; Page, Split e Sidebar não ganham uma moldura por essa regra.
 - Calendar e Command preservam a geometria embutível. Um consumidor standalone pode ajustar o
   contêiner por `className` quando a composição pedir mais presença.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "12.11.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/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.