@softize/opus 10.0.0 → 11.1.0

package/CHANGELOG.md

@@ -6,11 +6,54 @@ Este arquivo viaja no pacote: num projeto, leia `node_modules/@softize/opus/CHAN
 Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `manifest:check`) — eles apontam o que a mudança cobra do seu código.
 
+## 11.1.0 — 2026-08-21
+
+O Opus passa a distribuir a skill `write-product-communication` para orientar documentação,
+interface, mensagens de erro, CLI, onboarding e textos explicativos a partir da situação do
+leitor. A página antes dedicada apenas a microcopy agora reúne a referência canônica de
+comunicação, incluindo escrita normativa e tratamento de erros.
+
+O `opus setup` expande o conteúdo dessa referência ao materializar a skill em `.agents` e
+`.claude`. As instruções permanentes e as skills de UI, actions, mudanças e upgrades passam a
+acionar a orientação nos fluxos em que produzem texto. Testes de criação e setup confirmam que
+projetos novos recebem o conteúdo completo, sem depender de um link externo.
+
+A home, as páginas iniciais e a mensagem de sucesso do `opus check` começam a migração da voz
+existente: apresentam contexto e efeito antes das regras, evitam slogans e informam a próxima
+etapa em linguagem natural.
+
 > As entradas 2.30.1–2.31.5 foram **reconstruídas do git** (o release publicava sem
 > passar por aqui). Uma delas — a 2.31.5, que mudou o rem base — é visual GLOBAL e
 > tinha ficado sem registro nenhum, o que é exatamente o caso que este arquivo existe
 > pra cobrir.
 
+## 11.0.0 — 2026-08-21
+
+**Breaking — deprecateds removidos na fronteira pública.** O major anterior manteve por
+engano APIs cuja própria documentação prometia remoção na próxima versão; esta versão
+fecha a migração em vez de carregar duas taxonomias indefinidamente.
+
+- `AppShell`, `AppShellBar`, `AppShellTrigger`, `useAppShell`, `useSidebarSlot` e
+  `SectionShell` (incluindo seus tipos `Section*`) saem. Componha chrome e seções com
+  `Split`, `Pane`, `Sidebar`, `PaneHeader`, `PaneContent`, `PaneFooter` e `SidebarNav`.
+- `ResizablePanelGroup`, `ResizablePanel` e `ResizableHandle` deixam de ser exports
+  públicos. Use `<Split resizable>` e declare tamanho/limites nos `<Pane>`.
+- `SidebarHeader`, `SidebarContent` e `SidebarFooter` saem; eram aliases de
+  `PaneHeader`, `PaneContent` e `PaneFooter`.
+- `DomainConfig.models` sai. Declare entidades em `DomainConfig.entities`; os comandos
+  `opus db` e o gerador agora leem somente esse campo. O manifest deixa de emitir o array
+  redundante `models`; os nomes continuam disponíveis em `entities[].name`.
+
+`SidebarNav` passa a aceitar `subgroups`, cobrindo navegação contextual e a árvore de três
+níveis da documentação sem um shell especializado. `ShellNav` agora deriva o estado
+recolhido diretamente da `Sidebar`. O próprio `DocBrowser` foi migrado para a composição
+canônica e serve como consumidor de referência.
+
+**Migração:** substitua shells prontos pela composição `Split > Pane > Sidebar`; troque os
+aliases `Sidebar*` pelos slots `Pane*`; envolva painéis ajustáveis em `<Split resizable>`;
+renomeie `domain.models` para `domain.entities` e, ao consumir manifest, derive nomes de
+`domain.entities.map(entity => entity.name)`.
+
 ## 10.0.0 — 2026-08-20
 
 **Breaking — forma usa a escala do Tailwind e superfícies sempre carregam seu foreground.**

package/bin/cli.mjs

@@ -190,7 +190,7 @@ async function cmdCheck(dir) {
   }
   const viaContrato = contracts > 0 ? ` (${contracts} contrato(s))` : ''
   if (findings.length === 0) {
-    log('success', `✓ opus check: ${actions} action(s)${viaContrato}, 0 violação — padrão ok.`)
+    log('success', `✓ opus check: ${actions} action(s)${viaContrato}; nenhuma violação encontrada.`)
     return
   }
 

package/bin/lib/db-check-runner.mjs

@@ -8,7 +8,7 @@
  *
  * Contrato do `opus.config.ts` pros comandos `db`:
  *   - `entities?: EntityConfig[]`        — entidades explícitas (opcional)
- *   - `domains?: DomainConfig[]`         — entidades coletadas de `domain.models`
+ *   - `domains?: DomainConfig[]`         — entidades coletadas de `domain.entities`
  *   - `database: () => Kysely | Promise<Kysely>`  — factory LAZY do banco.
  *     É factory (não instância) de propósito: o `gen` importa o mesmo config
  *     sem nunca chamar `database()`, então não abre conexão.
@@ -29,9 +29,9 @@ function emit(obj) {
 
 function collectEntities(domain, out) {
   if (domain === null || typeof domain !== 'object') return
-  const models = domain.models
-  if (models !== undefined && models !== null && typeof models === 'object') {
-    for (const value of Object.values(models)) {
+  const entities = domain.entities
+  if (entities !== undefined && entities !== null && typeof entities === 'object') {
+    for (const value of Object.values(entities)) {
       if (isEntityConfig(value)) out.push(value)
     }
   }
@@ -59,7 +59,7 @@ async function main() {
   }
 
   if (entities.length === 0) {
-    emit({ ok: false, error: 'nenhuma entidade encontrada (config.entities ou domain.models)' })
+    emit({ ok: false, error: 'nenhuma entidade encontrada (config.entities ou domain.entities)' })
     return
   }
 

package/bin/lib/db-migrate-runner.mjs

@@ -28,9 +28,9 @@ function emit(obj) {
 
 function collectEntities(domain, out) {
   if (domain === null || typeof domain !== 'object') return
-  const models = domain.models
-  if (models !== undefined && models !== null && typeof models === 'object') {
-    for (const value of Object.values(models)) if (isEntityConfig(value)) out.push(value)
+  const entities = domain.entities
+  if (entities !== undefined && entities !== null && typeof entities === 'object') {
+    for (const value of Object.values(entities)) if (isEntityConfig(value)) out.push(value)
   }
   if (Array.isArray(domain.subdomains)) for (const sub of domain.subdomains) collectEntities(sub, out)
 }

package/bin/lib/db-scaffold-runner.mjs

@@ -23,9 +23,9 @@ function emit(obj) {
 
 function collectEntities(domain, out) {
   if (domain === null || typeof domain !== 'object') return
-  const models = domain.models
-  if (models !== undefined && models !== null && typeof models === 'object') {
-    for (const value of Object.values(models)) if (isEntityConfig(value)) out.push(value)
+  const entities = domain.entities
+  if (entities !== undefined && entities !== null && typeof entities === 'object') {
+    for (const value of Object.values(entities)) if (isEntityConfig(value)) out.push(value)
   }
   if (Array.isArray(domain.subdomains)) for (const sub of domain.subdomains) collectEntities(sub, out)
 }
@@ -48,7 +48,7 @@ async function main() {
   if (Array.isArray(config.entities)) for (const e of config.entities) if (isEntityConfig(e)) entities.push(e)
   if (Array.isArray(config.domains)) for (const d of config.domains) collectEntities(d, entities)
   if (entities.length === 0) {
-    emit({ ok: false, error: 'nenhuma entidade encontrada (config.entities ou domain.models)' })
+    emit({ ok: false, error: 'nenhuma entidade encontrada (config.entities ou domain.entities)' })
     return
   }
   if (typeof config.database !== 'function') {

package/bin/lib/db.mjs

@@ -249,7 +249,7 @@ Flags:
 
 O opus.config.ts precisa expor, pros comandos db:
   database: () => Kysely          factory LAZY do banco (gen não a chama)
-  entities | domains              entidades (explícitas ou via domain.models)
+  entities | domains              entidades (explícitas ou via domain.entities)
   schema?: string                 script SQL idempotente (default: ./db/schema.sql)
   migrations?: string             pasta dos rascunhos do scaffold (default: ./migrations)
 

package/bin/lib/gen-manifest.mjs

@@ -25,10 +25,7 @@ function shapeDomain(d) {
     dicts: d.dicts,
     repository: d.hasRepository,
     service: d.hasService,
-    // `entities` = a fonte estrutural+negócio (campos + docs). `models` = nomes
-    // (legado, removido no PR de rename). Ambos por ora pra não quebrar a lente.
     entities: d.entities ?? [],
-    models: d.modelNames,
     actions: d.actions.map(shapeAction),
     reactions: d.reactions,
     schedules: d.schedules,

package/bin/lib/gen-runner.mjs

@@ -30,7 +30,7 @@
  *     SerializedDomain:
  *     {
  *       name, dicts, actions, reactions, schedules, subdomains,
- *       hasRepository, hasService, hasModels
+ *       hasRepository, hasService
  *     }
  *
  *     SerializedAction (todos os ActionDef preservam suas strings):
@@ -143,17 +143,12 @@ async function main() {
 // =============================================================================
 
 function serializeDomain(domain, ctx) {
-  // `entities` é o nome preferido; `models` é o legado (alias). Lê os dois.
-  const entitySrc = domain.entities ?? domain.models
-  const entityList = serializeEntities(entitySrc)
+  const entityList = serializeEntities(domain.entities)
   return {
     name: domain.name,
     description: nullable(domain.description),
     hasRepository: domain.repository !== undefined,
     hasService: domain.service !== undefined,
-    // Compat: nomes ainda expostos; `entities` traz a estrutura+doc completa.
-    hasModels: entityList.length > 0,
-    modelNames: entityList.map((e) => e.name),
     entities: entityList,
     dicts: serializeDicts(domain.dicts),
     actions: Array.from(iterateActions(domain.actions), (a) =>

package/bin/lib/init.mjs

@@ -1,6 +1,7 @@
 /** opus setup: aplica o marcador per-app e os artefatos Opus rastreáveis no repo. */
 
 import { promises as fs } from "node:fs";
+import { tmpdir } from "node:os";
 import path from "node:path";
 
 import { materializeOpus, PACKAGE_VERSION } from "./materialize.mjs";
@@ -27,7 +28,12 @@ async function readJson(p) {
 /** Raiz do repo (sobe até achar `.git`); sem repo → null (o chamador decide o fallback). */
 export async function repoRootOf(dir) {
   let cur = path.resolve(dir);
+  const temporaryRoot = path.resolve(tmpdir());
   for (;;) {
+    // O diretório temporário global pode receber marcadores transitórios de ferramentas
+    // e sandboxes. Um projeto dentro dele ainda pode ter sua própria raiz Git, mas não deve
+    // herdar `/tmp/.git` como se todos os fixtures pertencessem ao mesmo repositório.
+    if (cur === temporaryRoot) return null;
     if (await exists(path.join(cur, ".git"))) return cur;
     const up = path.dirname(cur);
     if (up === cur) return null;

package/bin/lib/materialize.mjs

@@ -5,6 +5,7 @@ import { dirname, extname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import { validateSkill } from './validate-skill.mjs'
+import { expandDocIncludes } from './docs-include.mjs'
 
 export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
 export const PACKAGE_NAME = '@softize/opus'
@@ -97,7 +98,8 @@ function expectedFiles(exclude) {
     for (const file of filesUnder(join(PACKAGE_ROOT, sourceRoot))) {
       const source = `${sourceRoot}/${file.relative}`
       const destination = `${destinationRoot}/${file.relative}`
-      const content = readFileSync(file.path, 'utf8')
+      const sourceContent = readFileSync(file.path, 'utf8')
+      const content = file.relative === 'SKILL.md' ? expandDocIncludes(sourceContent) : sourceContent
       expected.set(destination, { source, content, output: addMarker(destination, source, content) })
     }
   }

package/docs/data-layer.md

@@ -90,7 +90,7 @@ infra do `gen`, não a do `check`). Contrato do config **pros comandos `db`**:
 
 ```ts
 export default {
-  domains: [...],                       // entidades coletadas de domain.models
+  domains: [...],                       // entidades coletadas de domain.entities
   entities: [Deal, Company],            // ou explícitas (opcional)
   schema: './src/db/schema.sql',        // o script idempotente (default: ./db/schema.sql)
   database: () => new Kysely({ ... }),  // factory LAZY do banco
@@ -139,7 +139,7 @@ import { Kysely, PostgresDialect, CamelCasePlugin } from 'kysely'
 import { Deal } from './src/domains/deals/deal.entity.ts'
 
 export default {
-  entities: [Deal],          // ou domains: [...] (entidades via domain.models)
+  entities: [Deal],          // ou domains: [...] (entidades via domain.entities)
   naming: 'snake',           // colunas snake no banco
   migrations: './migrations',
   database: () => new Kysely({

package/docs/protocol.md

@@ -2053,14 +2053,14 @@ defineAction({
 
 ### Entidades dentro de um domínio
 
-`DomainConfig.models` recebe as entidades do recorte (substitui o `unknown` placeholder atual). O domínio agrupa; a entidade declara.
+`DomainConfig.entities` recebe as entidades do recorte. O domínio agrupa; a entidade declara.
 
 ```ts
 import { defineDomain } from '@softize/opus'
 
 export const crm = defineDomain({
   name: 'crm',
-  models: { Deal, Company, Contact },
+  entities: { Deal, Company, Contact },
   actions: { /* deal.create, deal.search, ... */ },
 })
 ```

package/package.json

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

package/registry/instructions/opus.md

@@ -15,3 +15,6 @@ artefatos de agentes fica em `base.json`; cada app Opus mantém seu marcador `op
   branch antes de commit/review e usar `upgrade-opus` para ler changelog e aplicar migrações.
 - Consultar as skills Opus materializadas conforme o workflow; não atribuir ao SDK decisões
   universais de domínio ou arquitetura.
+- Usar `write-product-communication` ao criar ou alterar documentação, textos de interface,
+  mensagens de erro, CLI, onboarding ou explicações. Partir da situação do leitor, apresentar
+  contexto antes da regra e evitar slogans, absolutos e linguagem de manifesto.

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

@@ -26,6 +26,8 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
 7. Usar diretamente a escala `rounded-*`; não criar radius por nome de componente quando
    `rounded-sm` a `rounded-xl` já expressam a forma.
 8. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
+9. Usar `write-product-communication` para labels, ajuda, estados vazios, confirmações e erros;
+   revisar o fluxo completo, não apenas cada string isolada.
 
 ## Verificação
 

package/registry/skills/create-opus-action/SKILL.md

@@ -21,6 +21,8 @@ registrados no runtime do projeto.
 1. Rodar `node scripts/scaffold.mjs <resource> <verb> <kind>` a partir desta skill.
 2. Colocar o contrato em módulo importável pelos consumidores e o binding no lado servidor.
 3. Substituir os exemplos do scaffold por schemas, descrições e comportamento do domínio.
+   Usar `write-product-communication` nas descrições, mensagens e textos projetados para UI
+   ou documentação.
 4. Declarar `requires` somente com `authorize` efetivo; `requires` sozinho não protege a action.
 5. Exportar e registrar o binding no domínio/runtime existente.
 6. Acionar `test-opus-action` para cobrir contrato, sucesso, erros e efeitos relevantes.

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

@@ -25,6 +25,8 @@ dependências server-only, bindings registrados, testes e gates verdes.
 5. Usar `create-opus-action`, `test-opus-action` ou `build-opus-ui` quando a mudança entrar
    nesses workflows especializados.
 6. Atualizar manifest, docs geradas e exemplos somente pelos comandos do repo.
+7. Usar `write-product-communication` sempre que a mudança alcançar documentação, UI, CLI,
+   mensagens de erro ou outro texto destinado a uma pessoa.
 
 ## Verificação
 

package/registry/skills/upgrade-opus/SKILL.md

@@ -19,6 +19,8 @@ materializados e projeções geradas consistentes no mesmo diff.
 4. Aplicar migrações no código por domínio, sem compatibilidade temporária silenciosa.
 5. Rodar `opus check`, typecheck, testes, build e geradores declarados pelo projeto.
 6. Conferir `base.json`, lockfile, skills, hooks, instruções e outputs gerados no diff.
+7. Usar `write-product-communication` ao redigir changelog, guia de migração e mensagens
+   adicionadas ou alteradas durante o upgrade.
 
 ## Verificação
 

package/registry/skills/write-product-communication/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: write-product-communication
+description: Escreve e revisa comunicação de produto clara, humana e orientada ao leitor. Usar ao criar ou alterar documentação, mensagens de erro, textos de interface, CLI, onboarding, ajuda, explicações, comentários ou qualquer conteúdo que uma pessoa precise compreender.
+---
+
+# Escrever comunicação de produto
+
+## Resultado
+
+Entregar uma comunicação que parte da situação do leitor, oferece o contexto necessário e
+permite que a pessoa compreenda ou prossiga sem decodificar a linguagem interna da equipe.
+
+## Procedimento
+
+1. Identificar quem lerá o texto, o que essa pessoa tenta fazer e o que precisa compreender ou
+   decidir em seguida.
+2. Ler a comunicação no fluxo completo em que aparecerá, incluindo estados anteriores e
+   posteriores.
+3. Escrever a partir do problema e do efeito percebido; introduzir mecanismos e termos técnicos
+   somente quando acrescentarem precisão.
+4. Distinguir princípios, regras, recomendações, comportamentos, verificações e exceções.
+5. Revisar o texto fora do contexto da implementação e remover pressupostos, slogans,
+   advertências desnecessárias e detalhes internos.
+6. Confirmar que erros explicam o ocorrido, o impacto e uma próxima ação real quando ela existir.
+
+## Referência canônica
+
+<!-- opus-doc: microcopy.md -->

package/registry/skills/write-product-communication/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Comunicação de produto"
+  short_description: "Escreva textos claros, humanos e úteis"
+  default_prompt: "Use $write-product-communication para revisar esta comunicação pelo ponto de vista do leitor."

package/src/core/domain.ts

@@ -2,7 +2,7 @@
  * tbdlib — `defineDomain` factory + flatten helper.
  *
  * Domain agrupa as peças que pertencem a um mesmo recorte funcional
- * (dicts, models, repository, service, actions, reactions, schedules,
+ * (dicts, entities, repository, service, actions, reactions, schedules,
  * subdomains). É puramente declarativo: nenhum efeito colateral acontece
  * em `defineDomain`. O runtime consome o objeto via `flattenDomain` quando
  * recebe um `DomainConfig` em `register(...)`.
@@ -55,12 +55,9 @@ export interface DomainConfig {
   dicts?: Record<string, unknown>
 
   /** Entidades do domínio (`defineEntity`). Map de nome → EntityConfig. É a fonte
-   *  estrutural+negócio que vai pro manifest. `models` é o nome legado (alias). */
+   *  estrutural+negócio que vai pro manifest. */
   entities?: Record<string, unknown>
 
-  /** @deprecated Use `entities`. Mantido por compat — o runtime/gen lê os dois. */
-  models?: Record<string, unknown>
-
   /** Repository class do domínio. */
   repository?: unknown
 
@@ -152,7 +149,7 @@ export function isDomainConfig(value: unknown): value is DomainConfig {
     'schedules' in v ||
     'subdomains' in v ||
     'dicts' in v ||
-    'models' in v ||
+    'entities' in v ||
     'repository' in v ||
     'service' in v
   )

package/src/data/readonly-pool.ts

@@ -5,8 +5,8 @@
  *
  *   1. **Pool com teto** — crie o `Pool` com `max` (e/ou use `maxConcurrent` aqui):
  *      query de LLM não esgota as conexões do app.
- *   2. **Transação READ ONLY** — `BEGIN TRANSACTION READ ONLY`: escrita morre no
- *      servidor, qualquer que seja o SQL.
+ *   2. **Transação READ ONLY** — `BEGIN TRANSACTION READ ONLY`: o servidor rejeita
+ *      qualquer tentativa de escrita, independentemente do SQL recebido.
  *   3. **`SET LOCAL ROLE` por transação** — o alcance é do contexto: com grants
  *      default-fechado, `sales_read` não enxerga `hr_employees.salary` nem por
  *      SELECT criativo. (Criar os roles/grants é migração sua; aqui só se assume.)

package/src/schema/entity.ts

@@ -310,7 +310,7 @@ export function entityTable(config: EntityConfig): string {
 
 /**
  * `true` se `value` parece um `EntityConfig`. Usado pra coletar entidades de
- * `domain.models` (que é `unknown`) sem confundir com action/reaction/model.
+ * `domain.entities` (que é `unknown`) sem confundir com action/reaction/model.
  * Heurística: tem `name` string + `fields` objeto e **não** tem `kind`
  * (descarta `ActionDef`).
  */

package/src/ui/components/patterns/shell-nav.tsx

@@ -2,11 +2,8 @@
  * <ShellNav /> — o menu como primitivo PIVOTÁVEL. Um nav (grupos → itens, com heading e
  * âncora inferior) que serve os DOIS lares do chrome sem flag:
  *
- *   - na sidebar do <AppShell>  → recolhe pra ícone-só (com tooltip) quando a sidebar
- *     recolhe, sozinho. Sabe que está NA sidebar (e se ela recolheu) pelo contexto de
- *     slot do AppShell (`useSidebarSlot`) — o app não passa isso em duas mãos.
- *   - dentro do conteúdo (o que o <SectionShell> faz) → sempre expandido (fora da sidebar,
- *     `useSidebarSlot` é null).
+ *   - dentro de <Sidebar> → recolhe pra ícone-só (com tooltip) junto com a coluna;
+ *   - fora de <Sidebar> → permanece expandido.
  *
  * "Tanto faz onde": o componente se adapta ao lugar, sem "modo" configurado.
  *
@@ -17,7 +14,7 @@
 
 import type { ReactNode } from 'react'
 import { cn } from '../../lib/cn.ts'
-import { useSidebarSlot } from './app-shell.tsx'
+import { useSidebarCollapsed } from './sidebar.tsx'
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../primitives/tooltip.tsx'
 
 export interface ShellNavItem {
@@ -49,7 +46,7 @@ export interface ShellNavProps {
   footer?: ShellNavGroup[]
   /** Rótulo da landmark `<nav>`. */
   navLabel?: string
-  /** Classes da raiz (a coluna). A LARGURA vem do lar (sidebar do AppShell / SectionShell). */
+  /** Classes da raiz (a coluna). A largura vem do pane/sidebar que a contém. */
   className?: string
 }
 
@@ -109,8 +106,7 @@ function renderGroup(group: ShellNavGroup, gi: number, activeId: string | undefi
 }
 
 export function ShellNav({ groups, activeId, onSelect, heading, footer, navLabel = 'Navegação', className }: ShellNavProps): React.ReactElement {
-  // Recolhe SÓ na sidebar recolhida (o contexto de slot é null no conteúdo → sempre expandido).
-  const railed = useSidebarSlot()?.collapsed ?? false
+  const railed = useSidebarCollapsed()
 
   const body = (
     <div data-slot="shell-nav" className={cn('flex h-full min-h-0 flex-col', className)}>

package/src/ui/components/patterns/sidebar.tsx

@@ -5,6 +5,11 @@ import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../pri
 interface SidebarContextValue { collapsed: boolean }
 const SidebarContext = createContext<SidebarContextValue | null>(null)
 
+/** Estado da Sidebar mais próxima. Uso interno por navegações que se adaptam ao colapso. */
+export function useSidebarCollapsed(): boolean {
+  return useContext(SidebarContext)?.collapsed ?? false
+}
+
 export interface SidebarProps {
   collapsed?: boolean
   /** Desliga a borda quando o Split já desenha a divisória. */
@@ -39,27 +44,21 @@ export function PaneFooter({ className, children }: { className?: string; childr
   return <div data-slot="pane-footer" className={cn('shrink-0 border-t border-border p-2', className)}>{children}</div>
 }
 
-/** @deprecated Use PaneHeader. */
-export const SidebarHeader = PaneHeader
-/** @deprecated Use PaneContent. */
-export const SidebarContent = PaneContent
-/** @deprecated Use PaneFooter. */
-export const SidebarFooter = PaneFooter
-
 export interface SidebarItemProps {
   label: string
   icon?: ReactNode
   badge?: ReactNode
   active?: boolean
   disabled?: boolean
+  className?: string
   onClick: () => void
 }
 
 /** Item de navegação que se adapta ao colapso da Sidebar em que está. */
-export function SidebarItem({ label, icon, badge, active = false, disabled = false, onClick }: SidebarItemProps): React.ReactElement {
-  const collapsed = useContext(SidebarContext)?.collapsed ?? false
+export function SidebarItem({ label, icon, badge, active = false, disabled = false, className, onClick }: SidebarItemProps): React.ReactElement {
+  const collapsed = useSidebarCollapsed()
   const button = (
-    <button type="button" disabled={disabled} aria-current={active ? 'page' : undefined} onClick={onClick} className={cn('flex items-center gap-2.5 rounded-md transition-colors', 'disabled:pointer-events-none disabled:opacity-40', collapsed ? 'mx-auto size-9 justify-center p-0' : 'w-full px-2.5 py-1.5 text-left text-sm', active ? 'bg-muted font-medium text-foreground' : 'text-foreground/80 hover:bg-muted/60')}>
+    <button type="button" disabled={disabled} aria-current={active ? 'page' : undefined} onClick={onClick} className={cn('flex items-center gap-2.5 rounded-md transition-colors', 'disabled:pointer-events-none disabled:opacity-40', collapsed ? 'mx-auto size-9 justify-center p-0' : 'w-full px-2.5 py-1.5 text-left text-sm', active ? 'bg-muted font-medium text-foreground' : 'text-foreground/80 hover:bg-muted/60', className)}>
       {icon !== undefined && <span className="flex shrink-0">{icon}</span>}
       {!collapsed && <span className="min-w-0 flex-1 truncate">{label}</span>}
       {!collapsed && badge !== undefined && <span className="shrink-0">{badge}</span>}
@@ -71,17 +70,43 @@ export function SidebarItem({ label, icon, badge, active = false, disabled = fal
 
 export interface SidebarNavGroup {
   label?: string
-  items: Array<Omit<SidebarItemProps, 'active' | 'onClick'> & { id: string }>
+  items?: SidebarNavItem[]
+  subgroups?: SidebarNavSubgroup[]
+}
+
+export type SidebarNavItem = Omit<SidebarItemProps, 'active' | 'onClick'> & { id: string }
+
+export interface SidebarNavSubgroup {
+  label?: string
+  items: SidebarNavItem[]
 }
 
+const titled = (label?: string): boolean => (label ?? '').trim() !== ''
+const subFilled = (subgroup: SidebarNavSubgroup): boolean => subgroup.items.length > 0
+const groupFilled = (group: SidebarNavGroup): boolean =>
+  (group.items?.length ?? 0) > 0 || (group.subgroups?.some(subFilled) ?? false)
+
 /** Navegação controlada para Sidebar. Header/footer continuam slots explícitos do pai. */
 export function SidebarNav({ groups, activeId, onSelect, navLabel = 'Navegação', className }: { groups: SidebarNavGroup[]; activeId?: string; onSelect: (id: string) => void; navLabel?: string; className?: string }): React.ReactElement {
-  const collapsed = useContext(SidebarContext)?.collapsed ?? false
+  const collapsed = useSidebarCollapsed()
+  const renderItem = (item: SidebarNavItem, nested = false): React.ReactElement => (
+    <SidebarItem
+      key={item.id}
+      {...item}
+      className={cn(nested && !collapsed && 'pl-6', item.className)}
+      active={item.id === activeId}
+      onClick={() => onSelect(item.id)}
+    />
+  )
   const body = (
     <nav aria-label={navLabel} data-slot="sidebar-nav" className={cn('space-y-4 p-2', className)}>
-      {groups.map((group, gi) => <div key={gi} className="space-y-0.5">
-        {!collapsed && group.label?.trim() && <div className="px-2.5 pb-1 text-xs font-medium text-muted-foreground/70">{group.label}</div>}
-        {group.items.map(({ id, ...item }) => <SidebarItem key={id} {...item} active={id === activeId} onClick={() => onSelect(id)} />)}
+      {groups.map((group, gi) => !groupFilled(group) ? null : <div key={gi} className="space-y-0.5">
+        {!collapsed && titled(group.label) && <div className="px-2.5 pb-1 text-xs font-medium text-muted-foreground/70">{group.label}</div>}
+        {group.items?.map((item) => renderItem(item))}
+        {group.subgroups?.map((subgroup, si) => !subFilled(subgroup) ? null : <div key={si} className="space-y-0.5">
+          {!collapsed && titled(subgroup.label) && <div className="pb-0.5 pl-4 pr-2.5 pt-1.5 text-[11px] font-medium text-muted-foreground/50">{subgroup.label}</div>}
+          {subgroup.items.map((item) => renderItem(item, titled(subgroup.label)))}
+        </div>)}
       </div>)}
     </nav>
   )

package/src/ui/docs/DocBrowser.tsx

@@ -14,7 +14,8 @@
  */
 import { useEffect } from 'react'
 import { DOC_SECTIONS, type DocSection, type DocEntry } from './registry'
-import { SectionShell, type SectionNavGroup } from '../components/patterns/section-shell.tsx'
+import { Pane, Split } from '../components/patterns/split.tsx'
+import { PaneContent, Sidebar, SidebarNav, type SidebarNavGroup } from '../components/patterns/sidebar.tsx'
 import { navigate, usePathname } from '../router.ts'
 
 function findPage(sections: DocSection[], slug: string): DocEntry | undefined {
@@ -70,21 +71,35 @@ export function DocBrowser({
   // Seção → grupo, e os grupos da seção → subgrupos. O tier do meio NÃO pode ser
   // achatado: `docSectionsFromFolder` o preenche a partir de sub-pasta (ou do
   // frontmatter `group:`), que é o caminho do `opusDocs({ source })`.
-  const navGroups: SectionNavGroup[] = sections.map((section) => ({
+  const navGroups: SidebarNavGroup[] = sections.map((section) => ({
     label: section.label,
     subgroups: section.groups.map((g) => ({
       label: g.label,
-      items: g.pages.map((p) => ({ id: p.slug, label: p.title, badge: p.badge })),
+      items: g.pages.map((p) => ({
+        id: p.slug,
+        label: p.title,
+        badge: p.badge === undefined ? undefined : <span className="rounded border border-border/60 px-1 font-mono text-[10px] leading-tight text-muted-foreground/60">{p.badge}</span>,
+      })),
     })),
   }))
 
   return (
-    <SectionShell
-      groups={navGroups}
-      activeId={page?.slug}
-      onSelect={(slug) => go(`${basePath}/${slug}`)}
-    >
-      <div className="mx-auto max-w-3xl px-8 py-8">{page?.render()}</div>
-    </SectionShell>
+    <Split className="h-full">
+      <Pane inset="none" className="w-56">
+        <Sidebar className="w-full">
+          <PaneContent>
+            <SidebarNav
+              groups={navGroups}
+              activeId={page?.slug}
+              navLabel="Navegação da documentação"
+              onSelect={(slug) => go(`${basePath}/${slug}`)}
+            />
+          </PaneContent>
+        </Sidebar>
+      </Pane>
+      <Pane key={page?.slug} grow inset="none" className="overflow-y-auto">
+        <div className="mx-auto max-w-3xl px-8 py-8">{page?.render()}</div>
+      </Pane>
+    </Split>
   )
 }

package/src/ui/docs/content/actions.md

@@ -4,9 +4,9 @@ title: Actions & contratos
 
 # Actions & contratos
 
-A action é a unidade do Opus. O contrato (entidade + input/output + metadados) mora no package
-compartilhado; a API amarra o handler; a web renderiza a partir do mesmo contrato. Um shape,
-três consumidores.
+Uma action descreve uma operação que cliente e servidor precisam compreender da mesma forma.
+Seu contrato reúne entidade, entrada, saída e metadados no package compartilhado. A API conecta
+o handler e a web usa a mesma definição para executar ou renderizar a operação.
 
 ## Contrato primeiro
 
@@ -51,8 +51,9 @@ export const workspaceCreate = bindAction(workspaceCreateContract, {
 
 ## Ordem canônica dos campos
 
-> O `opus check` reprova fora desta ordem — é a régua, 0 violação antes de entregar. A skill
-> `create-opus-action` gera contrato e binding no formato certo por construção.
+> Esta ordem mantém contratos previsíveis para leitura e geração. O `opus check` informa os
+> campos que precisam ser reposicionados, e a skill `create-opus-action` já cria o contrato e o
+> binding nessa estrutura.
 
 ```text
 name → kind → (label / summary / messages / tags…)
@@ -130,7 +131,7 @@ descartável — vira o contrato que o backend honra.
 import { useLookupAction } from '@softize/opus/client'
 import { ActionForm } from '@softize/opus/ui/react'
 
-// Lista paginada, tipada pelo contrato — zero shape duplicado.
+// O contrato mantém a lista paginada tipada sem exigir uma definição paralela.
 const { rows, fetchNextPage } = useLookupAction(workspaceListContract)
 
 // Form contract-driven: os campos (fields) moram NO contrato.