@softize/opus 11.1.1 → 12.0.1

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

@@ -2,6 +2,7 @@
 name: create-opus-action
 description: Cria uma action Opus no split canônico de defineContract e bindAction, incluindo registro e validação. Use ao adicionar endpoint, comando, consulta ou operação de domínio em projeto baseado no Opus.
 ---
+<!-- softize-skill-route: $test-opus-action -->
 
 # Criar action Opus
 
@@ -21,16 +22,15 @@ 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.
+6. Carregar e seguir `$test-opus-action` para cobrir contrato, sucesso, erros e efeitos relevantes.
 
 ## Verificação
 
 Rodar `opus check <escopo>`, typecheck e testes do domínio. Se o projeto gera manifest,
-OpenAPI ou docs, regenerar e conferir o diff.
+OpenAPI ou docs, regenerar e conferir o diff. Regenerar também o inventário com `opus copy`
+e executar `base copy check` quando o contrato declarar texto humano.
 
 ## Limites
 

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

@@ -2,6 +2,9 @@
 name: implement-opus-change
 description: Implementa uma mudança em projeto baseado no Opus preservando contrato, binding, registro e projeções. Use ao alterar domínio, action, runtime ou integração que utilize @softize/opus.
 ---
+<!-- softize-skill-route: $create-opus-action -->
+<!-- softize-skill-route: $test-opus-action -->
+<!-- softize-skill-route: $build-opus-ui -->
 
 # Implementar mudança Opus
 
@@ -22,16 +25,15 @@ dependências server-only, bindings registrados, testes e gates verdes.
 2. Modelar primeiro o contrato observável: nome, descrição, input, output, erros e metadata.
 3. Manter código compartilhável fora de banco, segredo, filesystem e drivers server-only.
 4. Implementar o binding e registrar o `ActionDef` no domínio/runtime conforme a topologia local.
-5. Usar `create-opus-action`, `test-opus-action` ou `build-opus-ui` quando a mudança entrar
-   nesses workflows especializados.
+5. Carregar e seguir `$create-opus-action`, `$test-opus-action` ou `$build-opus-ui` antes
+   do passo correspondente 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
 
 Rodar `opus check` no escopo correto, testes afetados, typecheck e os geradores que o
-projeto declara. Conferir o diff gerado antes do handoff.
+projeto declara. Se o contrato mudou texto humano, regenerar com `opus copy` e executar
+`opus copy --check` seguido de `base copy check`. Conferir o diff gerado antes do handoff.
 
 ## Limites
 

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

@@ -15,12 +15,16 @@ materializados e projeções geradas consistentes no mesmo diff.
 1. Registrar versão atual e alvo e ler todas as entradas intermediárias do `CHANGELOG.md`,
    priorizando seções Breaking e instruções de migração.
 2. Atualizar a dependência com o package manager do repo.
-3. Executar `opus setup` para materializar exatamente a versão resolvida.
+3. Executar o script do projeto (`pnpm run setup` ou, no monorepo,
+   `pnpm --filter <workspace> run setup`) para materializar Base e Opus na ordem declarada.
+   `pnpm setup` sem `run` continua reservado ao setup da própria máquina.
 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.
+6. Remover configuração obsoleta da registry privada: o setup limpa a diretiva conhecida
+   no `.npmrc` do projeto; diagnosticar também `pnpm config get @softize:registry --global`
+   e, se apontar para `registry.softize.com.br`, executar
+   `pnpm config delete @softize:registry --global` com autorização do dono da máquina.
+7. Conferir `base.json`, lockfile, skills, hooks, instruções e outputs gerados no diff.
 
 ## Verificação
 

package/registry/skills/upgrade-opus/references/upgrade-checklist.md

@@ -1,7 +1,10 @@
 # Checklist de upgrade
 
 - versão alvo presente em `package.json`, lockfile, `base.json` e `opus.json` aplicáveis;
-- `opus setup` e `opus check` verdes;
+- `pnpm run setup` (ou `pnpm --filter <workspace> run setup`) e `opus check` verdes;
+- `.npmrc` do projeto sem `@softize:registry=...registry.softize.com.br` e configuração
+  global antiga removida com autorização explícita;
+- `opus copy --check` e `base copy check` verdes quando o inventário estiver configurado;
 - breakings intermediários tratados;
 - typecheck, testes e build verdes;
 - manifest, OpenAPI e docs regenerados quando configurados;

package/registry/templates/app/package.json

@@ -3,6 +3,7 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "setup": "opus setup && base setup",
     "dev": "vite",
     "dev:design": "vite --mode design --configLoader runner",
     "build": "tsc --noEmit && vite build",
@@ -11,6 +12,8 @@
     "test": "vitest run",
     "format": "prettier --write src",
     "format:check": "prettier --check src",
+    "copy": "opus copy",
+    "copy:check": "opus copy --check && base copy check",
     "manifest": "opus gen",
     "manifest:check": "opus gen && git diff --exit-code .opus/manifest.json"
   },
@@ -27,6 +30,7 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
+    "@softize/base": "^2.0.0",
     "@tailwindcss/vite": "^4.1.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",

package/registry/templates/app/pnpm-workspace.yaml

@@ -5,7 +5,8 @@ allowBuilds:
   '@softize/opus': true
   esbuild: true
 
-# A base é do nosso registry (confiada): fora da quarentena de release do pnpm —
-# senão um bump nas primeiras 24h da versão resolveria versão velha.
+# Opus e Base são publicados juntos no npm público: os dois ficam fora da quarentena
+# para que um rollout recém-publicado não combine protocolo novo com política antiga.
 minimumReleaseAgeExclude:
   - '@softize/opus'
+  - '@softize/base'

package/registry/templates/app/src/domains/tasks/actions/list.ts

@@ -24,7 +24,7 @@ export const taskList = defineContract({
 
 // Fixture em memória — o domínio-exemplo não tem banco; troque pelo seu repositório.
 const TASKS = [
-  { id: '1', title: 'Conhecer a base Opus.', done: true },
+  { id: '1', title: 'Conhecer o Opus.', done: true },
   { id: '2', title: 'Modelar o primeiro domínio real.', done: false },
 ]
 

package/registry/templates/monorepo/pnpm-workspace.yaml

@@ -9,6 +9,8 @@ allowBuilds:
   '@softize/opus': true
   esbuild: true
 
-# A base é do nosso registry (confiada): fora da quarentena de release do pnpm.
+# Opus e Base são publicados juntos no npm público; não deixe a quarentena montar uma
+# combinação de versões que nunca passou pelos gates da release.
 minimumReleaseAgeExclude:
   - '@softize/opus'
+  - '@softize/base'

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

@@ -2,13 +2,21 @@ import { Children, isValidElement, type CSSProperties, type ReactElement, type R
 import { cn } from '../../lib/cn.ts'
 import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '../primitives/resizable.tsx'
 
+export type PaneSize = number | `${number}%` | `${number}rem` | `${number}em` | `${number}vh` | `${number}vw` | `${number}px`
+export type SplitLayout = Record<string, number>
+export interface SplitLayoutChange {
+  isUserInteraction: boolean
+}
+
 export interface PaneProps {
-  /** Fração inicial do split, em %. O pane que cresce recebe o restante. */
-  initialSize?: number
-  /** Fração mínima, em %, quando o split é redimensionável. */
-  minSize?: number
-  /** Fração máxima, em %, quando o split é redimensionável. */
-  maxSize?: number
+  /** Identidade estável usada pelo layout redimensionável e por layouts persistidos. */
+  id?: string
+  /** Tamanho inicial. Números representam porcentagens; strings aceitam %, rem, em, vh, vw e px. */
+  initialSize?: PaneSize
+  /** Tamanho mínimo quando o split é redimensionável. */
+  minSize?: PaneSize
+  /** Tamanho máximo quando o split é redimensionável. */
+  maxSize?: PaneSize
   /** Ocupa o espaço remanescente no layout simples. */
   grow?: boolean
   /** Respiro interno padrão. Use `none` para chrome, navegação ou conteúdo com inset próprio. */
@@ -18,21 +26,27 @@ export interface PaneProps {
 }
 
 /** Um conteúdo encaixável. Sua posição é dada pela ordem dentro de <Split>. */
-export function Pane({ initialSize, grow = false, inset = 'md', className, children }: PaneProps): React.ReactElement {
-  const style: CSSProperties | undefined = initialSize === undefined ? undefined : { flexBasis: `${initialSize}%` }
+export function Pane({ id, initialSize, grow = false, inset = 'md', className, children }: PaneProps): React.ReactElement {
+  const style: CSSProperties | undefined = initialSize === undefined ? undefined : { flexBasis: sizeToCss(initialSize) }
   const insets = { none: '', sm: 'p-2', md: 'p-4', lg: 'p-6' } as const
   return (
-    <div data-slot="pane" data-inset={inset} className={cn('min-h-0 min-w-0 shrink-0', grow && 'flex-1', insets[inset], className)} style={style}>
+    <div id={id === undefined ? undefined : String(id)} data-slot="pane" data-inset={inset} className={cn('min-h-0 min-w-0 shrink-0', grow && 'flex-1', insets[inset], className)} style={style}>
       {children}
     </div>
   )
 }
 
 export interface SplitProps {
+  /** Identidade estável do grupo redimensionável. */
+  id?: string
   direction?: 'horizontal' | 'vertical'
-  /** Quando ligado, cada fronteira ganha um handle e os tamanhos passam a ser percentuais. */
+  /** Quando ligado, cada fronteira ganha um separador acessível e arrastável. */
   resizable?: boolean
   handle?: boolean
+  /** Layout percentual restaurado, indexado pelos ids dos panes. */
+  defaultLayout?: SplitLayout
+  /** Chamado ao concluir uma mudança de layout; pode persistir o resultado em localStorage. */
+  onLayoutChanged?: (layout: SplitLayout, meta: SplitLayoutChange) => void
   className?: string
   children: ReactNode
 }
@@ -43,11 +57,20 @@ function panesOf(children: ReactNode): ReactElement<PaneProps>[] {
   )
 }
 
-// react-resizable-panels v4 interpreta `number` como pixels. O contrato de Split/Pane
-// é percentual (e o layout flex simples abaixo também usa `%`), então a unidade precisa
-// ser explícita na fronteira com o primitive.
-function percent(value: number | undefined): string | undefined {
-  return value === undefined ? undefined : `${value}%`
+// Números continuam percentuais por compatibilidade com Split/Pane. Strings preservam
+// a unidade explícita para layouts que precisam de um limite físico, como `28rem`.
+function sizeToCss(value: PaneSize): string {
+  return typeof value === 'number' ? `${value}%` : value
+}
+
+function resizableSize(value: PaneSize | undefined): string | undefined {
+  return value === undefined ? undefined : sizeToCss(value)
+}
+
+function percentage(value: PaneSize | undefined): number | undefined {
+  if (typeof value === 'number') return value
+  if (value?.endsWith('%')) return Number.parseFloat(value)
+  return undefined
 }
 
 /**
@@ -55,35 +78,54 @@ function percent(value: number | undefined): string | undefined {
  * quando fixa e o primitive Resizable quando `resizable`; quem consome não troca de
  * modelo de layout para ganhar arraste.
  */
-export function Split({ direction = 'horizontal', resizable = false, handle = false, className, children }: SplitProps): React.ReactElement {
+export function Split({
+  id,
+  direction = 'horizontal',
+  resizable = false,
+  handle = false,
+  defaultLayout,
+  onLayoutChanged,
+  className,
+  children,
+}: SplitProps): React.ReactElement {
   const panes = panesOf(children)
   const vertical = direction === 'vertical'
 
   if (!resizable) {
     return (
-      <div data-slot="split" data-direction={direction} className={cn('flex min-h-0 min-w-0 flex-1', vertical && 'flex-col', className)}>
+      <div id={id === undefined ? undefined : String(id)} data-slot="split" data-direction={direction} className={cn('flex min-h-0 min-w-0 flex-1', vertical && 'flex-col', className)}>
         {panes}
       </div>
     )
   }
 
-  const fixed = panes.reduce((sum, pane) => sum + (pane.props.initialSize ?? 0), 0)
+  const fixed = panes.reduce((sum, pane) => sum + (percentage(pane.props.initialSize) ?? 0), 0)
+  const hasAbsoluteSize = panes.some((pane) => typeof pane.props.initialSize === 'string' && !pane.props.initialSize.endsWith('%'))
   const growing = panes.filter((pane) => pane.props.grow)
   const rest = Math.max(0, 100 - fixed)
   const fallback = panes.length === 0 ? 100 : 100 / panes.length
 
   return (
-    <ResizablePanelGroup orientation={direction} data-slot="split" className={cn('min-h-0 min-w-0 flex-1', className)}>
+    <ResizablePanelGroup
+      id={id}
+      orientation={direction}
+      defaultLayout={defaultLayout}
+      onLayoutChanged={onLayoutChanged}
+      data-slot="split"
+      className={cn('min-h-0 min-w-0 flex-1', className)}
+    >
       {panes.flatMap((pane, index) => {
-        const size = pane.props.initialSize ?? (pane.props.grow ? rest / Math.max(1, growing.length) : fallback)
+        const size = pane.props.initialSize
+          ?? (hasAbsoluteSize ? undefined : pane.props.grow ? rest / Math.max(1, growing.length) : fallback)
         const panel = (
           <ResizablePanel
             key={pane.key ?? index}
-            defaultSize={percent(size)}
-            minSize={percent(pane.props.minSize)}
-            maxSize={percent(pane.props.maxSize)}
+            id={pane.props.id}
+            defaultSize={resizableSize(size)}
+            minSize={resizableSize(pane.props.minSize)}
+            maxSize={resizableSize(pane.props.maxSize)}
           >
-            <Pane {...pane.props} className={cn('h-full w-full', pane.props.className)} />
+            <Pane {...pane.props} id={undefined} className={cn('h-full w-full', pane.props.className)} />
           </ResizablePanel>
         )
         return index === 0 ? [panel] : [<ResizableHandle key={`handle-${pane.key ?? index}`} withHandle={handle} />, panel]

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

@@ -32,20 +32,21 @@ opus introspect --json
 ## Bootstrap e templates
 
 > `create` scaffolda um app novo com os pré-requisitos plugados; `setup` é per-app
-> (idempotente, nunca sobrescreve o seu); `add` copia um template do registry pro consumer.
+> (idempotente, nunca sobrescreve o seu); `add` copia um template do catálogo empacotado.
 
 ```bash
-opus create meu-app              # app canônico do zero: protocolo + UI + preview + dia zero
+opus create meu-app              # app canônico do zero: protocolo + UI + preview + automação
 opus create meu-cliente --monorepo  # a RAIZ de um workspace (apps/* + packages/*)
 opus create apps/portal          # dentro de um workspace: só o app (modo detectado)
-opus setup                       # grava opus.json, mantém o bloco do CLAUDE.md e o dia zero
+opus setup                       # grava opus.json e materializa a camada específica do SDK
 opus list                        # lista os templates disponíveis
-opus add action-form             # copia um template do registry pro projeto
+opus add action-form             # copia um template do catálogo pro projeto
 ```
 
 O esqueleto do `create` versiona com o Opus (sai do mesmo pacote que o SDK que ele
-configura) e nasce com os gates verdes: domínio-exemplo canônico, teste, manifest,
-CI de fábrica e o dev server pronto pro preview do Maestro. Dois modos, por detecção:
+configura) e nasce com os gates verdes: domínio-exemplo canônico, teste, manifest e o dev
+server pronto pro preview do Maestro. O método geral, a memória e a revisão vêm da Base
+depois de `pnpm run setup`. Dois modos, por detecção:
 repo standalone (template inteiro) ou **app em monorepo** (dentro de um workspace pnpm:
 só os arquivos do app; o que a raiz precisa ter vira aviso, sem clobber).
 
@@ -55,5 +56,5 @@ só os arquivos do app; o que a raiz precisa ter vira aviso, sem clobber).
 > action no formato canônico sem decorar convenção.
 
 `opus mcp` sobe o server (configurado em `.mcp.json`): o agente consulta a estrutura, roda o
-check e gera o esqueleto de uma action nova pela skill `create-opus-action` — a mesma régua do
+check e gera o esqueleto de uma action nova pela skill `$create-opus-action` — a mesma régua do
 `opus check`, por construção.

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

@@ -2,129 +2,82 @@
 title: Comunicação
 ---
 
-# Comunicação
-
-Toda comunicação do produto deve ajudar alguém a compreender o que está acontecendo e a
-seguir adiante com confiança. Esta orientação vale para documentação, interfaces, mensagens
-de erro, CLI, onboarding, textos explicativos, comentários e respostas produzidas por agentes.
-
-Clareza não significa apenas escrever frases curtas. Um texto claro parte da situação do
-leitor, apresenta o que ele precisa saber e oferece contexto suficiente para que a próxima
-decisão não dependa de adivinhação.
-
-## Antes de escrever
-
-Identifique quem lerá o texto, o que essa pessoa está tentando fazer e qual decisão ou ação
-deve ser possível depois da leitura. Quando essas respostas não estiverem claras, investigue o
-fluxo antes de escolher as palavras.
-
-Organize a explicação nesta ordem sempre que ela ajudar:
-
-1. apresente a situação ou o problema reconhecível pelo leitor;
-2. explique o benefício ou o efeito esperado;
-3. descreva o mecanismo somente no nível necessário;
-4. indique a próxima ação quando houver uma.
-
-Não comece pela arquitetura interna quando a necessidade do leitor oferece uma introdução
-mais natural. Termos técnicos são bem-vindos quando acrescentam precisão, mas devem ser
-apresentados antes de serem usados como parte da explicação.
-
-## Voz
-
-Escreva de maneira calma, próxima e segura. A comunicação pode ser firme sem parecer uma
-ordem interna ou um manifesto.
-
-- Prefira explicações completas a slogans, máximas e frases de efeito.
-- Evite absolutos como “sempre”, “nunca”, “zero” e “é” quando houver contexto, condição ou
-  exceção relevante.
-- Não use caixa-alta, negrito ou pontuação para fabricar autoridade.
-- Evite sequências telegráficas, equações e símbolos usados como conectores em prosa.
-- Não presuma que o leitor já concorda com a arquitetura ou conhece o vocabulário da equipe.
-- Explique decisões pelo valor que oferecem às pessoas, não apenas pela disciplina que impõem.
-- Mantenha o mesmo termo para o mesmo conceito em todas as superfícies.
-
-Em vez de “O domínio é a aplicação. Front e back são cascas”, explique a relação:
-
-> O Opus mantém as regras e os contratos do domínio em uma camada compartilhada. Assim,
-> cliente e servidor trabalham com as mesmas definições, sem duplicar schemas, validações ou
-> tipos de transporte.
-
-## Documentação
-
-Uma documentação deve formar o modelo mental do leitor antes de cobrar decisões baseadas
-nele. Apresente primeiro o problema, depois a ideia, um exemplo concreto e os próximos passos.
-Detalhes operacionais e situações excepcionais devem ficar próximos da etapa em que se tornam
-úteis, sem interromper a introdução principal.
-
-Ao registrar uma norma, deixe claro o peso da afirmação:
-
-- **Princípio:** explica a intenção que orienta as decisões.
-- **Regra:** descreve um requisito obrigatório e seu escopo.
-- **Recomendação:** apresenta o caminho preferido quando outras opções continuam válidas.
-- **Comportamento:** informa o que o produto faz automaticamente.
-- **Verificação:** mostra como confirmar que a regra foi atendida.
-- **Exceção:** delimita quando a orientação não se aplica.
-
-Uma regra normativa deve informar a condição em que se aplica, a razão que a sustenta e como
-ela é verificada. Por exemplo:
-
-> Cada action deve ser declarada em um arquivo próprio. Essa separação permite que o registro e
-> os geradores identifiquem cada action de forma determinística. O `opus check` informa quais
-> arquivos precisam ser separados quando encontra mais de uma declaração.
-
-Evite substituir essa explicação por “Uma por arquivo. O gate reprova”. A versão curta omite o
-motivo, não delimita o escopo e transforma uma ajuda em uma advertência.
-
-## Mensagens de erro
-
-Uma mensagem de erro deve responder, nessa ordem, ao que aconteceu, como isso afeta a tarefa e
-o que a pessoa pode fazer. Não culpe o usuário e não exponha endpoint, stack trace, status HTTP
-ou detalhes do runtime na interface; esses dados pertencem ao log ou à área de diagnóstico.
-
-| Situação | Prefira | Evite |
-|---|---|---|
-| Serviço indisponível | O Multica não respondeu. Tente novamente em alguns instantes. | ERRO: request failed (500) |
-| Recurso ausente | Este workspace não existe mais. Volte à lista para escolher outro. | Workspace inválido. |
-| Permissão | Você não tem acesso a este workspace. Peça acesso a um administrador. | Acesso negado. |
-| Validação | Informe um endereço de e-mail válido. | Campo inválido. |
-
-Quando não houver uma ação possível, diga isso com honestidade e preserve o trabalho já feito.
-Não ofereça “tente novamente” como resposta automática para falhas que uma nova tentativa não
-pode resolver.
-
-## Textos de interface
-
-Código e valores internos permanecem em inglês. O que uma pessoa lê na interface usa pt-BR,
-salvo quando o produto declarar outro idioma.
-
-- Frases começam com maiúscula e terminam com ponto.
-- Labels, títulos, itens de menu e botões usam sentence case e não levam ponto.
-- Placeholders de seleção usam `Selecione <artigo> <coisa>…`.
-- Placeholders ajudam a responder, mas não substituem o label do campo.
-- Botões descrevem a ação que executarão, como `Publicar` ou `Salvar alterações`.
-- Textos de ajuda explicam o efeito percebido, não a implementação interna.
-- Abreviações são usadas somente quando o espaço ou o vocabulário do domínio as justificam.
-
-| Tipo | Prefira | Evite |
-|---|---|---|
-| Frase | A configuração não carregou. | Config indisponível. |
-| Label | Nova sessão | Nova sessão. |
-| Botão | Publicar | PUBLICAR |
-| Placeholder | Selecione um cliente… | Selecionar |
-| Ajuda | Os agentes deste workspace passam a usar esta skill. | O push sobrescreve o runtime. |
-
-## Revisão
-
-Antes de entregar, releia o texto fora do contexto da implementação e confirme:
-
-- o leitor consegue reconhecer a situação sem conhecer o código;
-- conceitos novos são explicados antes de orientar decisões;
-- regras obrigatórias estão separadas de recomendações;
-- a razão da orientação aparece quando ajuda a compreendê-la;
-- mensagens de erro preservam a calma e oferecem uma saída real;
-- a frase soa como uma conversa profissional, não como log, slogan ou ordem interna;
-- detalhes técnicos permanecem disponíveis no lugar adequado sem dominar a comunicação.
-
-Leia o fluxo completo, não apenas strings isoladas. Um conjunto de frases corretas ainda pode
-produzir uma experiência confusa quando repete informações, muda de vocabulário ou apresenta
-ações fora da ordem em que a pessoa precisa delas.
+# Comunicação do Opus
+
+Esta página registra somente o vocabulário, as superfícies e os mapeamentos próprios do
+Opus. Princípios gerais de comunicação humana — contexto, impacto, próxima ação, gramática,
+pontuação e consistência — pertencem à skill `write-product-communication` da
+`@softize/base`. As regras mecanicamente verificáveis de copy ficam na política versionada,
+em `node_modules/@softize/base/docs/copy-policy.md`, e no catálogo executável
+`node_modules/@softize/base/policies/copy.json`.
+
+A separação é intencional: uma mudança editorial universal acontece na Base; esta página
+muda apenas quando o produto ou os componentes Opus mudam.
+
+## Língua e termos no Opus
+
+| Camada | Convenção local |
+|---|---|
+| Identificadores de código, arquivos, diretórios e domínios | Inglês |
+| Nomes de action e rota | Inglês, no formato `resource.verb` |
+| Colunas e tabelas de banco | Inglês, em `snake_case` |
+| Enums, status e chaves de dicionário | Inglês, inclusive em exemplos e fixtures (`active`, não `ativo`) |
+| Texto de UI visível | pt-BR; o contrato fornece o label humano para valores técnicos |
+| Comentários e documentação deste repositório | pt-BR |
+
+`Opus` e `Softize` são nomes próprios em prosa (`o Opus`, `a Softize`). Tokens técnicos
+preservam a grafia de código: `opus check`, `@softize/opus`, `opus.json` e
+`softize.com.br`.
+
+Use sempre o termo de produto, não o nome interno da implementação: `sessão`, `ambiente`,
+`cliente` e `agente`. Se a interface diz “cliente”, outra superfície não deve dizer
+“client” para a mesma entidade.
+
+## Papel semântico
+
+O componente ou o contrato Opus classifica cada texto antes de a Base aplicar a política.
+Essa classificação decide, por exemplo, se o conteúdo é um fragmento estrutural ou uma
+frase. Não copie as regras da Base para cá.
+
+| Superfície Opus | Papel enviado à Base |
+|---|---|
+| `label`, botão de confirmação e filhos de `Button` | `button` |
+| `title`, `CardTitle`, `DialogTitle` | `title` |
+| `description`, `hint`, `help` | `description` ou `helper-text` |
+| `messages.success` e `messages.error` | `success` e `error` |
+| `confirm.message`, `DialogDescription` | `dialog-body` |
+| label de campo, filtro ou opção | `label` ou `menu-item` |
+| placeholder de campo ou busca | `placeholder` |
+| `Select.emptyText` e grupos de opção | `empty-state` e `heading` |
+| confirmação local do `ActionTrigger` | `title`, `dialog-body` e `button` |
+
+Copy visual e nome acessível são superfícies cumulativas. Um `aria-label` estático nomeia
+um controle icon-only, mas não torna aceitável nem invisível ao gate um texto visual opaco.
+Em `Select`, mantenha o texto auditável no `label` string; `content`/`triggerLabel` com JSX
+estático e inequívoco também entram no inventário, inclusive com transformações nos
+descendentes. Composição ambígua ou dinâmica faz a geração falhar, pois pode introduzir texto
+visual que o protocolo não representa com segurança.
+`ActionTrigger.itemLabel` é conteúdo de domínio em runtime (o nome do registro alvo), não
+é copy editorial estável; `label` e `confirm.*` são as superfícies editoriais cobertas.
+
+O mapeamento completo, o limite de cobertura e os comandos do gate estão em
+`docs/code-style.md` do pacote.
+
+## Convenções dos componentes
+
+- Placeholders de seleção, simples, buscável ou múltipla, usam
+  `Selecione <artigo> <coisa>…`, sempre com o caractere `…`. Declare o placeholder no
+  contrato; o default do componente é apenas uma rede de segurança.
+- Exemplos são neutros e duráveis: use Empresa X / Empresa Y e
+  `contato@empresa-x.com.br`, nunca um cliente real ou que pareça real.
+- Em campos Opus, quando o termo canônico precisa de explicação persistente, mantenha o
+  termo curto em `label` e descreva o efeito em `help`. Por exemplo: `Staff` com
+  `Tem acesso ao back-office e a todos os workspaces.`
+- Abreviações só entram quando o espaço do componente realmente exigir. Prefira `mínimo`,
+  `máximo` e `configuração`; `Ex.:` é tolerado em placeholder.
+
+## Vocabulário de estado
+
+Nas superfícies de UI do Opus, use “indisponível” para um recurso que não pode ser usado,
+em vez dos rótulos alarmistas “ERRO” ou “FALHOU”. Endpoint, status HTTP e stack pertencem
+ao console, ao log ou à documentação técnica, não ao texto dos componentes.