@softize/opus 14.0.0 → 15.0.0

package/CHANGELOG.md

@@ -7,6 +7,69 @@ 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.
 
+## 15.0.0 — 2026-09-09
+
+`PageHeader` passa a oferecer `variant="bar"`, uma apresentação compacta da mesma região de título,
+descrição e ações. O novo `PageBack` recebe o destino pai explícito: no header padrão fica acima do
+título com rótulo; na barra vira icon-only com tooltip e nome acessível. Páginas comuns deixam de
+precisar de um chrome paralelo, enquanto `PageActionsTarget` permanece para workspaces imersivos que
+já tenham uma faixa própria. Para hierarquias com mais de um ancestral, `PageNavigation` recebe o
+`Breadcrumb` na mesma posição introdutória e não pode ser combinado com `PageBack`. Ações em barra
+usam a escala compacta: `sm` com texto e `icon-sm` quando exibem somente um ícone.
+
+`PageState` passa a centralizar carregamento, falha e vazio sem moldura e a ocupar a altura
+disponível. `Page` reconhece o estado mesmo quando um componente intermediário o renderiza, oculta
+o cabeçalho inteiro nos três estados e o restaura em `ready`. A falha mantém `role="alert"`, deixa
+de usar o visual de `Alert` e apresenta a recuperação como botão `outline` textual. A moldura tracejada continua disponível no `Empty` usado diretamente para
+representar uma região disponível à criação ou vínculo.
+
+O CLI carrega o `.env` ao lado do `opus.config.ts` antes de importar o config, em `db`, `seed` e
+`gen`. O config do consumer costuma abrir o banco no topo do módulo, lendo `process.env` na hora
+do import: sem isso, um projeto que guarda a URL no `.env` migrava o banco DEFAULT do config
+enquanto o runtime usava outro, e o schema aplicado sumia do banco que a aplicação abre. Variável
+já definida no ambiente vence o arquivo (a semântica do `--env-file` do Node), então
+`DATABASE_URL=... opus db migrate` e a injeção do container seguem mandando; ausência de `.env`
+é normal e não é erro. Um projeto que já carregava o `.env` por conta própria no `opus.config.ts`
+continua correto: as duas cargas são idempotentes e a primeira vence.
+
+**Breaking — API removida.** `Page` deixa de aceitar `count` e o barrel deixa de exportar
+`PageMeta` (ADR 0009). O cabeçalho da página reconhece somente `PageTitle`, `PageDescription`,
+`PageActions` e a região introdutória; um total vai para o conteúdo que o explica — a listagem, a
+métrica ou uma seção com `Content`, onde `ContentMeta` e `Content.count` continuam disponíveis.
+`PageBack` passa a exigir `href`: sem destino, o elemento não era tabulável nem tinha nome
+acessível. `PageNavigation` e `PageBack` não podem ser combinados na mesma página: escolha o
+retorno de um ancestral só ou a trilha completa.
+
+**Breaking — comportamento e DOM.** `Page` oculta o `PageHeader` inteiro enquanto o `PageState`
+estiver em carregamento, erro ou vazio, sem opt-out. Teste que procura o título da página durante a
+carga passa a falhar; o nível semântico segue disponível no `role="heading"` da própria superfície
+de estado. Some junto a região introdutória, então uma subpágina em erro fica sem o `PageBack` para
+o pai; quem depende desse retorno oferece a saída pelo `action` do próprio `PageState`. O motivo, a
+alternativa descartada e esse custo estão no adendo da ADR 0004. O erro e o vazio do `PageState`
+trocam de anatomia: sai `[data-slot="alert"]` e `[data-slot="alert-actions"]`, entram `error-state`
+e `state-actions`, e o vazio passa de `data-frame="region"` para `bare`. As ações de linha do
+`ActionList` passam a vir dentro de um `ButtonGroup`, o que acrescenta um `role="group"` por linha;
+as ações da barra (Filtros, Recarregar, Exibição) passaram de `outline` para `ghost`, e o que o
+consumidor entrega em `ActionFilterBar.actions` agora fica depois do grupo de controles auxiliares,
+no fim da barra. A recuperação do aviso inline de erro virou ação só de ícone, com o rótulo no nome
+acessível e no tooltip em vez do texto na tela. Quem afirma texto, variante ou slot nesses pontos
+precisa revisar as asserções.
+
+**Breaking — ícones voltam à escala.** `controlGlyph` passa a devolver seletores literais. Montada
+em runtime, a classe saía certa no DOM, mas o scanner do Tailwind não a via e o CSS nunca era
+gerado: na prática, todo ícone de `Button` sem `size-*` próprio vinha no tamanho padrão do lucide.
+Agora todos passam a medir o degrau da escala, então ícones encolhem visivelmente no consumidor. O
+`ActionTrigger` só de ícone usa `icon-xs` (1.5rem) por padrão, o degrau da ação que mora dentro de
+uma linha densa, e passa a respeitar um `size` declarado quando a composição pede mais presença —
+`icon-sm` na barra, por exemplo. Atenção ao inverso: um `size` que antes era ignorado no modo
+ícone passa a valer, então `size="lg"` esquecido ao lado de `icon` agora produz um botão de altura
+de texto com um ícone só.
+
+Do lado aditivo, `ButtonGroup` ganha `mode`: `connected`, o comportamento de sempre com as bordas
+coladas, e `spaced`, que só agrupa e espaça — é o que as ações de linha e os controles auxiliares
+da barra do `ActionList` passam a usar. `ActionList` ganha `toolbarActions` para o que o consumidor
+acrescenta no fim da barra de filtros.
+
 ## 14.0.0 — 2026-09-09
 
 Estados vazio, carregando e erro passam a uma composição só. `DataState` compõe `Empty` (moldura

package/bin/cli.mjs

@@ -328,6 +328,8 @@ Flags
   --json             (introspect, seed) Saída estruturada em JSON.
   --monorepo         (create) Cria a raiz do workspace em vez de um app.
   --config <path>    (gen, db, seed) Caminho do opus.config.ts. Default: ./opus.config.ts.
+                     O .env ao lado desse arquivo é carregado antes do config; variável
+                     já definida no ambiente vence o arquivo.
   --output <path>    (gen) Pasta de saída. Default: a do config, ou ./.gen.
   --profile <nome>   (seed) Perfil do dataset. Default: o defaultProfile do seed.
   --scope <nome>     (seed) Escopo explícito dos dados. Alternativa: OPUS_SEED_SCOPE.

package/bin/lib/check.mjs

@@ -107,8 +107,9 @@ const UI_STRUCTURAL_PARENTS = new Map([
   ["PageHeader", new Set(["Page"])],
   ["PageBody", new Set(["Page"])],
   ["PageTitle", new Set(["PageHeader"])],
+  ["PageBack", new Set(["PageHeader"])],
+  ["PageNavigation", new Set(["PageHeader"])],
   ["PageDescription", new Set(["PageHeader"])],
-  ["PageMeta", new Set(["PageHeader"])],
   ["PageActions", new Set(["PageHeader"])],
   ["ContentHeader", new Set(["Content"])],
   ["ContentBody", new Set(["Content"])],
@@ -166,7 +167,11 @@ const UI_STRUCTURAL_ROOTS = new Map([
     {
       header: "PageHeader",
       body: "PageBody",
-      shorthand: new Set(["title", "description", "count", "actions"]),
+      shorthand: new Set(["title", "description", "actions"]),
+      // O contador saiu do título da página (ADR 0009). Tirar `count` do shorthand não proíbe
+      // nada sozinho — só apaga o marcador que fazia o gate enxergar aquele Page —, então a
+      // prop removida é cobrada aqui, nas duas formas de composição.
+      removed: new Map([["count", "o total pertence ao conteúdo que o explica"]]),
     },
   ],
   [
@@ -174,7 +179,8 @@ const UI_STRUCTURAL_ROOTS = new Map([
     {
       header: "ContentHeader",
       body: "ContentBody",
-      shorthand: new Set(["title", "description", "meta", "actions"]),
+      shorthand: new Set(["title", "description", "count", "actions"]),
+      removed: new Map([["meta", "use `count`"]]),
     },
   ],
 ]);
@@ -183,8 +189,9 @@ const UI_STRICT_DIRECT_COMPONENTS = new Set([
   "PageHeader",
   "PageBody",
   "PageTitle",
+  "PageBack",
+  "PageNavigation",
   "PageDescription",
-  "PageMeta",
   "PageActions",
   "ContentHeader",
   "ContentBody",
@@ -202,7 +209,13 @@ const UI_STRUCTURAL_HEADERS = new Map([
     "PageHeader",
     {
       title: "PageTitle",
-      optional: new Set(["PageDescription", "PageMeta", "PageActions"]),
+      optional: new Set([
+        "PageBack",
+        "PageNavigation",
+        "PageDescription",
+        "PageActions",
+      ]),
+      exclusive: [new Set(["PageBack", "PageNavigation"])],
       shorthand: new Set(),
     },
   ],
@@ -898,6 +911,10 @@ export function checkUiStructure(file, text) {
             (name) =>
               children.names.filter((child) => child === name).length > 1,
           );
+          const combinedExclusive = (header.exclusive ?? []).some(
+            (group) =>
+              children.names.filter((name) => group.has(name)).length > 1,
+          );
           const titleValid =
             header.titleRequired === false ? titles <= 1 : titles === 1;
           const recognizedContent =
@@ -910,6 +927,7 @@ export function checkUiStructure(file, text) {
               !(header.allowOpaque && children.hasOpaque)) ||
             unexpected ||
             duplicatedOptional ||
+            combinedExclusive ||
             (children.hasOpaque && !header.allowOpaque)
           ) {
             add(
@@ -932,6 +950,16 @@ export function checkUiStructure(file, text) {
               : [],
           ),
         );
+        for (const [attribute, hint] of root.removed ?? []) {
+          if (attributes.has(attribute)) {
+            add(
+              node,
+              component,
+              `${component} não aceita mais a propriedade \`${attribute}\`: ${hint}.`,
+              "ui-structure-removed-prop",
+            );
+          }
+        }
         const shorthand = [...root.shorthand].some((attribute) =>
           attributes.has(attribute),
         );

package/bin/lib/cli-shared.mjs

@@ -55,10 +55,39 @@ export async function fileExists(file) {
 // Config do consumer
 // =============================================================================
 
+/**
+ * Carrega o `.env` ao lado do `opus.config.ts` no processo do CLI, para que ele chegue
+ * aos runners (que herdam o ambiente) ANTES de o config do consumer ser importado.
+ *
+ * O config costuma abrir a conexão do banco no topo do módulo, lendo `process.env` na
+ * hora do import: sem isto, `db` e `seed` caem na conexão default e operam um banco
+ * diferente do que o runtime do projeto usa. Ausência do arquivo é normal (container e
+ * CI injetam por ambiente) e não é erro; qualquer outra falha de leitura sobe.
+ *
+ * Variável já definida no ambiente VENCE o arquivo (semântica do `--env-file` do Node),
+ * então `DATABASE_URL=... opus db migrate` e a injeção do container continuam mandando.
+ *
+ * Devolve o caminho carregado, ou `null` quando não havia `.env`.
+ */
+export function loadProjectEnv(configPath) {
+  const envFile = path.join(path.dirname(configPath), '.env')
+  try {
+    process.loadEnvFile(envFile)
+    return envFile
+  } catch (cause) {
+    if (cause.code === 'ENOENT') return null
+    throw cause
+  }
+}
+
 /**
  * Resolve o `opus.config.ts` a partir de `flags.config` (default: `./opus.config.ts`),
  * contido no projeto. Lança `Error` com uma mensagem única quando o arquivo não existe;
  * cada comando decide o canal (texto ou JSON) e o código de saída.
+ *
+ * Resolver o config é também o momento em que o projeto passa a ser conhecido, então o
+ * `.env` dele é carregado aqui (ver `loadProjectEnv`) — em um lugar só, para que nenhum
+ * comando que importe o config do consumer possa esquecer.
  */
 export function resolveConfig(flags, cwd = process.cwd()) {
   const root = canonicalProjectDirectory(cwd)
@@ -69,7 +98,7 @@ export function resolveConfig(flags, cwd = process.cwd()) {
         'Passe o caminho com --config <path> ou crie o arquivo na raiz do projeto.',
     )
   }
-  return { cwd: root, configPath: config.path }
+  return { cwd: root, configPath: config.path, envFile: loadProjectEnv(config.path) }
 }
 
 // =============================================================================

package/bin/lib/copy.mjs

@@ -103,6 +103,9 @@ const JSX_CHILD_ROLES = new Map([
   ['PopoverDescription', 'description'],
   ['PopoverTitle', 'title'],
   ['PageDescription', 'description'],
+  // O texto do PageBack é o NOME do destino ('Clientes'), como um item de trilha — não um
+  // comando. Classificado como `button`, a política universal cobraria verbo de ação.
+  ['PageBack', 'breadcrumb'],
   ['PageTitle', 'title'],
   ['TableCaption', 'description'],
   ['TableHead', 'heading'],

package/bin/lib/db.mjs

@@ -189,6 +189,8 @@ export function helpDb() {
 
 Flags:
   --config <path>   Caminho interno ao projeto para opus.config.ts. Default: ./opus.config.ts
+                    O .env ao lado dele é carregado antes do config, então DATABASE_URL do
+                    projeto vale sem export manual; variável do ambiente vence o arquivo.
   --help, -h        Mostra esta mensagem
 
 O opus.config.ts precisa expor, pros comandos db:

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

@@ -1,5 +1,10 @@
 # ADR 0004 — O estado integral do conteúdo é composto dentro de Page
 
+> **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
+> adendo no fim deste arquivo registra o motivo, a alternativa descartada e o que se perde.
+
 ## Contexto
 
 `Page` padroniza o `<main>`, o cabeçalho e o container de uma página. Hoje, consumidores que ainda
@@ -21,15 +26,21 @@ direto de `Page`, que materializa `PageBody`; na composição explícita, `PageS
 `PageState`:
 
 - recebe um estado discriminado entre `loading`, `error`, `empty` e `ready`;
-- preserva o cabeçalho da página em todos os estados;
-- compõe `Spinner`, `Alert` e `Empty` em vez de recriar suas superfícies;
+- oculta o cabeçalho em `loading`, `error` e `empty`, restaurando-o em `ready`;
+- registra sua presença no `Page` mesmo quando um componente intermediário o renderiza;
+- ocupa a altura disponível e usa o título visível do estado como heading principal;
+- centraliza os três estados integrais com uma anatomia visual comum e sem moldura;
+- preserva `role="status"` no carregamento e `role="alert"` na falha sem apresentar o erro como `Alert`;
 - aceita título, descrição, ícone e ação contextual sem exibir erro técnico;
+- apresenta a recuperação integral como botão `outline` textual; o ícone isolado fica restrito a
+  superfícies compactas;
 - expõe `data-slot="page-state"` e `data-status` para testes e análise estrutural;
 - renderiza o conteúdo sem moldura adicional em `ready`.
 
 Estados parciais continuam pertencendo a `DataState`, `ActionView`, `ActionList` ou `Alert`, conforme
-a fronteira afetada. Uma coleção vazia continua dentro da estrutura da coleção; `Empty` representa
-uma região disponível, uma escolha pendente ou uma próxima ação.
+a fronteira afetada. Uma coleção vazia continua dentro da estrutura da coleção. A moldura tracejada
+de `Empty` representa uma região disponível para criar ou vincular; ela não aparece automaticamente
+no vazio integral de uma página.
 
 ## Alternativas consideradas
 
@@ -51,7 +62,8 @@ telas equivalentes.
 
 ## Consequências
 
-- Consumidores ganham uma composição uniforme sem acoplar `Page` a hooks ou actions.
+- Consumidores ganham uma composição uniforme sem acoplar `Page` a hooks ou actions e sem repetir
+  classes de altura.
 - A copy específica do fluxo permanece no consumidor; defaults seguros cobrem usos simples.
 - Migrações precisam distinguir estado integral de estado parcial antes de substituir a composição.
 - O gate estrutural do consumidor deve impedir novos estados integrais montados manualmente.
@@ -63,3 +75,25 @@ telas equivalentes.
   composição explícita.
 - Consumidores verificam `data-slot="page-state"` nos estados integrais e mantêm testes próprios para
   recuperação e distinção entre erro e vazio.
+
+## Adendo (2026-09-09) — o cabeçalho é ocultado nos estados integrais
+
+**Contexto.** A decisão original preservava o cabeçalho em `loading`, `error` e `empty`. Na
+prática, uma página em carregamento mostrava título e ações de um conteúdo que ainda não existia, e
+uma página em erro oferecia ações sobre um conteúdo que falhou. A ADR 0010, ao trazer a
+apresentação em barra, tornou isso mais visível: a faixa ficava de pé, com ações inertes, sobre uma
+superfície de estado que ocupa a tela inteira.
+
+**Decisão.** `Page` oculta o `PageHeader` enquanto o `PageState` estiver em `loading`, `error` ou
+`empty`, e o restaura em `ready`. Não há opt-out. O nível semântico não se perde: a própria
+superfície de estado carrega `role="heading"` com `aria-level={1}`.
+
+**Alternativa descartada.** Ocultar apenas título, descrição e ações, preservando a região
+introdutória. Foi descartada para esta versão porque partiria o cabeçalho em duas regras de
+visibilidade e deixaria a barra materializada só para um botão, contrariando "um header sem
+conteúdo útil não é materializado" da ADR 0010.
+
+**O que se perde, e é conhecido.** Some junto o `PageBack`, então uma subpágina em erro fica sem o
+retorno in-page para o pai — justamente quando a pessoa mais precisa sair. Enquanto esta ADR não
+for revista, uma subpágina que dependa desse retorno oferece a saída pelo `action` do próprio
+`PageState`. Reavaliar se o custo aparecer em uso real.

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

@@ -3,6 +3,10 @@
 - **Status:** aceita.
 - **Data:** 2026-09-04.
 
+> **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.
+
 ## Contexto
 
 Os componentes estruturais da UI descrevem regiões equivalentes com APIs diferentes. `Dialog`
@@ -20,8 +24,9 @@ perdida para obter uma estrutura explícita.
 As superfícies mantidas pela casa adotam a gramática `Root > Header + Body + Footer`, com
 `Title`, `Description`, `Meta` e `Actions` pertencendo ao `Header` da mesma família.
 
-- `Page` oferece `PageHeader`, `PageTitle`, `PageDescription`, `PageMeta`, `PageActions` e
-  `PageBody`.
+- `Page` oferece `PageHeader`, `PageBack`, `PageNavigation`, `PageTitle`, `PageDescription`,
+  `PageActions` e `PageBody`. A ADR 0010 acrescenta as apresentações `default` e `bar` ao mesmo
+  header.
 - `Content` representa uma região de conteúdo semanticamente nomeada e oferece `ContentHeader`,
   `ContentTitle`, `ContentDescription`, `ContentMeta`, `ContentActions` e `ContentBody`.
 - `CardContent` passa a ter `CardBody` como nome canônico.
@@ -37,7 +42,8 @@ As superfícies mantidas pela casa adotam a gramática `Root > Header + Body + F
   `ItemActions` e `ItemFooter`. `ItemContent` permanece temporariamente como alias legado de
   corpo, mas deixa de envolver título e descrição no código novo.
 
-`Page` e `Content` aceitam também uma forma curta com `title`, `description`, `meta` e `actions`.
+`Page` e `Content` aceitam também uma forma curta: `title`, `description` e `actions` nos dois,
+mais `count` no `Content`. A ADR 0009 tirou o contador do título da página.
 Essa forma é açúcar sintático: produz a mesma árvore semântica, os mesmos estilos e os mesmos
 `data-slot` da composição explícita. Um consumidor não pode misturar as duas formas na mesma raiz.
 

package/docs/adr/0009-page-title-does-not-carry-a-counter.md

@@ -0,0 +1,57 @@
+# ADR 0009 — O título da página não carrega contador
+
+- **Status:** aceita.
+- **Data:** 2026-09-09.
+- **Substitui parcialmente:** ADR 0005, somente quanto a `PageMeta` e `count` em `Page`.
+
+## Contexto
+
+`Page` permitia colocar um total imediatamente ao lado do título por `count` ou `PageMeta`. O
+número competia com a identidade da página, não explicava sozinho o conjunto contado e repetia
+informação que já pertence à listagem ou a uma seção do conteúdo.
+
+`Content` também possui metadata, mas representa regiões menores em que o valor pode estar ligado
+ao título local e continuar compreensível dentro da própria seção.
+
+## Decisão
+
+`Page` deixa de aceitar `count` e de exportar `PageMeta`. O cabeçalho da página reconhece somente
+`PageTitle`, `PageDescription` e `PageActions`. Totais e outros indicadores pertencem ao conteúdo
+que os explica, como uma listagem, métrica ou seção composta com `Content`.
+
+`ContentMeta` e o `count` de `Content` permanecem disponíveis. A anatomia compartilhada continua
+sendo usada, mas cada família expõe apenas os slots coerentes com sua escala.
+
+## Consequências
+
+- O título da página volta a comunicar somente a identidade da superfície.
+- Consumidores removem contadores do cabeçalho em vez de deslocá-los para outra posição sem
+  contexto.
+- Uma página que precise destacar um total o apresenta no corpo, próximo do conjunto ou da métrica
+  correspondente.
+- A remoção de `count` e `PageMeta` é incompatível e entra somente na próxima versão major.
+
+## Alternativas consideradas
+
+### Manter o contador como opção
+
+Preservaria compatibilidade, mas manteria uma composição visual que a aplicação já decidiu não
+usar. Foi descartada porque uma opção pública continuaria incentivando o retorno do padrão.
+
+### Ocultar o contador apenas no tema
+
+Evitaria a migração imediata, mas deixaria contrato, documentação e DOM sustentando uma capacidade
+sem representação. Foi descartada porque esconder não remove o padrão.
+
+### Mover automaticamente o total para a descrição
+
+Preservaria a informação, mas o componente não conhece o que está sendo contado nem consegue
+escrever contexto correto. Foi descartada para que o consumidor escolha uma superfície semântica
+quando o total for realmente necessário.
+
+## Verificação
+
+- O tipo de `Page` não aceita `count` e o barrel público não exporta `PageMeta`.
+- Testes de UI verificam a anatomia curta e explícita sem `page-meta`.
+- Busca estrutural impede usos de `count` em `Page` nos consumidores migrados.
+- Documentação e metadata públicas apresentam somente título, descrição e ações.

package/docs/adr/0010-page-header-owns-page-chrome.md

@@ -0,0 +1,73 @@
+# ADR 0010 — PageHeader também representa o chrome compacto da página
+
+- **Status:** aceita.
+- **Data:** 2026-09-09.
+- **Complementa:** ADR 0005.
+
+## Contexto
+
+Aplicações com sidebar passaram a montar uma barra superior separada de `PageHeader` para reunir
+navegação contextual e ações. Essa separação cria dois cabeçalhos para a mesma página, distribui
+título, retorno e ações entre contratos concorrentes e permite reservar uma faixa vazia quando o
+shell não recebe conteúdo.
+
+O breadcrumb absoluto também repete a localização já comunicada pela sidebar e pelo título. Em uma
+subpágina simples, a necessidade real é retornar a um pai conhecido; em hierarquias mais profundas,
+é apresentar os ancestrais relevantes. Nenhum dos casos exige uma segunda anatomia de cabeçalho.
+
+## Decisão
+
+`PageHeader` é a única região de cabeçalho de uma `Page` e oferece duas apresentações:
+
+- `variant="default"` organiza título, descrição e ações dentro do container da página;
+- `variant="bar"` ocupa uma faixa compacta, delimitada por borda, no topo da página.
+
+`PageBack` pertence diretamente a `PageHeader` e recebe um destino explícito. Na apresentação
+padrão, aparece acima do conjunto de título e descrição como botão `ghost` com ícone e rótulo. Na
+barra, aparece como controle icon-only com tooltip e nome acessível derivados do destino visível.
+`PageBack` e breadcrumb não aparecem juntos: retorno simples usa `PageBack`; múltiplos ancestrais
+relevantes são compostos com `Breadcrumb` dentro de `PageNavigation`, na mesma posição do
+cabeçalho.
+
+A variante altera somente a apresentação. Título, descrição, retorno e ações continuam pertencendo
+semanticamente à mesma página. Um header sem conteúdo útil não é materializado para reservar
+altura, e o header é ocultado durante os estados integrais do `PageState` — inversão da decisão
+original da ADR 0004, argumentada no adendo dela. Para acompanhar o ritmo
+compacto da barra, ações com texto usam `Button size="sm"` e ações somente com ícone usam
+`Button size="icon-sm"`.
+
+## Consequências
+
+- shells deixam de precisar de um `PageChrome` paralelo para páginas comuns;
+- páginas de primeiro nível usam o header padrão e não ganham uma barra vazia;
+- subpáginas simples mantêm o retorno junto ao título na apresentação padrão;
+- recursos que precisam de uma faixa persistente podem escolher `variant="bar"` sem mover ações por
+  portal;
+- botões da barra deixam de misturar a escala normal da página com controles compactos;
+- workspaces imersivos ainda podem manter um shell próprio quando não são representados por `Page`.
+
+## Alternativas consideradas
+
+### Manter PageHeader e chrome separados
+
+Preservaria a implementação atual dos consumidores, mas continuaria dividindo uma única região
+semântica entre duas APIs e exigindo regras para decidir onde cada ação aparece.
+
+### Exibir breadcrumb absoluto em toda subpágina
+
+Ofereceria uma trilha uniforme, mas repetiria a navegação global já visível e ocuparia espaço com a
+página atual, que já está nomeada pelo título.
+
+### Usar sempre uma barra
+
+Fixaria a posição dos controles, mas reservaria altura em páginas que não possuem navegação
+contextual nem ações persistentes. A barra permanece uma escolha de apresentação, não o default.
+
+## Verificação
+
+- testes de `Page` cobrem as duas variantes, a posição de `PageBack`, sua acessibilidade e o destino
+  explícito;
+- `opus check` reconhece `PageBack` e `PageNavigation` somente como filhos diretos e mutuamente
+  exclusivos de `PageHeader`;
+- a documentação demonstra retorno simples nas duas apresentações e separa esse caso de breadcrumb;
+- consumidores removem barras paralelas à medida que migram para a anatomia de `Page`.

package/docs/data-layer.md

@@ -70,6 +70,15 @@ opus db migrate       # aplica o SCHEMA IDEMPOTENTE + drift-check na sequência
 opus db scaffold      # gera rascunho a partir do diff (referência pro schema)
 ```
 
+**De onde vem a conexão.** O config do consumer costuma abrir o banco no topo do módulo,
+lendo `process.env` na hora do import. Por isso o CLI carrega o `.env` ao lado do
+`opus.config.ts` ANTES de importar o config — em `db`, `seed` e `gen`, num lugar só, para
+que nenhum comando possa esquecer. Variável já definida no ambiente vence o arquivo (a
+semântica do `--env-file` do Node), então `DATABASE_URL=... opus db migrate` e a injeção
+do container continuam mandando; ausência de `.env` é normal e não é erro. Sem isso, um
+projeto que guarda a URL no `.env` migrava o banco DEFAULT do config enquanto o runtime
+usava outro — o schema aplicado some do banco que a aplicação abre.
+
 **Schema idempotente evolutivo** (o padrão da casa, não migration versionada): UM
 script SQL (`config.schema`, ex. `src/db/schema.sql`) re-rodável — `CREATE IF NOT
 EXISTS` + guards `DO $$ IF EXISTS` cobrem nascer do zero E upgrade de prod no mesmo

package/package.json

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

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

@@ -42,8 +42,9 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
    o produto precisa de deep link, back/forward ou refresh.
 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
+   respectivos `*Body`. Para o caso direto, usar a sintaxe abreviada de `Page` (`title`,
+   `description`, `actions`) ou de `Content` (as mesmas mais `count`); não misturá-la com o
+   header explícito. O título da página não carrega contador. 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

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

@@ -5,18 +5,29 @@
   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>` 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.
+  explícita é `Page > PageHeader (PageBack? | PageNavigation?, PageTitle, PageDescription?,
+  PageActions?) + PageBody`; `title`, `description` 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.
+- `PageHeader` é a única região de cabeçalho da página. O default acompanha o container;
+  `variant="bar"` apresenta a mesma anatomia como faixa compacta no topo. Em uma subpágina simples,
+  `PageBack` recebe o destino pai explícito: aparece acima do título no default e como icon-only com
+  tooltip na barra. Para mais de um ancestral relevante, use `Breadcrumb` dentro de
+  `PageNavigation`. Não combine retorno e breadcrumb nem crie um chrome paralelo para uma `Page`.
+  Ações com texto na barra usam `Button size="sm"`; ações somente com ícone usam `icon-sm`.
+  `PageActionsTarget` fica reservado a workspaces imersivos que já possuam chrome próprio.
 - `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.
+  explícita, fica sozinho dentro de `PageBody`. Nos três estados ativos, o cabeçalho some, o estado
+  ocupa a área disponível e seu título assume o heading principal, inclusive quando um componente
+  intermediário renderiza o estado. O erro mantém `role="alert"`, usa a mesma composição central e
+  sem moldura dos demais estados e apresenta a recuperação como botão `outline` textual. 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
+  solto. `title`, `description`, `count` 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`.