@softize/opus 18.1.0 → 18.2.0

package/CHANGELOG.md

@@ -7,6 +7,79 @@ 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.
 
+## 18.2.0 — 2026-09-16
+
+`Presentation` passa a aceitar um body serializável baseado em componente. O contrato continua
+definindo rota, superfície, navegação e ações, enquanto a aplicação fornece o conteúdo React em
+tempo de execução. Assim, uma página pode adotar a casca dirigida por spec sem precisar migrar de
+uma vez toda a implementação interna para actions declarativas.
+
+Recursos podem declarar um gatilho de assistência contextual em `assistant`. A aplicação fornece o
+painel e os dados vivos do recurso por `assistant.render`; identidade, autorização e demais dados
+não entram no manifest. O novo `SurfaceAssistant`, também disponível pela API pública, divide
+somente o body de Page, Dialog ou Drawer. Cabeçalho e rodapé permanecem em toda a largura, e o
+gatilho sai do cabeçalho enquanto o painel aberto assume a identidade visual da assistência.
+
+O split contextual usa um único separador redimensionável, sem sobrepor uma segunda borda entre o
+conteúdo e o painel. O conteúdo principal permanece montado durante a conversa e volta a ocupar
+toda a largura quando ela é fechada.
+
+## 18.1.1 — 2026-09-16
+
+**Correção de segurança.** Quem executa tools de IA só roda o que `aiTools()` anunciou. Até aqui, o
+servidor MCP executava em `CallTool` qualquer action registrada, e o agente co-locado executava
+qualquer nome de tool que o modelo emitisse. Um cliente MCP, um modelo ou um prompt injetado podia
+rodar uma action sem `ai.enabled` — inclusive destrutiva — dentro da autorização do contexto
+resolvido. Os dois caminhos agora recusam o nome fora do conjunto exposto, com a mesma resposta
+para action inexistente e para action registrada mas não exposta, sem revelar quais existem.
+Nenhuma mudança é necessária em quem já marcava com `ai.enabled` as actions que expõe; quem
+dependia de chamar pelo MCP uma action não marcada precisa marcá-la.
+
+Uma action que não é `public` passa a exigir usuário ANTES de rodar os loaders. Antes, os
+`loads` consultavam dados para um chamador anônimo, que recebia o erro do loader — um
+`not_found`, por exemplo — e podia usar essa diferença para descobrir se um registro existe. O
+`authorize` continua depois dos loaders, porque depende do que eles carregam.
+
+`RadioGroupItem` passa a ter a classe `peer`, como `Checkbox` e `Switch`: o `Label` associado
+esmaece quando o item está desabilitado, como a documentação já descrevia. Em `DetailGroup` com
+moldura e orientação horizontal, a largura padrão da coluna de rótulos passa a ser uma classe, e
+uma classe do consumidor (`[--detail-label-width:9rem]`) volta a substituí-la; antes, só `style`
+conseguia.
+
+A documentação publicada foi revisada por inteiro, e as 92 páginas foram abertas num navegador
+headless sem erro de console nem de preview. O exemplo principal de Presentation voltou a
+renderizar: ele usava funções que não estavam no escopo dos previews e lançava `ReferenceError`.
+Um exemplo do `IconPicker` declarava `Icon`, nome que o escopo já fornece, e mostrava um erro de
+sintaxe no lugar do preview. Um gate novo compila cada preview com o escopo da sua página, do jeito
+que o site o executa, e reprova nome ausente ou redeclarado; o anterior só conferia tags JSX. Sessenta e quatro páginas foram
+corrigidas contra o código: props, defaults e tipos que não batiam, exemplos que não compilavam ou ensinavam padrões
+substituídos pelas versões 16 a 18, e afirmações que o código não sustenta. Entre elas, `auth.md`
+deixa de sugerir que o runtime aplica um campo `auth` inexistente, e `upgrading.md` passa a incluir
+`pnpm run setup` e os gates de copy, sem os quais o fluxo de upgrade falhava no primeiro gate.
+
+`opus check --help` lista as regras de Produto de Dados. As ADRs que dividiam número foram
+renumeradas: a do cabeçalho modal passa a 0018 e a da densidade compacta, a 0019; um gate impede
+nova colisão. O guia de release passa a dizer que a documentação é publicada à parte, com
+`pnpm deploy:docs`. A skill `build-opus-ui` passa a ensinar `placement` nos filtros e o
+`ButtonGroup` nos footers modais.
+
+### Correções do histórico
+
+Estas entradas publicadas descrevem algo diferente do que o código daquela versão fez. Elas não
+foram reescritas; a correção fica registrada aqui.
+
+- **17.2.1 nunca foi publicada.** O conteúdo daquela entrada — `renderMessageActions` nas mensagens
+  enviadas, `activity=""` e o `title` das tools MCP — saiu na 18.0.0.
+- **17.0.0 e 17.2.0 mudaram a composição explícita dentro de `PageShell` sem aviso de quebra.** A
+  17.0.0 passou a exigir `PageHeader` onde a 16.x exigia `PageIntro`, e a 17.2.0 voltou a exigir
+  `PageIntro`. Desde a 18.0.0, ambos são opcionais e a página exige um único heading principal.
+- **18.1.0:** `Item size="sm"` reduz também o espaço entre regiões, para `0.625rem`, e não somente o
+  padding vertical. A mesma versão trocou o fechamento de Dialog e Drawer, que na 18.0.1 era um
+  `Button` `icon`, pelo `CloseButton` (`neutral`, `subtle`, forma de pílula e `icon-sm`), com
+  a nova prop `closeSize`; nenhum dos dois foi anunciado. Ela também removeu breakpoints responsivos
+  e mudou o footer padrão do `ActionFormDialog`; quem tinha testes visuais ou telas abaixo de
+  `64rem` precisa revisá-los.
+
 ## 18.1.0 — 2026-09-15
 
 A UI passa a assumir layout desktop fixo com largura mínima suportada de `64rem`. Breakpoints de
@@ -107,6 +180,8 @@ a API imperativa, usam `outline`; a decisão principal continua `solid`.
 
 ## 17.2.1 — 2026-09-12
 
+> Esta versão nunca foi publicada no npm; o conteúdo abaixo saiu na 18.0.0.
+
 O `Chat` passa a renderizar `renderMessageActions` também nas mensagens enviadas. Data, cópia e
 outras ações contextuais podem usar a mesma extensão discreta nos dois lados da conversa.
 `activity=""` oferece o indicador compacto, com somente os pontos centralizados e “Pensando…”

package/PROMOTED.md

@@ -1,11 +1,10 @@
 # Enhancements promovidas ao Opus
 
 O registro CURADO da régua "o Opus cresce por reincidência". O fluxo vivo NÃO passa por
-edição manual deste arquivo: o agente no projeto aponta em `.opus/issues.jsonl` do repo
-dele (instrução na skill `implement-opus-change`; `type` **enhancement** ou **bug**) →
-o Maestro colhe no boot da sessão e abre a **Issue no repo do Opus**
-(`github.com/softize-dev/opus`, dedup por hash + ledger), onde a triagem e a decisão
-acontecem (aberta = pendente, fechada = decidida). Enhancement aceita com **n ≥ 2**
+edição manual deste arquivo: cada apontamento vira uma **Issue no repo do Opus**
+(`github.com/softize-dev/opus`), `type` **enhancement** ou **bug**, onde a triagem e a
+decisão acontecem (aberta = pendente, fechada = decidida). O pacote não coleta nada do
+projeto consumidor por conta própria. Enhancement aceita com **n ≥ 2**
 ocorrências reais — comportamento se paga na reincidência; estilo e conveniência não.
 Bug (defeito NO Opus) aciona com n=1: vira fix + CHANGELOG, **não** entra neste ledger.
 

package/README.md

@@ -1,6 +1,6 @@
 # Opus
 
-> **Status:** v0 — pacote único `@softize/opus` com subpath exports (core + adapters). Uma versão, sem semver por módulo.
+> Pacote único `@softize/opus` com subpath exports (core + adapters). Uma versão, sem semver por módulo.
 
 Protocolo de actions de ponta a ponta para TypeScript. Declare uma vez — input, autorização, execução, auditoria, feedback — e deixe os adapters materializarem a action na interface, no cliente, no servidor e no log.
 
@@ -43,6 +43,7 @@ Um pacote (`@softize/opus`), uma versão. Cada categoria abaixo é um **subpath
 | `@softize/opus/testing` | — | Harness de teste de actions pela fronteira do contrato (experimental) |
 | `@softize/opus/dsl` | — | Expressões declarativas avaliadas em `load` e em consultas |
 | `@softize/opus/seed` | — | Declaração e binding de datasets verificáveis operados pela CLI |
+| `@softize/opus/presentation` | — | Presentations portáteis: `definePresentation`, invocação e rotas |
 | `@softize/opus/vite` | — | Plugins Vite: runtime em modo design e auth de sessão fixa |
 
 Os drivers são resolvidos por subpath ESM (no estilo do Drizzle): `@softize/opus/server/fastify`, `@softize/opus/data/kysely`.
@@ -90,7 +91,7 @@ await app.listen({ port: 3000 })
 src/
   core/      schema/    server/    client/    ui/      data/    auth/    audit/
   log/       queue/     events/    scheduler/ storage/ cache/   ai/      mcp/
-  observability/        testing/   dsl/       seed/    vite/
+  observability/        testing/   dsl/       seed/    vite/    presentation/
 registry/    # scaffolds + skills Opus — geração e conhecimento do SDK, não runtime
 bin/         # CLI (opus create/setup/gen/copy/check/db/seed/pre-push/introspect/mcp) + libs
 docs/
@@ -117,8 +118,8 @@ O contrato não oferece reset/truncate, e `apply` precisa convergir quando repet
 
 ## Status
 
-- **v0**: 21 superfícies, suíte vitest com cobertura medida por `pnpm test:cov`. O threshold de 100% em `vitest.config.ts` é aspiracional e não faz parte do gate de release (ver [docs/releasing.md](docs/releasing.md)).
-- **v1+**: drivers adicionais (Hono, Drizzle, ArkType, Vue, Inngest, Redis events), camada de entidades (`defineEntity`), Conversya migration plan.
+- **Hoje**: 22 superfícies, suíte vitest com cobertura medida por `pnpm test:cov`. O threshold de 100% em `vitest.config.ts` é aspiracional e não faz parte do gate de release (ver [docs/releasing.md](docs/releasing.md)).
+- **Próximos**: drivers adicionais (Hono, Drizzle, ArkType, Vue, Inngest, Redis events) e o plano de migração da Conversya.
 
 ## Desenvolvimento
 

package/bin/cli.mjs

@@ -426,6 +426,10 @@ Regras da UI (@softize/opus/ui):
   unpaired-ui-surface     — superfície sem o foreground do par (bg-card sem
                             text-card-foreground, bg-popover sem text-popover-foreground)
 
+Regras dos Produtos de Dados (defineDataProduct):
+  data-product-*          — declaração exportada, id e versão válidos, sem duplicata,
+                            interfaces e entidades que existem no domínio
+
 Exit ≠ 0 se houver violação. Sem nenhuma action: projeto marcado (opus.json) passa
 vacuamente; sem marcador, falha — gate vazio não é aprovação. Default dir: cwd.
 `)

package/docs/adr/0004-page-content-state-is-composed.md

@@ -1,5 +1,8 @@
 # ADR 0004 — O estado integral do conteúdo é composto dentro de Page
 
+- **Status:** aceita, com adendo.
+- **Data:** 2026-09-04.
+
 > **Atualização (2026-09-09).** A decisão original preservava o cabeçalho da página em todos os
 > estados. Ela foi invertida: `PageState` passa a ocultá-lo em `loading`, `error` e `empty`, e a
 > restaurá-lo em `ready`. A lista de responsabilidades abaixo já descreve o comportamento novo; o

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

@@ -5,10 +5,14 @@
 
 > **Atualização (2026-09-09).** Parcialmente substituída pela ADR 0009 quanto a `PageMeta` e ao
 > `count` de `Page`, e complementada pela ADR 0010, que acrescenta as apresentações `default` e
-> `bar` ao mesmo header. O corpo abaixo já traz a anatomia vigente.
+> `bar` ao mesmo header.
 >
-> **Atualização (2026-09-11).** As ADRs 0012 e 0014 removem Description dos headers de Page,
+> **Atualização (2026-09-11).** As ADRs 0018 e 0014 removem Description dos headers de Page,
 > Dialog e Drawer. Contexto relevante começa no body.
+>
+> **Atualização (2026-09-16).** O corpo abaixo descreve a anatomia da época em que foi escrito, não a
+> vigente: a apresentação `bar` da ADR 0010 saiu com a ADR 0011, e nenhum header estrutural carrega
+> mais descrição (ADRs 0018 e 0014). A anatomia atual está na documentação de cada família.
 
 ## Contexto
 

package/docs/adr/0011-page-shell-coordinates-persistent-page-chrome.md

@@ -2,11 +2,16 @@
 
 - **Status:** aceita.
 - **Data:** 2026-09-10.
-- **Revisa:** ADR 0010.
+- **Substitui:** ADR 0010.
 
 > **Atualização (2026-09-13).** A ADR 0016 separa o chrome persistente da introdução e do
 > cabeçalho de uma coleção. `PageHeader` passa a declarar navegação e ações globais para a barra;
 > `PageIntro` permanece opcional no conteúdo e `Content` nomeia coleções.
+>
+> **Atualização (2026-09-16).** Desde a 18.0.0, a composição explícita dentro do shell aceita
+> `PageHeader`, `PageIntro` e `PageFooter` como opcionais e exige exatamente um heading principal —
+> `PageTitle`, `Content level={1}` ou um `PageState` ativo. As frases abaixo que pedem `PageIntro`
+> "sem `PageHeader`" descrevem a regra da 17.2 e não valem mais.
 
 ## Contexto
 

package/docs/adr/0014-structural-headers-do-not-carry-description.md

@@ -2,7 +2,7 @@
 
 - **Status:** aceita.
 - **Data:** 2026-09-11.
-- **Complementa:** ADRs 0005, 0011 e 0012.
+- **Complementa:** ADRs 0005, 0011 e 0018.
 
 ## Contexto
 
@@ -13,7 +13,7 @@ superfície e misturava o nome do recurso com instruções e consequências da t
 ## Decisão
 
 Headers estruturais contêm navegação opcional, título e actions. Page não oferece a propriedade
-`description` nem `PageDescription`; Dialog e Drawer seguem a mesma regra conforme a ADR 0012.
+`description` nem `PageDescription`; Dialog e Drawer seguem a mesma regra conforme a ADR 0018.
 
 Contexto que altera compreensão ou decisão aparece no início do body. Ele pode ser texto, `Alert`,
 `Content` ou outra composição adequada. `PageState`, `Alert`, `Empty`, campos, métricas e seções

package/docs/adr/0015-action-size-follows-interaction-density.md

@@ -21,10 +21,11 @@ risco.
 
 - ações textuais que decidem a superfície usam `default`: header de Page e footer de Page, Dialog
   ou Drawer;
-- ações operacionais em toolbar, header de seção ou coleção densa usam `sm`;
+- ações operacionais em toolbar, header de seção ou coleção densa usam `sm`; a criação no header
+  de uma coleção é a exceção e usa `default` (ADR 0016);
 - ações internas de linha, célula ou campo usam `xs` ou `icon-xs`;
-- ações somente com ícone que pertencem ao chrome da superfície, como voltar e fechar, usam
-  `icon`;
+- ações somente com ícone que pertencem ao chrome da superfície, como voltar, usam `icon`; desde a
+  18.1.0 o fechamento de Dialog e Drawer é o `CloseButton`, em `icon-sm` por padrão (`closeSize`);
 - `lg` fica reservado a chamadas que deliberadamente precisam de uma área de toque maior, não a
   uma ação primária comum.
 

package/docs/adr/{0012-modal-header-only-names-the-surface.md → 0018-modal-header-only-names-the-surface.md}

@@ -1,4 +1,7 @@
-# ADR 0012 — O cabeçalho modal apenas nomeia a superfície
+# ADR 0018 — O cabeçalho modal apenas nomeia a superfície
+
+> Publicada originalmente com o número 0012, que colidia com a ADR de Produtos de Dados do mesmo
+> dia. Renumerada em 2026-09-16; o conteúdo não mudou.
 
 - **Status:** aceita.
 - **Data:** 2026-09-11.

package/docs/adr/{0016-productive-surfaces-use-compact-density.md → 0019-productive-surfaces-use-compact-density.md}

@@ -1,4 +1,7 @@
-# ADR 0016 — Superfícies produtivas usam densidade compacta
+# ADR 0019 — Superfícies produtivas usam densidade compacta
+
+> Publicada originalmente com o número 0016, que colidia com a ADR do cabeçalho da coleção.
+> Renumerada em 2026-09-16; o conteúdo não mudou.
 
 - **Status:** aceita.
 - **Data:** 2026-09-14.

package/docs/code-style.md

@@ -98,8 +98,8 @@ Base instalada é dona do catálogo, dos kinds aceitos e do fundamento de cada r
 | `Select.options[].hint/triggerLabel/group`                                                                                                                                                 | `label`, `label`, `heading`                              |
 | `ActionTrigger.confirm.*`                                                                                                                                                                  | papel correspondente do diálogo                          |
 | `t.dict` — `label`, `description`, `doc` das entradas e `doc` do dicionário                                                                                                                | `label`, `description`                                   |
-| `DataState`/`PageState`/`ActionList`/`ActionListDialog` — `emptyMessage`, `errorMessage`, `retryLabel`; `PageState`/`ActionListDialog` — `title`, `description`; `ActionView.emptyMessage` | `empty-state`, `error`, `button`, `title`, `description` |
-| `dialog.alert/confirm/prompt/choose()` — `title`, `description`, `body`, `action`, `cancel`, `placeholder`, `actions[].label`                                                              | papel correspondente do diálogo                          |
+| `DataState`/`PageState`/`ActionList`/`ActionListDialog` — `emptyMessage`, `errorMessage`, `retryLabel`; `PageState` — `title`, `description`; `ActionListDialog` — `title`, `intro`; `ActionView.emptyMessage` | `empty-state`, `error`, `button`, `title`, `description` |
+| `dialog.alert/confirm/prompt/choose()` — `title`, `body`, `action`, `cancel`, `placeholder`, `actions[].label`                                                                             | papel correspondente do diálogo                          |
 | `TooltipContent` (children), `LabelHelp.help`                                                                                                                                              | `label`, `helper-text`                                   |
 
 ## Cobertura e significado do gate verde

package/docs/consumer-upgrade-propagation.md

@@ -52,6 +52,6 @@ Há três sinais diferentes e eles não devem ser confundidos:
 
 ## Verificação
 
-- o status do Maestro deve distinguir versão instalada, aplicada e adotada;
+- o status do Maestro deve distinguir versão disponível, adotada e aplicada;
 - fixtures com tokens removidos devem reprovar no detector de migração, enquanto texto de
   documentação e dependências geradas são ignorados.

package/docs/data-products.md

@@ -58,9 +58,11 @@ consumidores usam o nome qualificado; o alias só poderá ser removido numa vers
 ## Projeções
 
 `opus gen` publica os produtos no `.opus/manifest.json`. Actions expostas como tools carregam os
-IDs em `metadata.dataProducts`; no MCP, a chave é
-`_meta['com.softize.opus/data-products']`. Consumidores devem registrar apenas produtos associados
-a chamadas concluídas com sucesso.
+IDs em `metadata.dataProducts` e os rótulos legíveis em `metadata.dataProductLabels`, um mapa de ID
+para `label`. No MCP, as chaves são `_meta['com.softize.opus/data-products']` e
+`_meta['com.softize.opus/data-product-labels']`. Hosts mostram o rótulo às pessoas e usam o ID na
+execução e na auditoria. Consumidores devem registrar apenas produtos associados a chamadas
+concluídas com sucesso.
 
 O Opus Lens usa o manifest para mostrar a linhagem declarada entre Fontes, entities, produtos e
 Actions. Nenhuma dessas projeções é fonte autoritativa: corrija a declaração e gere novamente.

package/docs/protocol.md

@@ -604,7 +604,7 @@ Não vai ter `compose(authA, authB)` no core. Se sentir falta, é regra de negó
 
 O Opus **não autentica** — não valida token, não emite sessão. O adapter (server) recebe a request, valida o token via auth provider externo (Better Auth, Clerk, próprio), monta `ctx.user`, e entrega pro Opus. A partir daí, `authorize` decide.
 
-Se `ctx.user` é `null` e `public !== true`, runtime rejeita com `{ code: 'auth.unauthenticated', category: 'authentication' }` **antes** de chamar `authorize`.
+Se `ctx.user` é `null` e `public !== true`, runtime rejeita com `{ code: 'auth.unauthenticated', category: 'authentication' }` **antes** dos loaders e de `authorize`. Assim um chamador anônimo não dispara consultas nem descobre, pelo erro de um loader, se um registro existe.
 
 ---
 
@@ -1186,9 +1186,9 @@ ctx = { user, tenantId, can, db, emit, meta, ... }
    ↓
 Runtime.execute(action, input, ctx)
    ↓ (1) validate input contra schema
-   ↓ (2) load (se action declara `loads`)
-   ↓ (3) check public OR authenticate (ctx.user != null)
-   ↓ (4) authorize (chama action.authorize)
+   ↓ (2) check public OR authenticate (ctx.user != null)
+   ↓ (3) load (se action declara `loads`)
+   ↓ (4) authorize (chama action.authorize, que pode usar o que foi carregado)
    ↓ (5) handler executa
             (durante: handler pode chamar ctx.emit(event, data)
              → runtime publica via EventBusAdapter)
@@ -1426,14 +1426,14 @@ type BackgroundResult<T> =
 ```
 HTTP request → Server adapter
   ↓ (1) validate input
-  ↓ (2) load + authenticate + authorize
+  ↓ (2) authenticate + load + authorize
   ↓ (3) enqueue job via QueueAdapter + audit do enqueue
   ↓
 Server retorna JobHandle síncrono → client polla ou subscribe
   ↓
 Worker (processo separado) consome job:
   ↓ (a) reidrata auth/can e chama runtime.executeJob(spec, ctx, progress)
-  ↓ (b) revalida input + load + authenticate + authorize
+  ↓ (b) revalida input + authenticate + load + authorize
   ↓ (c) handler (recebe ProgressReporter se config.progress)
   ↓ (d) validate output + audit com provenance background
   ↓ (e) processor retorna/lança; BullMQ atualiza status done/failed

package/docs/releasing.md

@@ -13,6 +13,13 @@ configuração de escopo ou token de leitura.
 
 ## Release pela estação (o caminho normal)
 
+Antes de rodar, escreva no `CHANGELOG.md` a entrada `## X.Y.Z` da versão que vai sair. O script
+confere essa entrada só DEPOIS do bump, então esquecê-la aborta a release com o `package.json` já
+alterado — e a tentativa seguinte para na guarda de árvore limpa. Para recuperar, desfaça o bump
+(`git checkout -- package.json`), escreva a entrada, commite e rode de novo.
+
+Os comandos rodam em `packages/opus`; o `package.json` da raiz não tem `release`.
+
 ```bash
 pnpm release            # patch bump + publica no npm público
 pnpm release minor      # minor
@@ -53,7 +60,7 @@ pra testar publicação seria a guarda atrapalhando quem está experimentando.
 
 **Gate de qualidade**: depois do bump e da materialização, mas antes de publicar, roda
 `pnpm typecheck` + `pnpm test` + `pnpm copy:check` + `base copy check` e **aborta a release
-se qualquer um falhar**. O Opus declara `@softize/base ^2.2.1` em `dependencies`, pois usa
+se qualquer um falhar**. O Opus declara `@softize/base ^2.3.0` em `dependencies`, pois usa
 suas APIs públicas de filesystem em runtime, e materializa os artefatos Base no próprio repo;
 a release não baixa uma política ad hoc. Como o
 Opus **ship source** (`.ts`, sem build), essa é a última barreira antes do tarball — sem ela,
@@ -67,7 +74,7 @@ não é bloqueada por cobertura abaixo de 100%; a cobertura é acompanhada com `
 **Smoke do esqueleto**: depois do bump e antes do publish, o `release.sh` gera um app com
 `opus create`, instala o **tarball exato** que vai ser publicado e roda os gates dele
 (typecheck · test · `opus check` · `opus copy --check` · `base copy check` · manifest ·
-build). O template exige `@softize/base ^2.2.1`; publique a Base compatível antes do Opus.
+build). O template exige `@softize/base ^2.3.0`; publique a Base compatível antes do Opus.
 O `minimumReleaseAgeExclude` do template inclui os dois pacotes, e o smoke executa os
 fragmentos de pre-push para provar que o layout pnpm instalado resolve ambos os CLIs.
 É o que pega o que typecheck+test não
@@ -80,7 +87,24 @@ O script bumpa, publica **e leva o bump pra `origin/main`** — não sobra passo
 `--local` ele não commita nada (Verdaccio é sandbox). `pnpm release none` não cria diff de
 versão, mas ainda commita qualquer derivado que a materialização legitimamente atualizar.
 `--dry-run` encerra depois das mesmas materializações/gates/smoke, sem publish, commit ou
-push; use `none` para validar a versão atual sem sujar o manifesto.
+push; use `none` para validar a versão atual sem sujar o manifesto. Sem `--local`, o
+`--dry-run` também exige a `main` limpa e igual a `origin/main`.
+
+## A documentação é publicada à parte
+
+A release publica o pacote, não o site. `opus.softize.com.br` só muda quando alguém roda, na raiz
+do repositório:
+
+```bash
+pnpm deploy:docs
+```
+
+O script aplica as mesmas guardas de procedência da release, roda `typecheck`, `test`,
+`copy:check` e o `opus check` de `apps/opus`, builda o site e envia o resultado. Ele não roda o
+`base copy check` nem o smoke do esqueleto, que ficam com a release. Rode-o depois de cada
+release; sem isso, o site continua mostrando a versão anterior.
+Em setembro de 2026, o site ficou onze dias preso numa versão anterior à 13.0.0 enquanto o
+pacote chegava à 18.1.0. `pnpm deploy:docs --dry-run` valida sem enviar.
 
 ## Verificar
 
@@ -111,7 +135,7 @@ pnpm add @softize/opus@8.7.0-rc.0 --registry http://127.0.0.1:6873/
 
 Valide o app normalmente. Ao encerrar a sessão, restaure o intervalo de versão do
 consumidor para o npm e rode `pnpm install`; a prerelease local nunca é enviada ao npm.
-Para publicar outra tentativa, incremente o sucesso (`8.6.0-rc.1`, por exemplo) e repita
+Para publicar outra tentativa, incremente o sufixo (`8.7.0-rc.1`, por exemplo) e repita
 o mesmo fluxo.
 
 ## Auth

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "18.1.0",
+  "version": "18.2.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/references/ui-patterns.md

@@ -73,6 +73,11 @@ ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader`
 - `ActionFilterBar` renderiza busca, filtros, período e ações declarados por uma list action
   quando a tela precisa da toolbar sem entregar os resultados a `ActionList`. Manter seu
   `state` e `onStateChange` ligados à mesma projeção de URL usada pela superfície.
+- Filtros de list action declaram onde aparecem com `placement`: `inline` fica na barra;
+  `advanced` vai para o painel de filtros avançados, agrupado por `section` e distribuído em até
+  três colunas com `advancedFilters.columns`; `external` continua no estado navegável e no input,
+  mas a tela apresenta o controle por conta própria. `advanced: true` segue aceito só durante a
+  migração; em código novo, declarar `placement`.
 - `ActionForm` mantém validação, execução e estados do contrato nos dois modos: sem `children`,
   renderiza os campos declarados; com `children`, o consumidor diagrama `ActionFormField` e
   controles customizados pelo contexto. `ActionFormCard` e `ActionFormDialog` acrescentam a
@@ -81,8 +86,13 @@ ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader`
   a ação principal mantém `solid`. Criação e edição comuns preservam o rótulo padrão `Salvar`;
   `submitLabel` fica para efeitos específicos, como `Renomear` ou `Criar nova versão`. Em
   `Dialog mode="alert"`, a saída segura também usa `outline`.
+- `DialogFooter` e `DrawerFooter` cuidam só da faixa. Agrupar e distribuir as decisões cabe a um
+  `ButtonGroup` dentro deles, com `distribution="equal"` para o footer 50/50; botões soltos no
+  footer não são distribuídos. `ActionFormDialog` já compõe isso: por padrão o footer acompanha o
+  conteúdo com o cancelamento em `ghost`, e `footerDistribution="equal"` divide a faixa e passa o
+  cancelamento a `outline`.
 - Cabeçalhos de `Dialog` e `Drawer` nomeiam a superfície com o título e organizam suas ações. O close
-  padrão é uma action ghost somente com ícone no final do header; não crie uma posição flutuante
+  padrão é o `CloseButton` (`neutral`, `subtle`, pílula) no final do header, sem posição flutuante
   alternativa. Não preencher uma segunda linha por hábito. Consequência, restrição ou instrução que
   realmente mude a tarefa entra no início de `DialogBody`/`DrawerBody`, como texto ou `Alert`;
   wrappers usam `intro` e a API imperativa usa `body`. Relacione texto conciso por

package/src/auth/drivers/jwt.ts

@@ -34,7 +34,8 @@ import type { AuthAdapter, CanFn, User } from '../../core/index.ts'
 // =============================================================================
 
 export interface JwtAuthOptions<P extends JwtPayload = JwtPayload> {
-  /** Secret HMAC ou public key. Pode ser string sync ou async resolver. */
+  /** Secret HMAC ou public key, fixo ou por resolver (sync ou async). O resolver é chamado
+   *  sem argumentos: a escolha da chave pelo `kid` do token ainda não é suportada. */
   secret: string | Buffer | ((kid?: string) => Promise<string | Buffer> | string | Buffer)
 
   /** Algorithms aceitos (default ['HS256']). */