@softize/opus 28.0.0 → 29.0.0

package/bin/lib/materialize.mjs

@@ -27,6 +27,7 @@ const REGISTRY = join(PACKAGE_ROOT, 'registry')
 const BLOCK_SOURCE = 'registry/instructions/opus.md'
 const BLOCK_END = '<!-- softize-managed:end @softize/opus -->'
 const MANAGED_ROOTS = ['.agents/skills', '.claude/skills', '.claude/hooks', '.github/workflows', '.githooks/pre-push.d']
+const CLAUDE_IMPORT = '@AGENTS.md'
 
 const normalizedLineEndings = (content) => content.replace(/\r\n?/gu, '\n')
 const hash = (content) => createHash('sha256').update(normalizedLineEndings(content)).digest('hex')
@@ -533,6 +534,103 @@ function reconcileInstructions(root, file, mode, errors, changes) {
   }
 }
 
+// Blocos gerenciados de qualquer pacote. Um marcador de início ilegível não identifica dono e
+// conta como texto do projeto. Mesmo critério da Base (@softize/base, ADR 0006).
+function managedBlocks(content) {
+  const blocks = []
+  let cursor = 0
+  for (const match of content.matchAll(/<!-- softize-managed:start (\{[^\n]+\}) -->/g)) {
+    let meta
+    try {
+      meta = JSON.parse(match[1])
+    } catch {
+      continue
+    }
+    if (typeof meta?.package !== 'string') continue
+    const openEnd = match.index + match[0].length
+    const endMarker = `<!-- softize-managed:end ${meta.package} -->`
+    const endAt = content.indexOf(endMarker, openEnd)
+    if (match.index < cursor || endAt === -1 || content.slice(openEnd, endAt).includes('softize-managed:start')) return null
+    const end = endAt + endMarker.length
+    blocks.push({ start: match.index, end, package: meta.package, text: content.slice(match.index, end) })
+    cursor = end
+  }
+  return blocks
+}
+
+// Texto do projeto fora dos blocos gerenciados e da linha de import, normalizado para comparar o
+// CLAUDE.md legado com o AGENTS.md sem depender de fim de linha ou de linhas em branco.
+function freeInstructions(content, blocks) {
+  let rest = ''
+  let cursor = 0
+  for (const block of blocks) {
+    rest += content.slice(cursor, block.start)
+    cursor = block.end
+  }
+  rest += content.slice(cursor)
+  return normalizedLineEndings(rest)
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter((line) => line !== CLAUDE_IMPORT)
+    .join('\n')
+    .replace(/\n{3,}/gu, '\n\n')
+    .trim()
+}
+
+// O CLAUDE.md só importa o AGENTS.md, que concentra as instruções para qualquer agente. O Opus
+// remove dele apenas o próprio bloco; blocos de outros pacotes continuam depois do import até que
+// o pacote dono os remova, para que versões antigas e novas convivam sem reescrever o arquivo uma
+// da outra. Texto do projeto que só existe no CLAUDE.md é preservado e reprovado.
+function reconcileClaudeImport(root, mode, errors, changes) {
+  const destination = 'CLAUDE.md'
+  const pending =
+    `${destination}: deve conter a linha ${CLAUDE_IMPORT}, que importa o AGENTS.md, seguida apenas dos ` +
+    'blocos de outros pacotes, quando houver; rode opus setup.'
+  const currentFile = readMaterializedFile(root, destination, errors)
+  if (currentFile === null) return
+  const current = currentFile.exists ? currentFile.content : ''
+  const own = findBlock(current)
+  const blocks = managedBlocks(current)
+  if (own?.malformed || blocks === null) {
+    errors.push(`${destination}: bloco gerenciado malformado.`)
+    return
+  }
+  if (own !== null && (own.owner?.package !== PACKAGE_NAME || hash(own.body) !== own.owner.sha256)) {
+    errors.push(`${destination}: bloco Opus foi editado ou perdeu sua identificação de origem; preservado.`)
+    return
+  }
+
+  const free = freeInstructions(current, blocks)
+  if (free !== '') {
+    const agentsFile = readMaterializedFile(root, 'AGENTS.md', errors)
+    if (agentsFile === null) return
+    const agents = agentsFile.exists ? agentsFile.content : ''
+    if (free !== freeInstructions(agents, managedBlocks(agents) ?? [])) {
+      errors.push(
+        `${destination}: tem instruções que não estão no AGENTS.md; preservado. O CLAUDE.md passa a conter só ` +
+          `${CLAUDE_IMPORT}, então mova essas instruções para o AGENTS.md e rode opus setup.`,
+      )
+      return
+    }
+  }
+
+  const foreign = blocks.filter((block) => block.package !== PACKAGE_NAME).map((block) => normalizedLineEndings(block.text))
+  const expected = `${[CLAUDE_IMPORT, ...foreign].join('\n\n')}\n`
+  if (currentFile.exists && managedTextEquivalent(current, expected)) return
+  if (mode === 'check') errors.push(pending)
+  else if (
+    replaceMaterializedFile(
+      root,
+      destination,
+      currentFile.exists ? withProjectLineEndings(expected, current) : expected,
+      currentFile,
+      errors,
+    )
+  ) {
+    changes.push(`${currentFile.exists ? 'atualizado' : 'criado'} ${destination} como import do AGENTS.md`)
+  }
+}
+
 function isOpusHook(hook) { return typeof hook?.command === 'string' && hook.command.includes('.claude/hooks/opus-check-on-stop.mjs') }
 
 function isPlainObject(value) {
@@ -792,7 +890,7 @@ export function materializeOpus(root, mode = 'setup', options = {}) {
   removeObsolete(target, expected, mode, errors, changes)
   detectLegacyArtifacts(target, errors)
   reconcileInstructions(target, 'AGENTS.md', mode, errors, changes)
-  reconcileInstructions(target, 'CLAUDE.md', mode, errors, changes)
+  reconcileClaudeImport(target, mode, errors, changes)
   reconcileSettings(target, mode, errors, changes)
   configureGit(target, mode, errors, changes)
   return { ok: errors.length === 0, errors, changes, expected: [...expected.keys()] }

package/docs/adr/0028-schedules-run-actions-as-the-system-by-action-opt-in.md

@@ -45,7 +45,7 @@ HTTP sem usuário; o acesso do sistema é opt-in por action e negado por padrão
    `{ kind: 'schedule', scheduleName }` — ou `background` com essa provenance original. O helper
    `isSystemActor(ctx)`, exportado pelo core, responde se o ator é o sistema, para que um
    `authorize` possa aceitá-lo de forma explícita: `(ctx) => isSystemActor(ctx) ||
-   ctx.can('caixa:fechar')`. O helper não lê a provenance, que qualquer código servidor pode
+   ctx.can('ledger:close')`. O helper não lê a provenance, que qualquer código servidor pode
    preencher: ele consulta um registro interno dos contextos que o próprio runtime criou para o
    sistema. `requires` continua declarativo: o sistema não detém permissões, e o manifest mostra
    `automatable` ao lado de `permission`.

package/docs/adr/0037-design-data-lives-outside-the-contract.md

@@ -54,7 +54,7 @@ Forças em tensão:
    - uma action ligada a um handler real (`bindAction`) mantém esse handler, como hoje.
 3. **Cenários são registrados fora do contrato, pelo nome da action.** O plugin ganha a opção
    `scenarios`, com um ou mais globs. Os módulos casados exportam cenários criados por
-   `defineDesignScenario(contrato, resposta)`, e a resposta pode ser um valor ou uma função tipada
+   `defineDesignScenario(contract, response)`, e a resposta pode ser um valor ou uma função tipada
    pela entrada e pela saída do contrato. O cenário vence a resposta padrão. Um cenário para uma
    action inexistente é erro visível no preview, não um silêncio.
 4. **O Opus não decide onde os cenários ficam.** A opção não tem default dentro do código da

package/docs/adr/0061-claude-md-imports-agents-md.md

@@ -0,0 +1,41 @@
+# ADR 0061 — O `CLAUDE.md` importa o `AGENTS.md`
+
+- **Status:** aceita.
+- **Data:** 2026-10-15.
+- **Acompanha:** ADR 0006 do `@softize/base`, que define o mesmo formato.
+
+## Contexto
+
+O `opus setup` escrevia o bloco de instruções do Opus no `AGENTS.md`, lido pelo Codex, e no
+`CLAUDE.md`, lido pelo Claude. A Base fazia o mesmo com o bloco dela. Fora dos blocos, cada projeto
+mantinha à mão as próprias regras nos dois arquivos, e as duas cópias divergiam: na GrandBrasil,
+quatro convenções existiram só no `AGENTS.md` por doze dias, e as sessões do Claude trabalharam sem
+elas.
+
+A documentação do Claude Code recomenda, para quem usa as duas ferramentas, um `CLAUDE.md` com a
+linha `@AGENTS.md`. A Base adotou esse formato na ADR 0006. Como o `CLAUDE.md` recebe blocos dos
+dois pacotes, e cada projeto adota as versões deles em momentos diferentes, o Opus precisa seguir
+a mesma regra para que um `setup` não desfaça o do outro.
+
+## Decisão
+
+O `AGENTS.md` é o único arquivo com instruções. O `opus setup` mantém nele o bloco do Opus e grava
+o `CLAUDE.md` como a linha `@AGENTS.md`, sem marcador.
+
+Ao reconciliar o `CLAUDE.md`, o Opus remove só o próprio bloco, quando íntegro. Blocos de outros
+pacotes ficam depois da linha do import, separados por uma linha em branco, até que o pacote dono
+os remova. O texto do projeto fora dos blocos e do import é comparado com o do `AGENTS.md`, com fim
+de linha, espaços no fim das linhas e linhas em branco seguidas normalizados: se for igual, é
+cópia e sai; se for diferente, `setup` e `opus check` preservam o arquivo e pedem para mover as
+instruções para o `AGENTS.md`. Os critérios de bloco, de linha do import e de normalização são os
+da Base, e as mensagens seguem as dela, trocando o comando por `opus setup`.
+
+## Consequências
+
+- Projeto com instruções só no `CLAUDE.md` precisa movê-las para o `AGENTS.md` antes de o `setup`
+  concluir. Por isso a mudança sai numa versão major.
+- Enquanto um projeto usa uma Base anterior à ADR 0006, o `CLAUDE.md` fica com o import e o bloco
+  da Base. O conteúdo da Base aparece duas vezes para o Claude, pelo import e pelo bloco, até a
+  adoção da Base nova; o arquivo não oscila entre os dois `setup`.
+- Um bloco do Opus editado à mão ou um bloco gerenciado malformado no `CLAUDE.md` são preservados e
+  reprovados, como antes.

package/docs/adr/README.md

@@ -14,3 +14,5 @@ estar documentado na superfície correspondente, sem exigir a reconstrução des
 - [ADR 0059 — Subheadings orientam sem carregar regras de negócio](0059-subheadings-orient-without-carrying-business-rules.md).
 
 - [ADR 0060 — Composição de superfícies com cabeçalho e intro](0060-surface-composition-separates-chrome-and-intro.md).
+
+- [ADR 0061 — O `CLAUDE.md` importa o `AGENTS.md`](0061-claude-md-imports-agents-md.md).

package/docs/code-style.md

@@ -48,8 +48,12 @@ dinâmica, importada sem fallback ou composta de forma opaca reprova a extraçã
 lacunas conhecidas visíveis em vez de produzir um inventário verde e incompleto.
 
 Transformações visuais não observáveis e exceções ficam explícitas em `base.json`, usando um
-seletor estável e revisável. `source`, `line` e `role` devem identificar exatamente uma entrada;
-`text` é um refinamento opcional. Mudanças que invalidam o seletor reprovam a extração. Metadata
+seletor estável e revisável. `source`, `role` e `text` selecionam o texto pelo conteúdo: a
+declaração vale para toda ocorrência desse texto com esse papel no arquivo e continua válida
+quando linhas entram ou saem acima dela. Um seletor que não encontra o texto reprova a extração,
+porque o texto mudou ou saiu do arquivo. O formato anterior, com `line` no lugar de `text` (ou
+junto dele), ainda é aceito e seleciona exatamente uma entrada naquela linha; `opus copy
+--reanchor` converte esses seletores para o formato por conteúdo. Metadata
 pode complementar a análise, mas nunca sobrescrever uma transformação já observada no JSX —
 `transform: "none"` não mascara `className="uppercase"`. O Opus valida o shape `COPYnnn`; a
 Base instalada é dona do catálogo, dos kinds aceitos e do fundamento de cada regra:
@@ -63,16 +67,16 @@ Base instalada é dona do catálogo, dos kinds aceitos e do fundamento de cada r
     "transforms": [
       {
         "source": "src/account.ts",
-        "line": 12,
         "role": "button",
+        "text": "Confirmar",
         "transform": "uppercase"
       }
     ],
     "exemptions": [
       {
         "source": "src/account.ts",
-        "line": 18,
         "role": "label",
+        "text": "ABC-123",
         "ruleId": "COPY001",
         "kind": "external-requirement",
         "reason": "Código regulatório exibido na grafia oficial.",
@@ -145,21 +149,56 @@ exigiria adivinhar espaços continuam reprovando.
 
 Quando o diagnóstico corresponde a dados reais da aplicação ou a uma mensagem interpolada,
 `copy.dynamic` permite classificar somente aquela superfície sem excluir o arquivo. Cada item
-seleciona exatamente um diagnóstico por `source`, `line` e `field`, registra `reason` e
-`reference` auditáveis e usa um destes contratos:
+seleciona o diagnóstico por `source`, `field` e `expression` — o trecho de código que o
+extrator não conseguiu resolver; a mensagem do `opus copy` traz os dois valores prontos para
+copiar —,
+registra `reason` e `reference` auditáveis e usa um destes contratos:
 
 - `runtime-data` reconhece nomes, contagens, status ou opções fornecidos em runtime. Nenhuma
   entrada editorial é fabricada;
 - `message-template` exige `role` e `text`. O texto-modelo entra no inventário e passa pela
   política da Base, mas não substitui nem altera o conteúdo renderizado.
 
-As declarações aparecem em `dynamicSurfaces` no inventário. Se o source mudar e o seletor não
-encontrar exatamente um diagnóstico, `opus copy` falha. Assim, a classificação permanece
+No trecho, espaços e quebras de linha viram um espaço só e a vírgula final antes de `)`, `]` ou
+`}` é ignorada, para a âncora sobreviver à reformatação; trechos com mais de 200 caracteres são
+cortados e terminam em `…`. A declaração vale para toda ocorrência do mesmo trecho no mesmo
+campo do arquivo e não depende da linha em que ele está.
+
+As declarações aparecem em `dynamicSurfaces` no inventário, com as linhas atuais de cada
+ocorrência. Se o código mudar e o seletor deixar de encontrar o trecho, `opus copy` falha e lista,
+numa execução, todas as declarações quebradas, cada uma com o arquivo, o campo e os trechos desse
+campo que ainda não têm declaração. Assim, a classificação permanece
 estreita e revisável, sem transformar metadata em uma exclusão silenciosa. O mecanismo aceita
 somente diagnósticos de conteúdo; incerteza estrutural, `className`, `style`, transformação ou
 modo de renderização continua bloqueante. Superfície vazia também não pode ser reclassificada
 como dado de runtime.
 
+Declarações escritas antes da versão 29.0.0 usam `line` no lugar de `expression` (ou de `text`,
+nas exceções e transformações) e quebram sempre que alguém edita o arquivo acima delas. Elas
+continuam aceitas, selecionam exatamente um alvo naquela linha e são aplicadas antes das
+declarações por conteúdo, para que uma declaração pontual não seja coberta por uma geral; o
+`opus copy` avisa quantas restam. Para convertê-las, rode `opus copy --reanchor`. O comando
+agrupa as declarações por arquivo e campo (em `copy.dynamic`) ou por arquivo, papel e texto
+(nas exceções e transformações), grava o `base.json` e regenera o inventário:
+
+- um grupo só é convertido quando tem exatamente uma declaração para cada alvo. Assim a âncora
+  por conteúdo cobre os mesmos alvos que as âncoras por linha cobriam. Se o mesmo texto aparece
+  mais vezes do que foi declarado, ou se há um diagnóstico do campo sem declaração, o grupo
+  continua por linha e aparece no relatório;
+- dentro do grupo, declarações e alvos são pareados em ordem de linha. Quando o arquivo mudou e
+  as âncoras quebraram, o comando lista cada declaração que mudou de linha para revisão no diff;
+- declarações idênticas que passariam a selecionar o mesmo conteúdo viram uma só;
+- duas declarações com motivos diferentes para o mesmo conteúdo continuam por linha, já
+  corrigida, porque um seletor por conteúdo cobriria as duas com um único motivo. Para
+  convertê-las, unifique o motivo ou mantenha a âncora por linha;
+- os seletores gravados precisam passar na extração do `opus copy`; o que não dá para ancorar com
+  segurança fica como está e aparece no relatório.
+
+O `--reanchor` não avalia a política de copy da Base. Depois dele, rode `opus copy --check` e
+`base copy check`. Na revisão de uma declaração por conteúdo, vale olhar `dynamicSurfaces[].lines`
+no diff do inventário: uma lista que cresce indica que um trecho genérico, como `title` ou
+`count`, passou a cobrir uma ocorrência nova, que pode ter outra origem.
+
 Um `opus copy --check` verde **não significa que toda a copy do produto foi coberta**. Ficam
 fora, deliberadamente:
 

package/docs/protocol.md

@@ -679,7 +679,7 @@ O acesso do sistema é **opt-in por action** e negado por padrão. Sem usuário,
 `isSystemActor(ctx)` responde se o ator é o sistema. Ele consulta um registro interno dos contextos que o runtime criou, e não a provenance. Como o sistema não detém permissões, um `authorize` que delega a `ctx.can` o aceita de forma explícita, numa closure — a DSL em string não expressa isso, e `ctx.provenance` não serve como teste de sistema, porque o chamador de `runtime.execute` pode preenchê-la:
 
 ```ts
-authorize: (ctx) => isSystemActor(ctx) || ctx.can('caixa:fechar')
+authorize: (ctx) => isSystemActor(ctx) || ctx.can('ledger:close')
 ```
 
 `requires` continua declarativo; o manifest projeta `automatable` ao lado de `permission`. O audit registra `actor: { id: null, type: 'system' }`. Ver ADR 0028.

package/docs/releasing.md

@@ -18,6 +18,13 @@ confere essa entrada só DEPOIS do bump, então esquecê-la aborta a release com
 alterado — e a tentativa seguinte para na guarda de árvore limpa. Para recuperar, desfaça o bump
 (`git checkout -- package.json`), escreva a entrada, commite e rode de novo.
 
+Uma entrada que já está na `origin/main` não muda mais: quem consome o pacote lê o changelog como
+guia de migração, e em 10/09/2026 uma formatação avulsa reescreveu entradas publicadas e mudou o
+sentido de uma delas. Para corrigir uma informação publicada, registre a correção numa entrada
+nova, na próxima versão. A entrada da versão em preparo, enquanto não chega à `main`, pode ser
+ajustada livremente. O pre-push (`.githooks/pre-push.d/01-changelog`) e o `pnpm release` reprovam
+a alteração de uma seção publicada; para conferir antes, rode `pnpm changelog:check` na raiz.
+
 Os comandos rodam em `packages/opus`; o `package.json` da raiz não tem `release`.
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "28.0.0",
+  "version": "29.0.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

@@ -24,7 +24,9 @@ artefatos de agentes fica em `base.json`; cada app Opus mantém seu marcador `op
   e operá-los por `opus seed`; não criar comandos de seed paralelos nem reset implícito.
 - Regenerar o inventário com `opus copy` quando mudar copy em contrato ou componente Opus
   mapeado; o Opus classifica os papéis semânticos e a política universal de `@softize/base`
-  valida o conteúdo.
+  valida o conteúdo. O inventário também guarda o hash de todo arquivo JS/TS do escopo, mesmo sem
+  copy, como os scripts em `scripts/*.mjs`; alterar qualquer um deles também exige `opus copy`,
+  e o pre-push reprova o inventário desatualizado.
 - Rodar `opus check`, `opus copy --check` e os gates do projeto depois de alterar actions,
   bindings ou versão do SDK.
 - Quando a default branch tiver adotado uma versão diferente da worktree, reconciliar a

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

@@ -89,10 +89,12 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
 Rodar `opus check`, testes focados, typecheck e build da superfície. Se a interface alterou
 copy em contrato ou componente Opus mapeado, regenerar com `opus copy` e executar
 `base copy check`. Quando uma superfície mapeada recebe dados da aplicação, usar
-`copy.dynamic` com seletor exato, motivo e referência: `runtime-data` para valores sem autoria
-editorial; `message-template` com `role` e texto-modelo para mensagens interpoladas. Não excluir
+`copy.dynamic` com `field` e `expression` copiados do diagnóstico, motivo e referência:
+`runtime-data` para valores sem autoria editorial; `message-template` com `role` e
+texto-modelo para mensagens interpoladas. Não usar `line` em declaração nova. Não excluir
 o arquivo inteiro nem contornar o diagnóstico com `aria-label` paralelo. Revisar cada declaração
-dinâmica como fronteira de cobertura, mesmo com os gates verdes.
+dinâmica como fronteira de cobertura, mesmo com os gates verdes, inclusive quando
+`dynamicSurfaces[].lines` cresce no diff do inventário.
 Inspecionar visualmente a rota real e validar navegação por URL quando aplicável.
 
 ## Limites

package/registry/skills/maintain-opus-docs/SKILL.md

@@ -52,7 +52,8 @@ o código não sustenta.
 
 Executar `node scripts/audit-docs.mjs "$(git rev-parse --show-toplevel)"` a partir do diretório
 desta skill e, depois, os testes do renderer e do catálogo, typecheck, `opus check` e
-`opus copy --check`. Conferir
+`opus copy --check`. No repositório do Opus, o teste `tests/scripts/example-language.test.ts`
+reprova identificadores com palavra em português nos exemplos e nas fontes; rode-o também. Conferir
 que todos os previews renderizam, que cada API pública documentada possui sua própria referência,
 que nenhum arquivo publicado ficou órfão e que links e redirects chegam à página esperada. Fazer uma
 passada visual nas páginas alteradas e registrar qualquer limitação que o gate automático não cubra.

package/registry/skills/maintain-opus-docs/references/editorial-standard.md

@@ -40,6 +40,13 @@ genérica.
 - Depois do código, explicar somente efeitos que não sejam óbvios pela leitura: default aplicado,
   estado controlado, ação automática, limite ou consequência.
 - Usar preview para comportamento visual e bloco de código para integração sem palco executável.
+- Escrever o código dos exemplos em inglês, como o resto do código: variáveis, funções, campos,
+  nomes de action, domínios, eventos, schedules, permissões e caminhos de arquivo
+  (`ledgerCloseContract`, `ledger.close`, `ledger:close`, `design/scenarios/orders.ts`). Isso vale
+  também para o código em crase no meio da prosa. O texto que a pessoa vê — `label`, mensagens,
+  descrições, conteúdo JSX — e os comentários continuam em pt-BR. Um exemplo fictício não tem
+  vocabulário de domínio estabelecido, então a exceção de domínio das instruções do projeto não se
+  aplica a ele.
 
 ## Famílias e referência
 
@@ -74,6 +81,8 @@ Para cada título, parágrafo, item, exemplo e célula de tabela, verificar:
 8. O texto ao redor do exemplo explica intenção e comportamento, sem narrar cada linha do código?
 9. O título permite localizar a informação pela tarefa, inclusive por link direto?
 10. Pontuação, capitalização, concordância e paralelismo estão consistentes?
+11. Os identificadores do exemplo e do código em crase estão em inglês, e o texto exibido à pessoa,
+    em pt-BR?
 
 Ao terminar cada página, reler a sequência inteira. Linhas corretas isoladamente ainda podem formar
 uma página repetitiva, invertida ou sem progressão.

package/registry/skills/maintain-opus-docs/references/evaluations.md

@@ -1,3 +1,5 @@
+<!-- language-exempt-file: o caso de avaliação descreve de propósito um exemplo com identificadores em português. -->
+
 # Avaliações
 
 ## Deve disparar
@@ -32,3 +34,9 @@ Exigir inventário explícito, leitura linha por linha, correção na fonte can
 previews, typecheck, gates de copy e confirmação de que não restaram páginas órfãs. Reprovar se a
 execução se limitar às páginas mais longas, fizer apenas busca por padrões ou declarar cobertura
 total sem listar o universo revisado.
+
+Num exemplo de agendamento com `caixaFecharContract`, a action `caixa.fechar`, a permissão
+`caixa:fechar` e o rótulo `Fechar caixa`, pedir a revisão da página sem apontar o problema.
+Aprovar somente quando identificadores, action, domínio e permissão passarem para o inglês, o
+rótulo continuar em pt-BR e o gate de idioma passar. Reprovar se o rótulo for traduzido ou se a
+exceção de vocabulário de domínio for usada para manter o exemplo fictício em português.

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

@@ -1,5 +1,5 @@
 # Permissão de build scripts (o pnpm bloqueia por default): o postinstall do
-# @softize/opus roda o `opus setup` (pin + bloco gerenciado do CLAUDE.md) a cada
+# @softize/opus roda o `opus setup` (pin + bloco gerenciado do AGENTS.md) a cada
 # install; o esbuild (vite) compila o binário nativo.
 allowBuilds:
   '@softize/opus': true

package/src/core/system-actor.ts

@@ -17,7 +17,7 @@ const systemContexts = new WeakSet<object>()
 /**
  * Diz se a action está executando como o sistema: disparada por um schedule, ou no job que ele
  * enfileirou, sem usuário. Use no `authorize` de uma action `automatable` para aceitar o sistema
- * de forma explícita: `authorize: (ctx) => isSystemActor(ctx) || ctx.can('caixa:fechar')`.
+ * de forma explícita: `authorize: (ctx) => isSystemActor(ctx) || ctx.can('ledger:close')`.
  * Passe o próprio `ctx` recebido: uma cópia, como `{ ...ctx }`, não é reconhecida.
  */
 export function isSystemActor(ctx: ActionContext): boolean {

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

@@ -3058,7 +3058,7 @@ export function ActionList<TInput, TItem>({
 // URL sync — a serialização padrão do estado da toolbar (querystring compacta)
 // =============================================================================
 //
-// Convenção: `q` · `sort=chave:dir` (omitido quando é o default do contrato) ·
+// Convenção: `q` · `sort=key:dir` (omitido quando é o default do contrato) ·
 // `period=preset` relativo ou `period=from..to` (o custom é implícito; default
 // omitido) · `view` (omitida quando é a primeira) · `cols=a,b,c` (omitida no
 // default) · filtros pelo PRÓPRIO nome (multiple → CSV). Quem embala liga:

package/src/ui/docs/content/action-list.md

@@ -459,7 +459,7 @@ restaurá-lo.
 />
 ```
 
-Convenção compacta (defaults omitidos): `?q=…&sort=chave:dir&status=…&view=board&cols=a,b,c&limit=25`.
+Convenção compacta (defaults omitidos): `?q=…&sort=key:dir&status=…&view=board&cols=a,b,c&limit=25`.
 
 ## Composição dos itens
 

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

@@ -323,7 +323,7 @@ A resposta é tipada pela entrada e pela saída do contrato; em `list`, é a pá
 plugin onde os cenários estão, com caminhos ou globs:
 `opusDesign({ scenarios: 'design/scenarios/**/*.ts' })`. Nos globs, `*` casa parte do nome dentro
 de uma pasta e `**` casa qualquer número de pastas, inclusive nenhuma: o padrão do exemplo carrega
-tanto `design/scenarios/pedidos.ts` quanto `design/scenarios/pedidos/lista.ts`. O cenário vence a
+tanto `design/scenarios/orders.ts` quanto `design/scenarios/orders/list.ts`. O cenário vence a
 resposta gerada. Um cenário de uma action que não existe, ou dois cenários para a mesma action,
 impedem o runtime de design de subir, e o erro lista os nomes.
 

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

@@ -64,8 +64,8 @@ const runtime = createRuntime({
 })
 
 // Na action: `authorize` decide antes do handler, com o contexto já resolvido.
-export const notaEmitir = bindAction(notaEmitirContract, {
-  authorize: (ctx) => ctx.can('nota.emitir'),
+export const invoiceIssue = bindAction(invoiceIssueContract, {
+  authorize: (ctx) => ctx.can('invoice:issue'),
   handler: async (ctx, input) => repo.create({ ...input, tenantId: ctx.tenantId }),
 })
 ```
@@ -95,7 +95,7 @@ Quando a decisão depende de dado que só o handler conhece, verifique no própr
 ```ts
 import { error } from '@softize/opus/core'
 
-if (!(await ctx.can('nota.cancelar', nota))) {
+if (!(await ctx.can('invoice:cancel', invoice))) {
   throw error({ code: 'auth.forbidden', category: 'authorization', message: 'Acesso negado' })
 }
 ```

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

@@ -82,6 +82,7 @@ opus gen                                    # manifest / openapi / docs / stubs
 opus gen --config ./apps/api/opus.config.ts # config fora do diretório atual
 opus gen --output ./custom/gen              # pasta de saída (padrão: a do config, ou ./.gen)
 opus copy                                   # inventário semântico de copy dos contratos
+opus copy --reanchor                        # ancora pelo conteúdo as declarações antigas do base.json
 opus introspect                             # modelo da estrutura: actions, reactions, schedules e ligações
 opus introspect --json
 ```
@@ -92,6 +93,11 @@ copy da `@softize/base` valida. O caminho vem de `base.json` (`copy.inventory`;
 versionado. `--check` compara sem escrever e falha quando o inventário está ausente,
 desatualizado ou contém copy dinâmica não declarada.
 
+Declarações de `copy.dynamic`, `copy.exemptions` e `copy.transforms` são ancoradas pelo conteúdo
+(`expression` ou `text`), e não pela linha. `opus copy --reanchor` converte as declarações antigas,
+ancoradas por `line`, grava o `base.json` e lista para revisão as que mudaram de linha ou
+continuam por linha; o detalhe está em `docs/code-style.md` do pacote.
+
 `opus introspect` lê o código sem executá-lo e só reconhece `defineAction`, `defineReaction`,
 `defineSchedule` e `defineDataProduct`. Actions do par `defineContract` e `bindAction`, reactions do
 par `defineReactionContract` e `bindReaction` e schedules declarados sem `defineSchedule` ficam fora

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

@@ -68,7 +68,7 @@ declaração adicional:
   respostas (`alert`, `prompt`, `choose`) entram no inventário como se fossem props de um
   `ActionFormDialog`; o campo do diagnóstico é `dialog.confirm().title`,
   `dialog.choose().actions[0].label` etc. Constantes locais resolvem normalmente. Uma função
-  que devolve template (`body: describe(nome)`) gera o diagnóstico `content` habitual e
+  que devolve template (`body: describe(name)`) gera o diagnóstico `content` habitual e
   se declara em `copy.dynamic` como `message-template`. Opções construídas em tempo de execução
   ou mutadas depois de declaradas reprovam como estrutura, porque nenhum texto pode ser
   atribuído a elas.
@@ -80,7 +80,7 @@ declaração adicional:
   mesmo arquivo, cada literal do array vira um texto na linha em que foi escrito, em vez de um
   diagnóstico sobre a prop. `filter`, `slice`, `toSorted` e `toReversed` podem ficar entre o
   array e a iteração. O limite é deliberado: o array precisa ser literal e declarado no mesmo
-  arquivo; o elemento só pode ser lido (`item.chave`), nunca passado adiante, espalhado ou
+  arquivo; o elemento só pode ser lido (`item.key`), nunca passado adiante, espalhado ou
   atribuído; o callback não pode receber o próprio array como terceiro parâmetro; e nenhum
   elemento pode ter a chave dinâmica. Arrays importados, derivados por spread ou por
   concatenação continuam gerando o diagnóstico da prop.
@@ -97,13 +97,15 @@ visual que o protocolo não representa com segurança.
 é copy editorial estável; `label` e `confirm.*` são as superfícies editoriais cobertas.
 
 Quando uma prop mapeada recebe dados da aplicação, declare a superfície em
-`base.json.copy.dynamic` em vez de excluir o arquivo inteiro. O seletor usa o caminho, a
-linha e o campo exibido pelo diagnóstico. `runtime-data` registra valores como nomes,
+`base.json.copy.dynamic` em vez de excluir o arquivo inteiro. O seletor usa o caminho, o campo
+e o trecho de código exibidos pelo diagnóstico, sem a linha: a declaração continua válida quando
+o arquivo muda acima dela. `runtime-data` registra valores como nomes,
 contagens e opções vindas de API sem transformá-los em copy editorial. `message-template`
 acrescenta ao inventário um texto-modelo com papel semântico, para que a parte autoral de uma
 mensagem interpolada continue passando pela política da Base. As declarações não alteram o
-que o React renderiza; um seletor que deixa de corresponder a um único diagnóstico reprova o
-gate e precisa ser revisto. Diagnósticos estruturais ou de transformação visual não podem ser
+que o React renderiza; um seletor que deixa de encontrar o trecho reprova o gate e precisa ser
+revisto. Declarações antigas, ancoradas por `line`, são convertidas com `opus copy --reanchor`.
+Diagnósticos estruturais ou de transformação visual não podem ser
 dispensados por `copy.dynamic`; ausência de conteúdo também continua bloqueante.
 
 ```json
@@ -112,7 +114,7 @@ dispensados por `copy.dynamic`; ausência de conteúdo também continua bloquean
     "dynamic": [
       {
         "source": "src/sessions.tsx",
-        "line": 42,
+        "expression": "sessionOptions",
         "field": "<Select>.options",
         "kind": "runtime-data",
         "reason": "As opções são nomes de sessões retornados pela aplicação.",
@@ -120,7 +122,7 @@ dispensados por `copy.dynamic`; ausência de conteúdo também continua bloquean
       },
       {
         "source": "src/sessions.tsx",
-        "line": 58,
+        "expression": "`Excluir ${session.name}?`",
         "field": "dialog.confirm().body",
         "kind": "message-template",
         "role": "dialog-body",

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

@@ -17,7 +17,7 @@ interface EventBusAdapter {
 }
 
 interface DomainEvent<T = unknown> {
-  type: string                                   // 'nota.emitida'
+  type: string                                   // 'invoice.issued'
   id: string
   timestamp: string
   actor: { id: string | null; type?: 'user' | 'system' | 'integration' }
@@ -39,7 +39,7 @@ const bus = mittEvents() // no mesmo processo do runtime
 ```
 
 O `mitt` entrega pelo nome exato do evento ou por `*`, que recebe todos. Padrões parciais, como
-`nota.*`, não são reconhecidos: assine `*` e filtre no handler.
+`invoice.*`, não são reconhecidos: assine `*` e filtre no handler.
 
 ## Emitir de uma action
 
@@ -51,13 +51,13 @@ const runtime = createRuntime({
   eventBus: bus,
 })
 
-export const notaEmitir = bindAction(notaEmitirContract, {
-  emits: ['nota.emitida'],
+export const invoiceIssue = bindAction(invoiceIssueContract, {
+  emits: ['invoice.issued'],
   handler: async (ctx, input) => {
-    const nota = await repo.create(input)
+    const invoice = await repo.create(input)
     // O runtime preenche id, timestamp, actor, tenant, source e trace.
-    await ctx.emit('nota.emitida', { id: nota.id, valor: nota.valor })
-    return nota
+    await ctx.emit('invoice.issued', { id: invoice.id, amount: invoice.amount })
+    return invoice
   },
 })
 ```
@@ -86,21 +86,21 @@ no código compartilhado e o efeito, no servidor:
 import { bindReaction, defineReactionContract } from '@softize/opus/core'
 
 // shared/ — qual evento e o que a reação significa.
-export const notaAvisarFinanceiro = defineReactionContract<{ id: string; valor: number }>({
-  name: 'nota.avisar-financeiro',
-  on: 'nota.emitida',
+export const invoiceNotifyFinance = defineReactionContract<{ id: string; amount: number }>({
+  name: 'invoice.notify-finance',
+  on: 'invoice.issued',
   description: 'Avisa o financeiro quando uma nota é emitida.',
 })
 
 // api/ — o efeito.
-export const notaAvisarFinanceiroImpl = bindReaction(notaAvisarFinanceiro, {
+export const invoiceNotifyFinanceImpl = bindReaction(invoiceNotifyFinance, {
   handler: async (ctx, event) => {
-    ctx.log.info('nota emitida', { id: event.data.id, valor: event.data.valor })
+    ctx.log.info('nota emitida', { id: event.data.id, amount: event.data.amount })
   },
 })
 ```
 
-Registre a reaction com as actions, em `defineDomain({ reactions: [notaAvisarFinanceiroImpl] })`
+Registre a reaction com as actions, em `defineDomain({ reactions: [invoiceNotifyFinanceImpl] })`
 ou em `runtime.register`. Com reactions registradas, o `start()` exige um `EventBusAdapter` e falha
 com `runtime.eventbus_required` quando ele não existe. `defineReaction` declara tudo num objeto só,
 quando não há separação entre cliente e servidor.

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

@@ -25,6 +25,10 @@ pnpm test
 O aplicativo inclui um domínio de tarefas, `opus.config.ts`, Vite, React, o tema do Opus e os
 comandos de teste e verificação. O dev server respeita a variável `PORT`. `opus.json` registra a
 versão do SDK adotada pelo app; `setup` materializa as instruções, skills e hooks gerenciados.
+As instruções ficam no `AGENTS.md`, que qualquer agente lê; o `CLAUDE.md` contém só a linha
+`@AGENTS.md`, que as importa para o Claude Code. Escreva as regras do seu projeto no `AGENTS.md`:
+o `setup` recusa um `CLAUDE.md` com instruções que não estão no `AGENTS.md` e pede que elas sejam
+movidas para lá.
 
 Quando os testes passarem, continue em [Primeiros passos](/docs/getting-started).