@softize/opus 11.0.0 → 11.1.1

package/CHANGELOG.md

@@ -6,6 +6,30 @@ 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.1 — 2026-08-21
+
+A referência canônica passa a usar `communication.md` como nome do arquivo e `communication`
+como slug. Assim, o nome interno e a URL acompanham o escopo ampliado da página, que deixou de
+tratar apenas de microcopy. A URL anterior, `/ui/microcopy`, redireciona para
+`/ui/communication`, preservando links existentes sem manter o nome antigo na navegação ou na
+fonte materializada.
+
+## 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

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "11.0.0",
+  "version": "11.1.1",
   "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: communication.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/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/ui/docs/DocBrowser.tsx

@@ -1,6 +1,6 @@
 /**
  * DocBrowser — a VERDADE VISUAL da casa, como doc completa. Seção multi-página: conceitos
- * (Introdução, Tokens & Tema, Microcopy, Customização) + uma página por componente do
+ * (Introdução, Tokens & Tema, Comunicação, Customização) + uma página por componente do
  * opus/ui, agrupados por seção. O que você vê aqui é o que os apps entregam (o site
  * do shadcn é catálogo do que existe; a expectativa visual nasce aqui).
  *
@@ -35,6 +35,8 @@ export interface DocBrowserProps {
   path?: string
   /** Seções a exibir (seção → grupo → página). Default = catálogo inteiro. */
   sections?: DocSection[]
+  /** Slugs antigos que devem abrir e substituir a URL pela página canônica. */
+  redirects?: Readonly<Record<string, string>>
   /** Monta o `document.title` a partir do título da página atual (ex.: `(t) => `${t} · Opus``).
    *  Ausente = não mexe no title. */
   documentTitle?: (pageTitle: string) => string
@@ -44,6 +46,7 @@ export function DocBrowser({
   basePath = '/docs',
   path: controlledPath,
   sections = DOC_SECTIONS,
+  redirects = {},
   documentTitle,
 }: DocBrowserProps): React.ReactElement {
   // Standalone: o path vem do router da casa (`usePathname` — pathname É o estado).
@@ -56,13 +59,18 @@ export function DocBrowser({
   // Slug = TODOS os segmentos após o basePath, unidos (rota aninhada: `/docs/guias/deploy`
   // → `guias/deploy`). Slug flat de 1 segmento continua igual (`join` de 1 elemento = ele).
   const rel = path.startsWith(basePath) ? path.slice(basePath.length) : ''
-  const slug = rel.split('/').filter(Boolean).join('/') || defaultSlug
+  const requestedSlug = rel.split('/').filter(Boolean).join('/') || defaultSlug
+  const slug = redirects[requestedSlug] ?? requestedSlug
   const page = findPage(sections, slug) ?? findPage(sections, defaultSlug)
 
   // `navigate` emite `popstate`, então o host é notificado nos dois modos — inclusive o
   // que ainda escuta o evento na unha, que era como este componente avisava antes.
   const go = (to: string): void => navigate(to)
 
+  useEffect(() => {
+    if (requestedSlug !== slug) navigate(`${basePath}/${slug}`, { replace: true })
+  }, [basePath, requestedSlug, slug])
+
   // O title da aba acompanha a página atual (quando o host fornece o formato).
   useEffect(() => {
     if (page && documentTitle) document.title = documentTitle(page.title)

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.

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

@@ -21,8 +21,9 @@ interface AuthAdapter {
 }
 ```
 
-`req` é o request cru do `ServerAdapter`. O `user` sai dos claims/sessão; o `can` é a régua
-de autorização — o Opus só chama, não decide.
+`req` é o request cru do `ServerAdapter`. O `user` vem dos claims ou da sessão, e o driver
+fornece a função `can` que decide cada autorização. O Opus chama essa função sem definir a
+política usada por ela.
 
 ## Drivers
 

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

@@ -9,7 +9,8 @@ valida as convenções e expõe o estado vivo pros agentes via MCP.
 
 ## Gates
 
-> A régua de entrega: 0 violação antes de qualquer handoff. Rode no CI e antes de commitar.
+> Use o check no CI e antes de entregar uma mudança. Ele informa quais contratos precisam de
+> ajuste e encerra com sucesso quando não encontra violações.
 
 ```bash
 opus check src    # valida as convenções das actions (exit ≠ 0 se violar)

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

@@ -0,0 +1,130 @@
+---
+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.

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

@@ -88,7 +88,7 @@ const { rows } = await bi.query(sqlDoLlm, { role: roleFor(ctx) })
 
 1. **Pool com teto** (`max` do pool e/ou `maxConcurrent`) — query de LLM não esgota as
    conexões do app;
-2. **`BEGIN TRANSACTION READ ONLY`** — escrita morre no servidor;
+2. **`BEGIN TRANSACTION READ ONLY`** — o servidor rejeita tentativas de escrita;
 3. **`SET LOCAL ROLE` por transação** — o alcance é do CONTEXTO (crie os roles com grants
    default-fechado nas suas migrações: sem isso, `sales_read` leria `hr_employees`);
 4. **Protocolo estendido** — o SQL roda sempre com array de valores; multi-sentença

package/src/ui/docs/content/getting-started.md

@@ -4,42 +4,34 @@ title: Getting started
 
 # Getting started
 
-O Opus é um SDK/protocolo spec-driven: o domínio **É** a aplicação (contratos +
-actions); front e back são cascas. Um projeto Opus-based pina o Opus, herda o runtime e segue os gates.
+O Opus ajuda cliente e servidor a preservar as mesmas regras à medida que uma aplicação
+evolui. Entidades e contratos de action ficam em uma camada compartilhada; o runtime, a UI e
+as ferramentas usam essas definições sem exigir schemas e tipos paralelos.
 
 ## O modelo
 
-> Antes de qualquer arquivo: por que o Opus existe e o que ele assume.
+> Comece pelo problema que o modelo compartilhado resolve antes de conhecer seus arquivos.
 
-A aplicação é o **domínio** — entidades, dicts e contratos de action. A API e a web são cascas
-que consomem esse domínio: zero shape duplicado. O Opus entrega o núcleo (runtime, adapters, UI,
-CLI) e os gates que mantêm o padrão. O que cada projeto adiciona é o seu domínio; o resto vem pinado.
+As regras de uma aplicação costumam aparecer em vários lugares: validação, transporte, API,
+formulários e documentação. No Opus, entidades, dicts e contratos de action descrevem essas
+regras uma vez. A API e a web consomem a mesma definição, enquanto runtime, adapters, UI, CLI
+e verificações ajudam a mantê-la consistente. Cada projeto acrescenta seu domínio sobre essa
+base versionada.
 
 ## Começar do zero
 
 > Projeto novo não se monta à mão: o esqueleto canônico sai do `opus create`, com os
 > pré-requisitos do protocolo, da UI e do preview já plugados — e os gates verdes.
 
-O Opus mora no registry da Softize (não no npm público) — uma vez por máquina, ensine
-o escopo ao pnpm; dentro do projeto criado o `.npmrc` já cuida disso:
-
 ```bash
-pnpm config set @softize:registry https://registry.softize.com.br/ --global  # 1x por máquina
-
 pnpm dlx @softize/opus create meu-app
 cd meu-app && git init && pnpm install && pnpm test
 ```
 
-Máquina nova: se o pnpm reclamar que o diretório global de binários não está no PATH
-(o `dlx` exige), rode `pnpm setup` e reabra o terminal — também é 1x por máquina. Se o
-setup acusar seção pnpm antiga no shell rc (`ERR_PNPM_BAD_SHELL_SECTION`), é resquício
-de versão anterior: `pnpm setup --force` substitui só o bloco dele.
-
-Release recém-saída (menos de 24h): a quarentena do pnpm resolve o `dlx` pra versão
-ANTIGA em silêncio ("Comando desconhecido" = sintoma clássico). Fure com a versão
-explícita — `pnpm dlx @softize/opus@<versão> create meu-app` — ou com a flag
-`pnpm --config.minimum-release-age=0 dlx …`. Dentro de projeto o pnpm se resolve
-sozinho (auto-exclui o Opus da quarentena no install).
+O comando cria a estrutura inicial e instala a versão estável disponível. Para experimentar
+uma versão específica, acrescente-a ao pacote: `pnpm dlx @softize/opus@<versão> create meu-app`.
+Se o pnpm informar que o diretório global de binários não está no `PATH`, execute `pnpm setup`
+e abra uma nova sessão do terminal antes de tentar novamente.
 
 Nasce com: `opus.config.ts` + domínio-exemplo canônico (0 violações, spec documentada),
 vite + react + tema do Opus (Tailwind v4 CSS-first), dev server na porta que o Maestro
@@ -59,8 +51,8 @@ pnpm dlx @softize/opus create apps/portal              # o app (modo detectado)
 
 ## Carregar o Opus num projeto existente
 
-> O pin vive no `opus.json`; o setup grava o esqueleto local. Ausência de `opus.json` = projeto
-> não inicializado — não improvise, rode o setup.
+> O `opus.json` registra a versão usada pelo projeto. Se o arquivo ainda não existe, o setup
+> cria a estrutura necessária antes das demais etapas.
 
 A versão do Opus fica pinada em `opus.json`. O `opus setup` é per-app: grava o `opus.json`,
 mantém o bloco gerenciado do `CLAUDE.md` (fora dele o arquivo é seu) e semeia o dia zero

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

@@ -6,7 +6,7 @@ title: Atualizar o Opus
 
 Projeto em produção fica meses sem tocar no Opus — e um dia precisa pular várias
 versões de uma vez. O ritual é o mesmo para humano e IA, e não depende de memória:
-cada peça do caminho está escrita ou é um gate que quebra alto.
+cada etapa está documentada ou é verificada por um gate que informa o que precisa ser corrigido.
 
 ## 1. Saber que está atrás
 

package/src/ui/docs/registry.tsx

@@ -39,7 +39,7 @@ import runtimeMd from './content/runtime.md?raw'
 import uiMd from './content/ui.md?raw'
 import cliMd from './content/cli.md?raw'
 import tokensMd from './content/tokens.md?raw'
-import microcopyMd from './content/microcopy.md?raw'
+import communicationMd from './content/communication.md?raw'
 import customizationMd from './content/customization.md?raw'
 
 // — Componentes —
@@ -267,7 +267,7 @@ export const UI_SECTIONS: DocSection[] = [
       {
         pages: [
           { slug: 'tokens', title: 'Tokens & Tema', render: doc(tokensMd) },
-          { slug: 'microcopy', title: 'Microcopy', render: doc(microcopyMd) },
+          { slug: 'communication', title: 'Comunicação', render: doc(communicationMd) },
           { slug: 'customization', title: 'Customização', render: doc(customizationMd) },
         ],
       },

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

@@ -1,83 +0,0 @@
----
-title: Microcopy
----
-
-# Microcopy
-
-Código em inglês; o que humano lê (UI, comentário, doc) em pt-BR. Frases começam com
-maiúscula e terminam com ponto; labels curtos em sentence case, sem ponto. **Esta página
-é a fonte** — `build-opus-ui` aplica esta convenção (regra duplicada em vez de apontada é
-defeito).
-
-## Língua por camada
-
-> Regra dura — não tem caso a caso.
-
-| Camada | Língua |
-|---|---|
-| Identificadores de código (vars, funções, tipos, arquivos, dirs, domínios) | Inglês |
-| Nomes de action / rota | Inglês (`resource.verb`) |
-| Colunas e tabelas de banco | Inglês (snake_case) |
-| Valores de código (enums, status, chaves de dict) | Inglês — mesmo em exemplos e fixtures (`active`, não `ativo`); a UI mostra o label pt |
-| Texto de UI visível (labels, headings, botões, placeholders, mensagens) | pt-BR |
-| Comentários e docs (`.md`) | pt-BR |
-
-## Frase vs label
-
-> Frase (mensagem, descrição, tooltip, help): maiúscula no início, ponto no fim. Label
-> (botão, heading, item de menu, chip): sentence case, sem ponto.
-
-| Tipo | Assim | Assim não |
-|---|---|---|
-| Frase | Opus não inicializado. | ~~opus nao inicializado~~ |
-| Frase | O Multica não respondeu — tente de novo. | ~~ERRO: request failed (500)~~ |
-| Label | Publicar | ~~PUBLICAR~~ |
-| Label | Nova sessão | ~~Nova sessão.~~ |
-| Placeholder | Selecione um cliente… | ~~Selecionar~~ · ~~digite o nome…~~ |
-
-## As regras que mais pegam
-
-> Erros recorrentes de revisão — atenção redobrada nestes.
-
-- **Maiúscula é ortografia, não estilo.** Toda frase começa com maiúscula — em UI,
-  hint/help **e comentário de código** — e nome próprio idem (Engineer, Multica, GitHub).
-  Vale com interpolação: mensagem que começaria com valor ganha um artigo na frente
-  (`O workspace '${slug}' não existe…`).
-- **Frase fluida, não telegrama.** Símbolo não é conector: nada de `—`/`+`/`≈` amarrando
-  ideias em label ou help. `Staff — acesso ao back-office + todos os workspaces` vira
-  label `Staff` + help `Tem acesso ao back-office e a todos os workspaces.`.
-- **"Opus" e "Softize" são nomes próprios.** Em prosa, maiúscula (`o Opus`, `a Softize`);
-  os tokens técnicos ficam minúsculos: `opus check`, `@softize/opus`, `opus.json`,
-  `softize.com.br`. É o nome → maiúscula; é código → minúscula.
-- **Abreviação é último caso.** Por extenso: `mínimo`, `máximo`, `configuração`.
-  `Config indisponível.` é duplamente errado (seco E abreviado): `A configuração não
-  carregou.`. `Ex.:` em placeholder é tolerado (com `E` maiúsculo).
-- **Placeholder de seleção segue UM padrão** (select simples, buscável, múltiplo):
-  `Selecione <artigo> <coisa>…` — com `…` (o caractere único), nunca o genérico
-  `Selecionar`. Declare no contrato (`fields.<campo>.placeholder`) — o default do
-  componente é rede de segurança, não estilo; dois pickers na mesma tela com padrões
-  diferentes é defeito.
-- **Nada de maiúsculo deliberado.** Sem ALL-CAPS — nem a classe `uppercase` — em labels,
-  headers ou badges.
-- **Exemplos são neutros e duráveis.** Nada de cliente real ou com cara de real: use
-  Empresa X / Empresa Y (`contato@empresa-x.com.br`). Exemplo "de verdade" envelhece,
-  vaza contexto e vira dívida.
-
-## Tom
-
-> Fale com o usuário, não com o log.
-
-- **Calmo e informativo, não alarmista.** "Indisponível" em vez de "ERRO"/"FALHOU".
-  Não culpe o usuário.
-- **Orientado à ação.** Quando dá, diga o próximo passo: `Inicie o ambiente`,
-  `Crie a primeira acima`.
-- **Conciso, mas natural — não telegráfico.** Prefira a forma completa do verbo a um
-  corte abrupto. O meio-termo é a régua: nem seco demais (`rode no projeto`) nem manual
-  técnico (jargão de arquitetura num help).
-- **Explique pelo efeito, não pelo mecanismo.** Se precisou citar sistema interno pra
-  explicar (`o push sobrescreve o runtime`), reescreva pelo que acontece pro usuário
-  (`os agentes deste workspace passam a usar esta skill`). Mecanismo é doc/comentário,
-  não tooltip.
-- **Nada de endpoint, status ou stack na tela** — detalhe técnico vai pro console/log.
-- **Termos do produto** (sessão, ambiente, cliente, agente), não do código. E o mesmo
-  termo sempre: se a UI fala "cliente", nenhum label diz "client".