@softize/opus 25.6.0 → 25.7.0

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/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

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

@@ -0,0 +1,58 @@
+---
+title: Visão geral
+---
+
+# Opus
+
+Opus é um SDK para aplicações TypeScript. Você declara as operações do produto em contratos
+compartilhados, liga a implementação no servidor e usa essas mesmas definições no cliente,
+nos testes e nas ferramentas do projeto.
+
+Uma consulta de mensalidade, por exemplo, recebe o tamanho da equipe e devolve o preço. O
+contrato define o formato dessas duas informações e permite o acesso sem login. O handler
+calcula o valor. A interface importa o contrato para chamar a operação com os mesmos tipos
+e validações usados no servidor.
+
+## O que você precisa entender primeiro
+
+Uma **action** é uma operação do sistema: consultar um preço, listar tarefas, salvar um cadastro
+ou ler um registro. Cada action tem um nome, uma entrada e uma saída.
+
+O **contrato** é a parte compartilhada da action. Ele declara o formato dos dados e as informações
+que seus consumidores precisam conhecer. O **binding** acrescenta o handler que executa a regra
+no servidor. Essa divisão permite importar o contrato na interface sem levar banco ou segredo
+para o navegador.
+
+O **domínio** agrupa actions e dados de um assunto do produto. O **runtime** executa o que foi
+registrado e oferece as dependências configuradas pelo aplicativo, como autenticação, banco ou
+auditoria. Essas dependências entram por adapters; você escolhe as peças necessárias ao projeto.
+
+```text
+Contrato compartilhado ──→ Cliente e interface
+         │
+         └── + handler ──→ Action registrada no runtime
+```
+
+Você escreve a regra de negócio e monta o aplicativo. O Opus fornece as declarações, a execução,
+os componentes de interface e as verificações que trabalham sobre essas declarações.
+
+## Faça uma primeira operação
+
+Em [Primeiros passos](/docs/getting-started), você calcula uma mensalidade, valida a entrada e
+testa o resultado. O exemplo usa uma regra pequena e dispensa banco, servidor HTTP e login.
+
+Depois desse percurso, [Actions e contratos](/docs/actions) explica como a mesma estrutura atende
+a formulários, listas, detalhes e operações com autorização.
+
+## Continue o trabalho que trouxe você até aqui
+
+| Você precisa… | Comece por… |
+| --- | --- |
+| Criar uma operação ou mudar uma regra | [Actions e contratos](/docs/actions) |
+| Publicar uma API e conectar dependências | [Runtime e adapters](/docs/runtime) |
+| Modelar dados persistidos | [Camada de dados](/docs/data) |
+| Construir uma tela | [Como consumir](/ui/como-consumir) |
+| Testar uma operação e suas permissões | [Testes de actions](/docs/testing) |
+| Atualizar a versão usada no projeto | [Atualização do Opus](/docs/upgrading) |
+
+O catálogo de [UI](/ui) tem navegação própria pelo volume de componentes e exemplos visuais.

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

@@ -69,6 +69,10 @@ render(
 Use `SidebarNav` quando grupos e itens já puderem ser descritos como dados. Use `SidebarItem`
 diretamente quando a composição precisar de controles, badges ou hierarquia particular.
 
+`SidebarItem` aceita `href` para destinos nativos, mantendo foco e abertura em outra aba.
+Quando o host usa um roteador, forneça também `onClick`: somente o clique simples é interceptado;
+cliques com modificadores preservam o comportamento do link. Sem `href`, o item continua sendo um botão.
+
 ## Colapso
 
 `collapsed` informa o estado compacto aos itens. Forneça labels acessíveis mesmo quando somente os

package/src/ui/docs/index.ts

@@ -7,7 +7,14 @@
  *    `@softize/opus/ui/docs/standalone` — não passa por aqui.
  */
 export { DocBrowser } from './CatalogDocBrowser.tsx'
+export { DocHeader } from './DocHeader.tsx'
+export { DocCatalog, DocRecordDetail } from './DocCatalog.tsx'
+export type { DocCatalogProps, DocRecordDetailProps } from './DocCatalog.tsx'
+export { decisionRecord, releaseRecords, parseChangelog, filterDocumentationRecords } from './records.ts'
+export type { DocumentationRecord } from './records.ts'
+export type { DocHeaderProps } from './DocHeader.tsx'
 export type { DocBrowserProps } from './CatalogDocBrowser.tsx'
+export type { DocBrowserSearchOptions } from './DocBrowser.tsx'
 export { DOC_SECTIONS, PROTOCOL_SECTIONS, UI_SECTIONS } from './registry.tsx'
 export type { DocEntry, DocGroup, DocSection } from './types.ts'
 export { docSectionsFromFolder } from './catalog-folder.tsx'
@@ -17,5 +24,5 @@ export { Example, CodeBlock, DocPage } from './doc.tsx'
 // Renderer de markdown do DocBrowser: prosa + fence ```tsx preview vira componente vivo.
 export { DocMarkdown } from './markdown.tsx'
 export type { DocMarkdownProps } from './markdown.tsx'
-// O changelog do pacote, pronto pra montar (o site o usa como página do menu superior).
+// O changelog do pacote, pronto para montar em um destino global ou no catálogo embutido.
 export { OpusChangelog, ChangelogView } from './changelog.tsx'

package/src/ui/docs/markdown.tsx

@@ -88,9 +88,11 @@ export interface DocMarkdownProps {
   /** Reescreve links do Markdown antes da renderização. Útil para resolver caminhos relativos
    *  quando o documento é publicado sob uma rota do aplicativo. */
   resolveHref?: (href: string) => string
+  /** Mantém código didático aberto quando false; exemplos vivos preservam sua composição. */
+  codeCollapsible?: boolean
 }
 
-export function DocMarkdown({ content, scope, resolveHref }: DocMarkdownProps): React.ReactElement {
+export function DocMarkdown({ content, scope, resolveHref, codeCollapsible = true }: DocMarkdownProps): React.ReactElement {
   // O `scope` ESTENDE o default (não substitui): o pattern injeta o palco doc-client
   // (DocBrowserActionProvider + contratos) sem perder o opus/ui + lucide + hooks. Memoiza pra
   // não re-avaliar os LiveBlocks a cada render (o scope injetado é estável no chamador).
@@ -135,7 +137,7 @@ export function DocMarkdown({ content, scope, resolveHref }: DocMarkdownProps):
           {/\b(preview|live)\b/.test(info) ? (
             <LiveBlock code={t.content} scope={liveScope} previewClassName={previewClassName} />
           ) : (
-            <CodeBlock code={t.content.replace(/\n$/, '')} lang={lang} />
+            <CodeBlock code={t.content.replace(/\n$/, '')} lang={lang} collapsible={codeCollapsible} />
           )}
         </div>,
       )
@@ -144,5 +146,5 @@ export function DocMarkdown({ content, scope, resolveHref }: DocMarkdownProps):
     }
   }
   flush()
-  return <div className="prose prose-sm max-w-none space-y-4">{parts}</div>
+  return <div data-slot="markdown" className="prose prose-sm max-w-none space-y-4">{parts}</div>
 }

package/src/ui/docs/records.ts

@@ -0,0 +1,144 @@
+export interface DocumentationRecord {
+  id: string;
+  title: string;
+  href: string;
+  date?: string;
+  status?: string;
+  searchText: string;
+  body: string;
+  summary?: string;
+  content?: string;
+  breaking?: string;
+  afterBreaking?: string;
+}
+
+export interface ChangelogVersion {
+  version: string;
+  date?: string;
+  body: string;
+  breaking?: string;
+  beforeBreaking?: string;
+  afterBreaking?: string;
+  /** Corpo original, com a ordem das seções preservada para a leitura integral. */
+  sourceBody?: string;
+}
+
+export interface ParsedChangelog {
+  intro: string;
+  versions: ChangelogVersion[];
+}
+
+/** Preserva a convenção publicada: `## versão — data` e seção `### Breaking`. */
+export function parseChangelog(source: string): ParsedChangelog {
+  const chunks = `\n${source.trim()}`.split(/\n## /);
+  const versions = chunks.slice(1).map((chunk) => {
+    const nl = chunk.indexOf("\n");
+    const header = (nl === -1 ? chunk : chunk.slice(0, nl)).trim();
+    const rest = nl === -1 ? "" : chunk.slice(nl + 1);
+    const [version, date] = header.split(/\s+—\s+/);
+    const sourceBody = rest.trim();
+    const breakingSection =
+      /^### Breaking[\t ]*\r?\n([\s\S]*?)(?=^###[\t ]|(?![\s\S]))/m.exec(sourceBody);
+    const body = breakingSection
+      ? sourceBody.slice(0, breakingSection.index) +
+        sourceBody.slice(breakingSection.index + breakingSection[0].length)
+      : sourceBody;
+    return {
+      version: (version ?? header).trim(),
+      ...(date !== undefined ? { date: date.trim() } : {}),
+      body: (body ?? "").trim(),
+      sourceBody,
+      ...(breakingSection
+        ? {
+            breaking: breakingSection[1]!.trim(),
+            beforeBreaking: sourceBody.slice(0, breakingSection.index).trim(),
+            afterBreaking: sourceBody
+              .slice(breakingSection.index + breakingSection[0].length)
+              .trim(),
+          }
+        : {}),
+    };
+  });
+  return { intro: chunks[0]?.trim() ?? "", versions };
+}
+
+/** Extrai só os campos declarados; a ausência de metadata não vira uma decisão presumida. */
+export function decisionRecord(
+  source: string,
+  href: string,
+): DocumentationRecord | undefined {
+  const heading = source.match(/^#\s+ADR\s+(\d+)\s*[—–:-]\s*(.+)$/m);
+  if (!heading) return undefined;
+  const header = source.split(/^##\s/m)[0] ?? "";
+  const metadata = (name: string): string | undefined => {
+    const value = header.match(
+      new RegExp(`^[\\t ]*-?[\\t ]*\\*\\*${name}:?\\*\\*:?[\\t ]*(.+)$`, "mi"),
+    )?.[1];
+    return value?.trim().replace(/\.$/, "");
+  };
+  const declaredStatus = metadata("Status");
+  // O estado resume a metadata; ressalvas e andamento permanecem no texto integral da decisão.
+  const status =
+    declaredStatus?.match(
+      /^(parcialmente (?:substituída|supersedida)|substituída|supersedida|aceita(?: para (?:protótipo|implementação(?: local)?|candidato local)| como primeiro corte)?|proposta|implementada|rejeitada)\b/i,
+    )?.[1] ?? declaredStatus;
+  const context = source
+    .match(/^##[\t ]+Contexto\b[^\n]*\n([\s\S]*)/im)?.[1]
+    ?.split(/^##[\t ]/m)[0];
+  return {
+    id: heading[1]!,
+    title: heading[2]!.trim(),
+    href,
+    date: metadata("Data"),
+    status,
+    summary:
+      context
+        ?.replace(/^#{1,6}[\t ].*(?:\r?\n|$)/gm, "")
+        .trim()
+        .split(/\n\s*\n/)[0]
+        ?.trim() || undefined,
+    searchText: source,
+    body: source,
+  };
+}
+
+export function releaseRecords(
+  source: string,
+  basePath: string,
+): DocumentationRecord[] {
+  return parseChangelog(source).versions.map((release) => {
+    return {
+      id: release.version,
+      title: release.version,
+      href: `${basePath}/${encodeURIComponent(release.version)}`,
+      date: release.date,
+      content: release.beforeBreaking ?? release.body,
+      breaking: release.breaking,
+      afterBreaking: release.afterBreaking,
+      body: `# ${release.version}\n\n${release.date ?? ""}\n\n${release.sourceBody}`,
+      searchText: `${release.version} ${release.date ?? ""} ${release.sourceBody}`,
+    };
+  });
+}
+
+function searchable(value: string): string {
+  return value
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLocaleLowerCase("pt-BR");
+}
+
+export function filterDocumentationRecords(
+  records: readonly DocumentationRecord[],
+  query: string,
+): DocumentationRecord[] {
+  const terms = searchable(query).trim().split(/\s+/).filter(Boolean);
+  return records.filter(
+    (record) =>
+      terms.every((term) =>
+        searchable(
+          `${record.id} ${record.title} ${record.status ?? ""} ${record.searchText}`,
+        ).includes(term),
+      ),
+  );
+}