@softize/opus 25.5.0 → 25.7.0

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.

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

@@ -0,0 +1,94 @@
+---
+title: Instalação
+---
+
+# Instalação
+
+Use `opus create` para começar um projeto com TypeScript, React, testes e as verificações do
+Opus configurados. Se o aplicativo já existe, instale o pacote e execute o setup para acrescentar
+os artefatos do SDK ao repositório.
+
+Os comandos desta página usam pnpm. Os pacotes Opus e Base são públicos e não exigem token de
+registro.
+
+## Criar um aplicativo
+
+```bash
+pnpm dlx @softize/opus create meu-app
+cd meu-app
+git init
+pnpm install
+pnpm run setup
+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.
+
+Quando os testes passarem, continue em [Primeiros passos](/docs/getting-started).
+
+## Criar um monorepo
+
+Crie a raiz do workspace antes dos aplicativos:
+
+```bash
+pnpm dlx @softize/opus create meu-cliente --monorepo
+cd meu-cliente
+git init
+pnpm dlx @softize/opus create apps/portal
+pnpm install
+pnpm --dir apps/portal run setup
+```
+
+Dentro de um workspace pnpm, `create` gera somente os arquivos do aplicativo. Ele detecta o
+`pnpm-workspace.yaml` da raiz e evita criar um workspace aninhado.
+
+Se a raiz já existir, o comando avisa quando faltar configuração para incluir o app em
+`packages`, permitir o postinstall com `allowBuilds` ou excluir Opus e Base da quarentena de
+versões. Esses avisos não alteram os arquivos da raiz.
+
+## Adotar em um projeto existente
+
+Na pasta do aplicativo, instale o SDK e execute o setup do Opus. Execute o setup da Base na raiz
+do repositório:
+
+```bash
+pnpm add @softize/opus
+pnpm add -D @softize/base
+pnpm exec opus setup
+pnpm exec base setup
+```
+
+Os dois setups são idempotentes. O Opus grava o marcador `opus.json`, o inventário de copy e as
+projeções específicas do SDK. A Base materializa o método geral de trabalho, a memória e os
+agentes. Em um monorepo, cada aplicativo mantém seu próprio marcador e sua configuração Opus.
+
+Para usar a UI em um aplicativo com Tailwind v4, importe o tema e inclua os componentes do
+pacote no scan do Tailwind. Este exemplo considera um CSS dentro de `src/`:
+
+```css
+@import '@softize/opus/ui/theme.css';
+@source '../node_modules/@softize/opus/src/ui/**/*.{ts,tsx}';
+```
+
+Os componentes são importados de `@softize/opus/ui/react`. A configuração dos providers e da
+execução de actions está em [Como consumir](/ui/como-consumir).
+
+## Resolver uma falha antes da criação
+
+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. Quando o setup apontar `ERR_PNPM_BAD_SHELL_SECTION`,
+`pnpm setup --force` substitui o bloco antigo do pnpm no arquivo de inicialização do shell.
+
+Uma política de quarentena do pnpm pode resolver uma versão anterior durante as primeiras
+horas de uma release. Se `create` responder com “Comando desconhecido”, informe a versão que
+você quer usar:
+
+```bash
+pnpm dlx @softize/opus@<versão> create meu-app
+```
+
+Outra opção é desativar a quarentena somente nessa chamada com
+`pnpm --config.minimum-release-age=0 dlx @softize/opus create meu-app`.
+O workspace gerado exclui Opus e Base dessa quarentena para manter o par adotado pelo template.

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

@@ -34,6 +34,45 @@ const sample = [
 render(<Markdown content={sample} />)
 ```
 
+## Documentos navegáveis
+
+Ao apresentar uma pasta de documentação, use `headingIds` para gerar âncoras e `resolveHref` para
+transformar os links internos na rota da aplicação. Os utilitários de
+`@softize/opus/ui/docs/links` mantêm os dois lados na mesma gramática sem decidir a URL final.
+
+```tsx
+import {
+  documentationSlugFromSourcePath,
+  resolveDocumentationLinkTarget,
+} from '@softize/opus/ui/docs/links'
+
+const sourcePath = 'guides/current.md'
+
+<Markdown
+  content={content}
+  headingIds
+  resolveHref={(href) => {
+    const target = resolveDocumentationLinkTarget(sourcePath, href)
+    if (target === null) return href
+    const slug = documentationSlugFromSourcePath(target.sourcePath)
+    return `/docs/project/${slug}${target.anchor === undefined ? '' : `#${target.anchor}`}`
+  }}
+/>
+```
+
+Passe `sourcePath` relativo à raiz documental. Um link absoluto iniciado por `/docs/` volta a essa
+raiz; `docs/` sem a barra inicial continua sendo uma subpasta comum. Protocolos, arquivos que não
+são Markdown e caminhos que escapam da raiz retornam `null`, para a aplicação preservar ou tratar o
+endereço original.
+
+## Referência de links documentais
+
+| Função | Resultado |
+|---|---|
+| `resolveDocumentationLinkTarget(currentSourcePath, href)` | Devolve o caminho `.md` ou `.mdx` relativo à raiz e a âncora normalizada. Decodifica segmentos percentuais válidos e devolve `null` quando o endereço não pertence ao acervo. |
+| `documentationSlugFromSourcePath(sourcePath)` | Remove a extensão e os prefixos numéricos de ordenação de cada segmento. Preserva a hierarquia restante. |
+| `documentationAnchor(fragment)` | Decodifica e normaliza um fragmento URI para comparação com o ID do título. |
+| `documentationHeadingAnchor(text)` | Normaliza o texto visível de um título sem interpretar sequências percentuais como URI. |
 
 ## Propriedades de Markdown
 
@@ -41,3 +80,5 @@ render(<Markdown content={sample} />)
 |---|---|---|---|
 | `content` | `string` | obrigatório | O texto em Markdown (CommonMark e tabelas do GFM, via markdown-it). HTML no texto é escapado, não interpretado, por isso o componente serve para texto escrito por pessoas ou gerado por modelos. Endereços soltos, como `https://…`, viram links. |
 | `className` | `string` | | Classes do contêiner. |
+| `resolveHref` | `(href: string) => string` | | Reescreve cada link antes da validação e da renderização. Use para transformar caminhos documentais em rotas da aplicação. |
+| `headingIds` | `boolean` | `false` | Gera IDs normalizados e únicos nos títulos. Ative em documentos navegáveis; mantenha desativado em mensagens comuns. |

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

@@ -57,8 +57,8 @@ entrada. Em `_meta`, cada tool traz os
 identificadores e `com.softize.opus/data-product-labels`, o nome legível de cada um.
 
 Quando a action declara o que faz com os dados, a tool traz também as anotações padrão do MCP:
-`readOnlyHint` vem de `effect`. Numa action que escreve, `destructiveHint` vai sempre explícito, a
-partir de `ai.destructive`, porque o MCP trata a ausência numa escrita como destrutiva.
+`readOnlyHint` vem de `effect`. Em uma action que escreve, `destructiveHint` vai sempre explícito, a
+partir de `ai.destructive`, porque o MCP trata a ausência em uma escrita como destrutiva.
 Em `_meta`, `com.softize.opus/effect` repete o efeito e `com.softize.opus/personal-data` diz se a
 resposta contém dado pessoal. Na action dona de um tipo de recurso, `com.softize.opus/assistant`
 traz o assistente declarado, para o host conhecê-lo pelo catálogo que já consulta e aplicar à saída