@softize/opus 25.6.0 → 26.0.0

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

@@ -63,13 +63,125 @@ render(
 )
 ```
 
+## Com imagens anexadas
+
+Quando a mensagem pode levar imagens, como um print de relatório para a IA reproduzir, passe
+`attachments`. O composer ganha o botão **Anexar imagem** na barra e uma faixa acima do campo, com a
+miniatura, o nome e o estado de cada imagem. Colar uma imagem no campo e soltá-la sobre o composer
+também anexam.
+
+O estado é do aplicativo, porque é ele quem envia e guarda a imagem. O composer faz a triagem e
+entrega os arquivos aceitos em `onAddFiles`; o aplicativo acrescenta cada um à lista como
+`uploading`, prepara a imagem com [`prepareImage`](#preparar-a-imagem-antes-do-envio), envia e muda o
+estado para `ready` ou `failed`. Depois do envio da mensagem, é o aplicativo que limpa a lista e
+revoga os endereços das miniaturas que criou.
+
+```tsx preview col
+const [text, setText] = React.useState('')
+const [items, setItems] = React.useState<ComposerAttachment[]>([])
+const nextId = React.useRef(1)
+const previews = React.useRef<Record<string, string>>({})
+
+// A miniatura é um endereço de objeto, que segura a imagem na memória até ser revogado.
+function release(id: string) {
+  const url = previews.current[id]
+  if (url !== undefined) URL.revokeObjectURL(url)
+  delete previews.current[id]
+}
+React.useEffect(() => () => Object.keys(previews.current).forEach(release), [])
+
+async function add(files: File[]) {
+  for (const file of files) {
+    const id = String(nextId.current++)
+    const prepared = await prepareImage(file)
+    if (!prepared.ok) {
+      setItems((list) => [...list, { id, name: file.name, status: 'failed', error: prepared.message }])
+      continue
+    }
+    previews.current[id] = URL.createObjectURL(prepared.file)
+    setItems((list) => [
+      ...list,
+      { id, name: prepared.file.name, status: 'uploading', previewUrl: previews.current[id] },
+    ])
+    // Aqui o aplicativo envia `prepared.file` ao próprio servidor.
+    await new Promise((r) => setTimeout(r, 800))
+    setItems((list) => list.map((item) => (item.id === id ? { ...item, status: 'ready' } : item)))
+  }
+}
+
+render(
+  <Composer
+    value={text}
+    onChange={setText}
+    onSubmit={() => {
+      items.forEach((item) => release(item.id))
+      setText('')
+      setItems([])
+    }}
+    placeholder="Cole, solte ou anexe um print…"
+    attachments={{
+      items,
+      onAddFiles: (files) => void add(files),
+      onRemove: (id) => {
+        release(id)
+        setItems((list) => list.filter((item) => item.id !== id))
+      },
+    }}
+  />,
+)
+```
+
+O envio passa com texto ou com pelo menos uma imagem pronta. Enquanto alguma imagem está sendo
+enviada, o botão de enviar espera; uma imagem com falha também bloqueia o envio até ser removida ou
+reenviada pelo aplicativo, para que nada do que está na faixa fique de fora sem aviso. Quem usa leitor
+de tela ouve quando uma imagem fica pronta ou falha, e, se o botão de anexar ficar desabilitado ao
+atingir o limite, o foco volta ao campo.
+
+A triagem aceita PNG, JPEG e WebP, até quatro imagens por mensagem; `accept` e `max` mudam esses
+limites. `accept` é um subconjunto desses três formatos, comparado com o tipo exato do arquivo, sem
+curinga como `image/*`. O que fica de fora é explicado acima do campo, como “Cada mensagem aceita até 4 imagens.”.
+Para dar outra explicação, passe `onReject`: o composer deixa de mostrar o aviso e entrega os
+arquivos recusados, com o motivo, ao aplicativo.
+
+Colar texto continua colando texto, mesmo quando a área de transferência também traz uma imagem, como
+ao copiar células de uma planilha. Uma imagem colada sem texto, como um print, recebe um nome que a
+pessoa reconhece na conversa: “Imagem colada 1.png”. A numeração não volta atrás: remover a primeira e
+colar outra dá “Imagem colada 3.png”, e nunca duas imagens com o mesmo nome no mesmo composer.
+
+O soltar que o composer recebe não sobe para os contêineres do aplicativo. Dentro do
+[Chat](/ui/chat#imagens-na-conversa), quem recebe o soltar é a conversa inteira.
+
+## Preparar a imagem antes do envio
+
+`prepareImage(file, options)` deixa a imagem pronta para ir à conversa. Ela lê só o cabeçalho do
+arquivo para conferir o formato, pelos bytes e não pela extensão, e as dimensões; uma foto acima de
+`maxPixels` é recusada antes de ser aberta, porque decodificá-la ocuparia centenas de megabytes de
+memória. Depois, reduz a imagem até o lado maior caber em `maxEdge`, mantendo a proporção e a
+orientação gravada pela câmera, de modo que a foto tirada com o celular em pé chega em pé; e codifica
+a imagem de novo, o que também descarta metadados como a localização. PNG continua PNG quando cabe em `maxBytes`; JPEG, WebP e o PNG que passa do teto viram
+JPEG com qualidade 0,85, sobre fundo branco.
+
+```ts
+const result = await prepareImage(file, { maxEdge: 1568, maxBytes: 3 * 1024 * 1024 })
+if (result.ok) {
+  await upload(result.file) // result.mediaType, result.width, result.height, result.size
+} else {
+  showError(result.message) // "Imagens animadas não são aceitas. Envie uma imagem parada…"
+}
+```
+
+A função não lança erro. Uma imagem fora dos formatos aceitos, animada, ilegível, com pixels demais ou
+que continua acima do teto depois de reduzida volta como `{ ok: false, reason, message }`, com a explicação pronta para a
+pessoa. Os padrões repetem os tetos do primeiro consumidor; passe os do seu produto, de preferência os
+mesmos que o servidor confere.
+
 ## Propriedades de Composer
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `value` | `string` | | Texto controlado; o dono do estado é quem compõe. |
 | `onChange` | `(value: string) => void` | | Recebe cada alteração do texto. |
-| `onSubmit` | `() => void` | | Chamado por Enter (sem Shift) ou pelo botão de enviar, somente quando há texto e nem `busy` nem `submitDisabled` estão ativos. |
+| `onSubmit` | `() => void` | | Chamado por Enter (sem Shift) ou pelo botão de enviar, somente quando há texto ou imagem pronta, nenhuma imagem está sendo enviada ou com falha, e nem `busy` nem `submitDisabled` estão ativos. |
 | `onHistoryPrevious` / `onHistoryNext` | `() => boolean` | | Navegação por ↑/↓ no histórico do dono; retorne `true` quando a tecla foi consumida. |
 | `busy` | `boolean` | `false` | Bloqueia o envio enquanto a operação anterior corre e troca o ícone de enviar por um spinner. O campo continua editável. |
 | `submitDisabled` | `boolean` | `false` | Bloqueia o envio por uma condição do consumidor, como um seletor ainda sem escolha. |
@@ -77,4 +189,35 @@ render(
 | `rows` | `number` | `1` | Linhas iniciais do campo, que cresce com o conteúdo até `10rem`. |
 | `autoFocus` | `boolean` | | Foca o campo ao montar. |
 | `actions` | `ReactNode` | | Controles discretos à esquerda do botão de enviar; com eles, o composer passa a ter duas linhas. |
+| `attachments` | `ComposerAttachments` | | Liga as imagens anexadas: botão **Anexar imagem**, faixa acima do campo, colar e soltar. Com ele, o composer passa a ter duas linhas. |
 | `className` | `string` | | Classes aplicadas à moldura do composer. |
+
+## Propriedades de ComposerAttachments
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `items` | `ComposerAttachment[]` | | Imagens anexadas à mensagem que está sendo escrita, na ordem da faixa. |
+| `onAddFiles` | `(files: File[]) => void` | | Recebe os arquivos aceitos pela triagem, vindos do botão, do colar ou do soltar. |
+| `onRemove` | `(id: string) => void` | | A pessoa removeu uma imagem da faixa; o foco volta ao campo. |
+| `max` | `number` | `4` | Limite de imagens por mensagem. O botão de anexar fica desabilitado quando ele é atingido. |
+| `accept` | `readonly AiImageMediaType[]` | PNG, JPEG e WebP | Formatos aceitos pelo botão e pela triagem, comparados com o tipo exato do arquivo. |
+| `onReject` | `(rejections: ComposerFileRejection[]) => void` | | Recebe os arquivos recusados, com o motivo `type` ou `limit`. Sem ele, o composer explica a recusa acima do campo. |
+
+`ComposerAttachment` é `{ id, name, status, previewUrl?, error? }`. `status` vale `uploading`,
+`ready` ou `failed`; `previewUrl` é o endereço da miniatura e `error` é o motivo mostrado quando a
+imagem falha.
+
+## Opções de prepareImage
+
+| Opção | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `maxEdge` | `number` | `1568` | Lado maior, em pixels, depois da redução. Imagens menores não são ampliadas. |
+| `maxBytes` | `number` | 3 MB | Teto da imagem preparada. Acima dele, o PNG vira `lossyType`; o que continua acima é recusado. |
+| `accept` | `readonly AiImageMediaType[]` | PNG, JPEG e WebP | Formatos aceitos na entrada, conferidos pelos primeiros bytes. |
+| `lossyType` | `'image/jpeg' \| 'image/webp'` | `'image/jpeg'` | Formato de JPEG, WebP e do PNG que passa do teto. |
+| `quality` | `number` | `0.85` | Qualidade da codificação com perdas, de 0 a 1. |
+| `maxPixels` | `number` | `40_000_000` | Teto de largura × altura da imagem original, lido do cabeçalho antes de decodificar. |
+
+O resultado é `{ ok: true, file, mediaType, width, height, size, resized }` ou
+`{ ok: false, reason, message }`, em que `reason` vale `unsupported-type`, `animated`,
+`too-many-pixels`, `too-large` ou `unreadable`.

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

@@ -168,7 +168,7 @@ componente da feature em vez de copiá-lo.
 
 ## Largura mínima e densidade
 
-O Opus oferece suporte a partir de `64rem` e não muda a composição conforme a largura da viewport.
+A UI das aplicações oferece suporte a partir de `64rem` e não muda a composição conforme a largura da viewport.
 Props de tamanho, como `size="sm"`, escolhem a densidade do componente; não representam
 breakpoints. Overflow e limites contra a janela continuam protegendo o conteúdo.
 
@@ -176,6 +176,10 @@ Não adicione em `className` uma adaptação isolada por viewport ou container.
 futura precisa começar pelo shell e formar um contrato comum para navegação, splits, tabelas e
 componentes.
 
+O [portal de documentação](/docs/documentation-portal) tem uma exceção própria para adaptar
+cabeçalho, leitura editorial e catálogos em telas estreitas. Essa exceção não altera o contrato
+dos componentes demonstrados nos exemplos vivos nem autoriza adaptações isoladas na aplicação.
+
 ## O que fica fora das alavancas
 
 Alguns detalhes fazem parte da identidade visual do Opus e são iguais em todo projeto: a faixa do

package/src/ui/docs/content/documentation-portal.md

@@ -0,0 +1,190 @@
+# Publicação de documentação
+
+Quando uma aplicação precisa publicar seus próprios Markdown, use a superfície leve
+`@softize/opus/ui/docs/browser`. Ela oferece cabeçalho, navegação e leitura sem incluir o catálogo
+do Opus nem o compilador de exemplos vivos.
+
+## Componha o portal
+
+O aplicativo escolhe a marca, as seções, as rotas e as ações. `DocHeader` alinha os controles no
+topo; `DocBrowser` pesquisa as páginas e organiza a leitura. O valor da busca é compartilhado,
+mas o campo aparece somente no cabeçalho:
+
+```tsx
+import { useState } from 'react'
+import { DocBrowser, DocHeader, type DocSection } from '@softize/opus/ui/docs/browser'
+import { Input } from '@softize/opus/ui/react'
+
+export function Documentation({ sections }: { sections: DocSection[] }) {
+  const [query, setQuery] = useState('')
+  return (
+    <div className="flex h-dvh flex-col">
+      <DocHeader
+        brand={<a href="/docs">Meu produto</a>}
+        search={<Input type="search" aria-label="Buscar na documentação"
+          value={query} onChange={(event) => setQuery(event.target.value)} />}
+      />
+      <main className="min-h-0 flex-1">
+        <DocBrowser sections={sections} sidebarSize="17rem" editorial sidebarInitiallyCollapsed
+          search={{ placement: 'external', value: query }} />
+      </main>
+    </div>
+  )
+}
+```
+
+Marca, busca e ações usam o mesmo alinhamento vertical. O campo tem até `22rem` e fica centralizado
+no cabeçalho, com colunas de mesma largura nas extremidades. A navegação superior é opcional; quando
+for necessária, ocupa uma linha própria. Em telas menores que `64rem`, a busca ganha sua própria linha. Não é necessário
+copiar esse grid no aplicativo. Links e controles mantêm seu comportamento nativo: o aplicativo
+continua responsável por navegar, trocar tema ou abrir o repositório.
+
+## Declare um percurso de leitura
+
+As `sections` organizam grupos e páginas na ordem declarada. Use essa ordem para aproximar
+conceitos relacionados, não para reproduzir automaticamente a árvore de arquivos. Cada página
+tem `slug`, `title` e `render`; `searchText` acrescenta conteúdo à busca e `navigationTitle` permite
+um rótulo lateral curto sem mudar o título completo.
+
+Com `editorial`, a leitura recebe contexto, sumário dos títulos renderizados e links de página
+anterior e seguinte. `additionalPages` preserva destinos diretos que não entram nessa sequência.
+A busca documental do topo mantém seu rótulo, valor e função ao navegar para catálogos e detalhes;
+continua pesquisando os guias na lateral. Consultas locais ficam no conteúdo da própria página e
+não substituem nem alteram esse campo.
+
+O portal organiza a descoberta; não é uma fronteira de autorização. Só envie ao navegador fontes
+que a pessoa possa consultar, inclusive aquelas disponíveis por URL direta.
+
+A adaptação do cabeçalho, da leitura editorial e dos catálogos à largura da tela é uma exceção
+restrita ao portal documental. A UI das aplicações e os componentes dos exemplos vivos preservam
+o contrato desktop a partir de `64rem`. O aplicativo organiza a moldura do portal em telas estreitas;
+`DocBrowser` não muda sozinho a orientação de `Split` nem transforma os exemplos em layouts móveis.
+
+## Consulte decisões e entregas
+
+ADRs e changelog mantêm o mapa dos guias, sem acrescentar uma árvore para cada registro. Use `sidebarLinks` para oferecer entradas
+no mesmo nível dos grupos, após os capítulos, sem incluí-las na sequência anterior/próxima.
+`DocCatalog` recebe registros derivados dos Markdown e uma consulta local independente do cabeçalho.
+Passe o catálogo em `content` para preservar a lateral:
+
+```tsx
+import { useEffect, useState } from 'react'
+import { DocBrowser, DocHeader, DocCatalog, DocRecordDetail, releaseRecords, type DocSection } from '@softize/opus/ui/docs/browser'
+import { Input, Markdown, usePathname } from '@softize/opus/ui/react'
+
+export function DocumentationPortal({ source, sections }: {
+  source: string; sections: DocSection[]
+}) {
+  const path = usePathname()
+  const [documentationQuery, setDocumentationQuery] = useState('')
+  const [catalogQuery, setCatalogQuery] = useState('')
+  const isChangelog = path === '/changelog' || path.startsWith('/changelog/')
+  const records = releaseRecords(source, '/changelog')
+  const record = records.find((entry) => entry.href === path)
+  useEffect(() => {
+    if (!isChangelog) setCatalogQuery('')
+  }, [isChangelog])
+  return <div className="flex h-dvh flex-col">
+    <DocHeader brand={<a href="/docs">Meu produto</a>}
+      search={<Input type="search" aria-label="Buscar na documentação"
+        value={documentationQuery} onChange={(event) => setDocumentationQuery(event.target.value)} />} />
+    <main className="min-h-0 flex-1">
+    <DocBrowser sections={sections} sidebarInitiallyCollapsed
+    search={{ placement: 'external', value: documentationQuery }}
+    sidebarLinks={[{ label: 'Changelog', href: '/changelog', active: isChangelog }]}
+    content={isChangelog ? (
+      record ? <DocRecordDetail catalogLabel="Changelog"><Markdown content={record.body} /></DocRecordDetail>
+      : path === '/changelog' ? <DocCatalog title="Changelog" description="Mudanças por versão."
+          kind="releases" records={records} query={catalogQuery} onQueryChange={setCatalogQuery} />
+      : <DocRecordDetail catalogLabel="Changelog"><Markdown content="# Registro não encontrado" /></DocRecordDetail>
+    ) : undefined} />
+    </main>
+  </div>
+}
+```
+
+O catálogo oferece busca textual sobre o conteúdo completo e apresenta os registros mais recentes
+primeiro, sem tabela, filtros, controles de ordenação ou paginação. Decisões mostram título, data,
+estado declarado e o primeiro parágrafo do contexto. Changelog retoma a leitura das versões com
+texto integral e cuidados de atualização em destaque.
+
+Não faz chamadas de rede: o aplicativo fornece os arquivos descobertos no build. Esse
+índice estático não substitui `ActionList` em coleções de recursos servidas por uma action.
+A consulta local pesquisa somente os registros; a busca do cabeçalho continua alimentando a árvore.
+O host controla os dois valores separadamente. Preserve a consulta local ao abrir um registro e
+voltar, e limpe-a ao trocar de catálogo; não limpe a consulta documental pela navegação.
+
+`decisionRecord(source, href)` extrai número, título, data e status declarados no cabeçalho de uma
+ADR. A lista apresenta o estado declarado; ressalvas e andamento continuam no texto integral.
+Ausência de data ou status aparece como não informada; títulos que não identificam uma ADR
+não geram registros. `releaseRecords(source, basePath)` preserva a convenção `## versão — data` do
+changelog e suas instruções de incompatibilidade. Histórico dentro de uma versão não vira uma
+release inventada.
+
+`content`, `breaking` e `afterBreaking` preservam a sequência da versão no resumo: texto inicial,
+cuidados de atualização e seções seguintes. O detalhe usa `body`, com o Markdown integral.
+
+O aplicativo resolve a URL do registro e passa seu conteúdo para `DocRecordDetail`, também no
+slot `content`. O registro mostra `catalogLabel` antes do título, sem breadcrumb. A navegação fica
+na lateral; `active` identifica o catálogo aberto. Preserve a mesma instância de `DocBrowser`
+entre guias, catálogo e registro para manter os ramos abertos pela pessoa.
+
+Quando recebe `content`, o navegador não escolhe uma página dos guias, não aplica seus redirects
+e não atualiza o título da aba. O aplicativo resolve a rota e o título desse conteúdo. O catálogo
+não define as rotas nem a autorização do aplicativo.
+
+## Propriedades de DocHeader
+
+| Propriedade | Tipo | Padrão | Uso |
+| --- | --- | --- | --- |
+| `brand` | `ReactNode` | Obrigatória | Marca ou link de entrada. |
+| `navigation` | `ReactNode` | — | Navegação opcional; sem ela, não há segunda linha de abas. |
+| `search` | `ReactNode` | — | Campo de busca controlado pelo aplicativo. |
+| `actions` | `ReactNode` | — | Controles como tema e repositório. |
+| `brandWidth` | `string` | `17rem` | Coluna da marca, normalmente igual à lateral. |
+| `className`, `style` e atributos de `header` | Atributos HTML | — | Identificação e ajustes locais sem substituir a composição. |
+
+## Propriedades de DocBrowser
+
+| Propriedade | Tipo | Padrão | Uso |
+| --- | --- | --- | --- |
+| `sections` | `DocSection[]` | Obrigatória na entrada leve | Seções, grupos e páginas na ordem de leitura. |
+| `basePath` | `string` | `/docs` | Prefixo das rotas. |
+| `path` | `string` | Rota compartilhada | Caminho controlado por um host externo. |
+| `redirects` | `Record<string, string>` | `{}` | Slugs anteriores e seus destinos canônicos. |
+| `documentTitle` | `(title: string) => string` | — | Título da aba a partir da página ativa. |
+| `search` | `boolean` ou `DocBrowserSearchOptions` | `false` | Busca lateral ou valor externo; consulta título, rótulo, badge e `searchText`. |
+| `sidebarSize` | `PaneSize` | `14rem` | Largura inicial da navegação. |
+| `sidebar` | `boolean` | `true` | Exibe a árvore; `false` mantém uma leitura simples sem lateral. |
+| `editorial` | `boolean` | `false` | Contexto, sumário e sequência, quando a lateral está presente. |
+| `navigationLabel` | `string` | `Documentação` | Nome da área no contexto editorial; por exemplo, `UI` para o catálogo de componentes. |
+| `additionalPages` | `DocEntry[]` | `[]` | Destinos diretos fora da árvore e da sequência. |
+| `content` | `ReactNode` | — | Conteúdo do host no lugar da página documental, mantendo a lateral. O host resolve rota e título; `null` deixa a leitura vazia. |
+| `sidebarLinks` | `{ label: string; href: string; active?: boolean }[]` | `[]` | Destinos globais fora dos capítulos; `active` marca o catálogo atual. |
+| `sidebarInitiallyCollapsed` | `boolean` | `false` | Seções e grupos nomeados começam recolhidos, inclusive em links diretos. A busca revela resultados temporariamente sem alterar os ramos abertos pela pessoa. |
+
+A entrada histórica `@softize/opus/ui/docs` inclui o catálogo e oferece suas páginas quando
+`sections` é omitida. Para conteúdo próprio, prefira a entrada leve do exemplo.
+
+`DocBrowserSearchOptions` é exportado pelas duas entradas documentais. Com `placement: 'sidebar'`
+(ou sem `placement`), o navegador mantém a consulta local. Com `placement: 'external'`, `value`
+é obrigatório e o host fornece o campo. Nos dois modos, `label`, `placeholder` e `emptyMessage`
+são opcionais; os dois primeiros só afetam o campo lateral.
+
+## Propriedades de DocCatalog
+
+| Propriedade | Tipo | Padrão | Uso |
+| --- | --- | --- | --- |
+| `title` | `string` | Obrigatória | Título do catálogo. |
+| `description` | `string` | Obrigatória | Contexto para a consulta. |
+| `records` | `readonly DocumentationRecord[]` | Obrigatória | Índice estático com identidade, título, URL, corpo e texto pesquisável. Data, status, `summary`, `content`, `breaking` e `afterBreaking` são opcionais: contexto da ADR e partes do resumo da versão. |
+| `query` | `string` | Obrigatória | Valor do campo local, independente da busca documental do topo. |
+| `onQueryChange` | `(query: string) => void` | Obrigatória | Atualiza a consulta controlada pelo host quando a pessoa escreve no campo local. |
+| `kind` | `'decisions' \| 'releases'` | Obrigatória | Lista de decisões com contexto ou leitura contínua das versões. |
+
+## Propriedades de DocRecordDetail
+
+| Propriedade | Tipo | Padrão | Uso |
+| --- | --- | --- | --- |
+| `catalogLabel` | `string` | Obrigatória | Nome do catálogo antes do título, sem breadcrumb. |
+| `children` | `ReactNode` | Obrigatória | Conteúdo completo do registro. |

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

@@ -4,123 +4,165 @@ title: Primeiros passos
 
 # Primeiros passos
 
-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.
+Vamos calcular o preço de uma assinatura a partir do tamanho da equipe. Ao terminar, você terá
+uma operação com entrada validada, um handler no servidor e um teste que confirma a regra.
 
-## O modelo
+Neste exemplo, cada pessoa custa R$ 29 por mês. A consulta é pública, não grava dados e não
+precisa de banco. Isso permite acompanhar o caminho completo de uma action antes de configurar
+um servidor HTTP ou uma interface.
 
-As regras de uma aplicação costumam aparecer em vários lugares: validação, transporte, API,
-formulários e documentação. No Opus, entidades, dicionários 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.
+## Prepare o projeto
 
-## Começar do zero
-
-Para um projeto novo, use `opus create`: ele gera o app com os pré-requisitos do protocolo, da UI e
-do preview já configurados, e os gates passam desde o início.
-
-O Opus e a Base ficam no npm público: a instalação não exige token nem configuração de escopo.
-Crie o projeto e materialize as duas camadas antes dos gates:
+Se você já trabalha em um projeto Opus, siga para o contrato. Para criar um projeto novo, use um
+ambiente com Node.js e pnpm instalados:
 
 ```bash
 pnpm dlx @softize/opus create meu-app
-cd meu-app && git init && pnpm install && pnpm run setup && pnpm test
+cd meu-app
+git init
+pnpm install
+pnpm run setup
+pnpm test
 ```
 
-O comando cria a estrutura inicial e instala a versão estável disponível. Em uma máquina nova,
-se o `dlx` informar que o diretório global de binários não está no `PATH`, execute `pnpm setup`
-e abra outra sessão do terminal. Se o setup encontrar uma seção antiga do pnpm no arquivo de
-inicialização do shell (`ERR_PNPM_BAD_SHELL_SECTION`), `pnpm setup --force` substitui somente
-esse bloco.
+O projeto inclui TypeScript, Vite, React, um domínio de tarefas e os comandos de teste e
+verificação. `setup` materializa as instruções e os artefatos do Opus e da Base usados pelo
+projeto. Para adotar em um aplicativo existente, criar um monorepo ou resolver uma falha de
+instalação, consulte [Instalação](/docs/installation).
+
+## Declare o contrato
+
+O contrato diz o que a operação recebe, o que devolve e quem pode chamá-la. Ele fica em um arquivo
+que cliente e servidor conseguem importar, sem banco, segredo ou driver de servidor.
 
-Durante as primeiras 24 horas de uma release, a quarentena do pnpm pode resolver silenciosamente
-uma versão anterior. Se o CLI responder com “Comando desconhecido”, informe a versão explicitamente
-com `pnpm dlx @softize/opus@<versão> create meu-app` ou desative a quarentena apenas nessa chamada
-com `pnpm --config.minimum-release-age=0 dlx …`. Dentro do projeto, o workspace exclui Opus e Base
-da quarentena para preservar o par validado.
+Crie `src/domains/subscription/actions/quote.contract.ts`:
 
-O app criado inclui:
+```ts
+import { defineContract } from '@softize/opus/core'
+import { z } from 'zod'
+
+export const subscriptionQuoteContract = defineContract({
+  name: 'subscription.quote',
+  kind: 'simple',
+  summary: 'Calcula a mensalidade de uma equipe',
+  description: 'A assinatura custa R$ 29 por pessoa por mês, com pelo menos uma pessoa.',
+  input: z.object({ seats: z.number().int().positive() }),
+  output: z.object({ monthlyTotalInCents: z.number().int().nonnegative() }),
+  effect: 'read',
+  personalData: false,
+  public: true,
+})
+```
 
-- `opus.config.ts` e um domínio de exemplo documentado, sem violações no `opus check`;
-- Vite, React e o tema do Opus sobre Tailwind v4, configurado por CSS;
-- um dev server que respeita a variável `PORT`, para que um orquestrador de preview escolha a
-  porta;
-- `opus.json`, com a versão adotada, e as instruções, skills e hooks gerenciados.
+`seats` aceita somente um inteiro positivo. O valor devolvido usa centavos: três pessoas custam
+`8700`, ou R$ 87. `public: true` permite consultar o preço sem login; quando esse campo é omitido,
+a action exige uma pessoa autenticada.
 
-A Base cuida do método geral de trabalho, da memória e da revisão; o Opus acrescenta o conhecimento
-específico do SDK.
+O nome `subscription.quote` identifica a operação. O `kind: 'simple'` a define como uma chamada
+sem formulário, coleção ou página de detalhe. Os outros tipos estão em
+[Actions e contratos](/docs/actions).
 
-Em um monorepo, crie primeiro a raiz com `--monorepo` e depois cada app dentro dela. O `create`
-detecta o `pnpm-workspace.yaml` e gera só os arquivos do app, sem um workspace aninhado. O que a raiz
-precisa ter, como o glob de packages, `allowBuilds` e as exclusões de quarentena para Opus e Base,
-aparece como aviso, sem alterar os arquivos da raiz:
+## Ligue a regra ao contrato
 
-```bash
-pnpm dlx @softize/opus create meu-cliente --monorepo   # a raiz do workspace
-cd meu-cliente && git init
-pnpm dlx @softize/opus create apps/portal              # o app (modo detectado)
+O handler recebe a entrada validada e calcula a resposta. `bindAction` liga esse código ao
+contrato sem colocar a implementação no módulo que o cliente importa.
+
+Crie `src/domains/subscription/actions/quote.ts`:
+
+```ts
+import { bindAction } from '@softize/opus/core'
+import { subscriptionQuoteContract } from './quote.contract.ts'
+
+export const subscriptionQuote = bindAction(subscriptionQuoteContract, {
+  handler: async (_ctx, input) => ({
+    monthlyTotalInCents: input.seats * 2900,
+  }),
+})
 ```
 
-## Carregar o Opus em um projeto existente
+O contrato permanece compartilhável. O binding fica do lado do servidor, onde também poderão
+entrar banco, integrações e outras dependências da regra.
 
-O `opus.json` registra a versão do Opus adotada pelo app; se ele ainda não existe, o setup o cria.
-`opus setup` roda em cada app e grava o marcador, o inventário de copy e as projeções específicas do
-SDK. `base setup` materializa na raiz do repositório o método geral, a memória, os agentes e a
-revisão. Os componentes vêm de `@softize/opus/ui/react`, e o tema, de um arquivo CSS.
+## Confira o resultado e o limite da entrada
 
-```bash
-# Bootstrap idempotente de um projeto existente.
-pnpm add @softize/opus
-pnpm add -D @softize/base
-pnpm exec opus setup
-pnpm exec base setup
+`runAction` executa a action pela fronteira do contrato. Assim, o teste verifica tanto a conta
+quanto a validação que ocorre antes do handler.
+
+Crie `src/domains/subscription/actions/quote.test.ts`:
+
+```ts
+import { runAction } from '@softize/opus/testing'
+import { expect, it } from 'vitest'
+import { subscriptionQuote } from './quote.ts'
+
+it('calcula a assinatura de três pessoas', async () => {
+  const { output } = await runAction(subscriptionQuote, { seats: 3 })
+  expect(output).toEqual({ monthlyTotalInCents: 8700 })
+})
+
+it('recusa uma equipe sem pessoas', async () => {
+  await expect(runAction(subscriptionQuote, { seats: 0 })).rejects.toMatchObject({
+    code: 'validation.invalid_input',
+  })
+})
 ```
 
-```css
-/* index.css do app — o tema do Opus e os componentes do pacote no scan do Tailwind. */
-@import '@softize/opus/ui/theme.css';
-@source '../node_modules/@softize/opus/src/ui/**/*.{ts,tsx}';
+Execute `pnpm test`. Os dois testes devem passar. Não foi necessário criar um servidor, simular
+login ou configurar banco: o teste usa a operação ligada ao seu handler.
+
+## Inclua a action no domínio
+
+Um domínio reúne as operações e os dados de um assunto do produto. Registre a nova action em
+`src/domains/subscription/index.ts`:
+
+```ts
+import { defineDomain } from '@softize/opus/core'
+import { subscriptionQuote } from './actions/quote.ts'
+
+export const subscriptionDomain = defineDomain({
+  name: 'subscription',
+  description: 'Assinaturas de equipes e cálculo de mensalidade.',
+  actions: { subscriptionQuote },
+})
 ```
 
-## Montar o runtime
+No `opus.config.ts`, importe `subscriptionDomain` e acrescente-o ao array `domains` que já existe.
+Essa lista informa à CLI quais domínios entram no manifest gerado pelo projeto.
 
-No servidor, `createRuntime` reúne as capacidades que o app usa. Cada capacidade, como banco,
-autenticação ou auditoria, é um adapter que pode ser trocado sem alterar o domínio. Os providers da
-interface estão em [Como consumir](/ui/como-consumir).
+Para executar a action no runtime, registre o mesmo domínio. Este trecho pode rodar em um
+arquivo do servidor ou em um teste de integração:
 
 ```ts
 import { createRuntime } from '@softize/opus/core'
-import { jwtAuth } from '@softize/opus/auth/jwt'
-import { kyselyData } from '@softize/opus/data/kysely'
-import { fastifyServer } from '@softize/opus/server/fastify'
-import { pgAudit } from '@softize/opus/audit/pg'
-import { workspaceDomain } from './domains/workspace/index.ts'
-
-const runtime = createRuntime({
-  server: fastifyServer({ app }),
-  data: kyselyData({ db }),       // Kysely e Postgres
-  auth: jwtAuth({ secret: process.env.JWT_SECRET!, mapUser: (p) => ({ id: String(p.sub) }) }),
-  audit: [pgAudit({ pool })],     // trilha de auditoria
-  config: { env, i18n: { defaultLocale: 'pt-BR' } },
+import { subscriptionDomain } from './domains/subscription/index.ts'
+
+const runtime = createRuntime()
+runtime.register([subscriptionDomain])
+
+const result = await runtime.execute('subscription.quote', { seats: 3 }, {
+  user: null,
+  tenantId: null,
+  can: () => false,
 })
 
-// Só o que foi registrado existe para o runtime.
-runtime.register([workspaceDomain])
-await runtime.start()
+if (result.ok) {
+  console.log(result.data) // { monthlyTotalInCents: 8700 }
+}
 ```
 
-Cada capacidade e o registro de domínios estão detalhados em [Runtime & adapters](/docs/runtime).
+O runtime devolve um resultado com `ok` para distinguir sucesso de falha. A consulta continua
+pública mesmo sem usuário. Uma action que não foi registrada não pode ser executada.
+
+## Continue a partir do que você precisa construir
 
-## Antes de alterar o projeto
+Você já declarou, executou e testou uma action. O próximo passo depende de onde a operação será
+usada:
 
-A documentação do próprio repositório descreve o que é específico dele; esta página cobre só o que
-vale para todo projeto Opus.
+- Para publicar a operação por HTTP e acrescentar banco ou autenticação, siga para
+  [Runtime e adapters](/docs/runtime).
+- Para criar um formulário, uma coleção ou um detalhe, veja os tipos em
+  [Actions e contratos](/docs/actions) e os [componentes de UI](/ui/como-consumir).
+- Para cobrir permissões e efeitos da operação, avance para [Testar actions](/docs/testing).
 
-- O `CLAUDE.md` do repositório e de cada app reúne o mapa do código, os gates e os cuidados locais.
-- A `description` de entidades e actions registra a regra de negócio, que `opus gen` projeta no
-  manifest.
-- Antes de entregar, rode `opus check` (convenções das actions e da UI), `opus copy --check` e
-  `base copy check` (inventário e política de copy) e, com banco, `opus db check` (divergência entre
-  entidades e banco).
+Antes de entregar uma mudança, execute `pnpm exec opus check`, `pnpm exec opus copy --check`
+e os gates do seu repositório. Consulte [CLI](/docs/cli) para entender o que cada comando verifica.