@softize/opus 8.6.6

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

@@ -0,0 +1,86 @@
+## Horizontal
+
+ResizablePanelGroup envolve os painéis e o ResizableHandle entre eles. O grupo ocupa a altura do pai (h-full), então dê um tamanho ao container.
+
+```tsx preview col
+<div className="h-48 rounded-md border">
+  <ResizablePanelGroup orientation="horizontal">
+    <ResizablePanel defaultSize={35}>
+      <div className="flex h-full items-center justify-center p-4 text-sm">
+        Árvore do repositório
+      </div>
+    </ResizablePanel>
+    <ResizableHandle />
+    <ResizablePanel defaultSize={65}>
+      <div className="flex h-full items-center justify-center p-4 text-sm">
+        Diff da sessão
+      </div>
+    </ResizablePanel>
+  </ResizablePanelGroup>
+</div>
+```
+
+## Com alça visível
+
+withHandle no ResizableHandle desenha a pega central — facilita acertar o arraste quando a divisória precisa ficar óbvia.
+
+```tsx preview col
+<div className="h-48 rounded-md border">
+  <ResizablePanelGroup orientation="horizontal">
+    <ResizablePanel defaultSize={40} minSize={20}>
+      <div className="flex h-full items-center justify-center p-4 text-sm">
+        Painel do agente developer
+      </div>
+    </ResizablePanel>
+    <ResizableHandle withHandle />
+    <ResizablePanel defaultSize={60} minSize={20}>
+      <div className="flex h-full items-center justify-center p-4 text-sm">
+        Preview do worktree
+      </div>
+    </ResizablePanel>
+  </ResizablePanelGroup>
+</div>
+```
+
+## Aninhado
+
+Um ResizablePanelGroup dentro de um painel cruza as direções: orientation=vertical empilha os painéis e a alça vira horizontal.
+
+```tsx preview col
+<div className="h-64 rounded-md border">
+  <ResizablePanelGroup orientation="horizontal">
+    <ResizablePanel defaultSize={30}>
+      <div className="flex h-full items-center justify-center p-4 text-sm">
+        Workspace Empresa X
+      </div>
+    </ResizablePanel>
+    <ResizableHandle withHandle />
+    <ResizablePanel defaultSize={70}>
+      <ResizablePanelGroup orientation="vertical">
+        <ResizablePanel defaultSize={60}>
+          <div className="flex h-full items-center justify-center p-4 text-sm">
+            Chat do reviewer
+          </div>
+        </ResizablePanel>
+        <ResizableHandle withHandle />
+        <ResizablePanel defaultSize={40}>
+          <div className="flex h-full items-center justify-center p-4 text-sm">
+            Saída do opus check
+          </div>
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </ResizablePanel>
+  </ResizablePanelGroup>
+</div>
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `orientation (ResizablePanelGroup)` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção do arraste — horizontal vira colunas, vertical empilha em linhas. |
+| `defaultSize (ResizablePanel)` | `number \| string` | | Tamanho inicial do painel, em porcentagem do grupo. |
+| `minSize (ResizablePanel)` | `number \| string` | | Tamanho mínimo até onde o painel encolhe no arraste. |
+| `maxSize (ResizablePanel)` | `number \| string` | | Tamanho máximo até onde o painel cresce no arraste. |
+| `collapsible (ResizablePanel)` | `boolean` | `false` | Deixa o painel colapsar ao ser arrastado abaixo do minSize. |
+| `withHandle (ResizableHandle)` | `boolean` | `false` | Desenha a pega central na divisória — torna o ponto de arraste visível. |

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

@@ -0,0 +1,56 @@
+## O pathname É o estado
+
+Roteamento history-based, sem dependência: `pushState` + `popstate` + `useSyncExternalStore`. Páginas orientadas a URL — deep-link, reload e o botão voltar funcionam de graça, porque não há um segundo lugar guardando "onde estou".
+
+```tsx
+import { navigate, useSegments } from '@softize/opus/ui/react'
+
+function App() {
+  const segments = useSegments()        // '/settings/users' → ['settings','users']
+  if (segments[0] === 'settings') return <Settings />
+  return <Home />
+}
+```
+
+## O escopo é pequeno de propósito
+
+Não há tabela de rotas, `<Route>`, params tipados nem carregamento de dados. Isto é a **leitura reativa da URL + um `navigate`** — quem decide o que renderizar é o app, com `if`/`switch` sobre os segmentos.
+
+A régua: se a sua tela precisa de casamento de padrão (`/users/:id/posts/:postId`), params tipados ou data loaders, o caso pede uma biblioteca de rotas, não isto. Um app de back-office com uma dúzia de destinos quase nunca precisa.
+
+## As quatro peças
+
+| | |
+|---|---|
+| `usePathname()` | O pathname como estado reativo. |
+| `useSegments()` | Os segmentos, já sem os vazios: `/settings/users` → `['settings','users']`. |
+| `useSearchParams()` | A querystring reativa — o lar natural do estado interno de uma seção (qual relatório está aberto, o recorte de uma lista). |
+| `navigate(path, opts?)` | `pushState` + notifica. `{ replace: true }` troca a entrada corrente. |
+
+## Dois detalhes que custaram caro nas cópias à mão
+
+**Destino igual é no-op.** `navigate` resolve o destino com `new URL` e compara o `href` inteiro — não faz nada se você já está exatamente lá. Sem isso, clicar duas vezes no mesmo item do menu empilha entradas idênticas e o botão "voltar" não sai do lugar.
+
+Comparar strings cruas parece bastar e não basta, em duas frentes. O **hash**: estando em `/a#secao`, `navigate('/a')` pareceria destino repetido e a âncora nunca sairia da URL. E o **encoding**: `window.location` devolve `/relatórios` como `/relat%C3%B3rios`, então a comparação crua nunca casa e cada clique empilha — bem no caso pt-BR, e no ``navigate(`/reports?report=${arquivo}`)`` com nome de arquivo acentuado.
+
+**A notificação é um evento, não uma lista.** `pushState` não dispara `popstate`, então `navigate` dispara — e é `window.dispatchEvent`, não um `Set` de assinantes em escopo de módulo. A diferença aparece nas bordas: código que ainda escuta `popstate` na unha continua acompanhando, e duas cópias do pacote no `node_modules` continuam se enxergando. Uma lista privada mora numa instância do bundle; o `window` é um só.
+
+**`useSyncExternalStore`, não `useState`.** Ler `window.location` dentro de `useState`/`useEffect` sofre *tearing* no modo concurrent: dois componentes podem renderizar o mesmo commit com URLs diferentes. As cópias que este módulo substituiu faziam isso.
+
+## `replace`: quando o passo não é história
+
+```tsx
+navigate(`/reports?report=${file}`, { replace: true })
+```
+
+Use quando a mudança não merece uma volta do botão "voltar" — um rascunho que ganha id no meio do fluxo, um filtro que a pessoa ajusta várias vezes seguidas. O default (`pushState`) é o certo para navegação de verdade.
+
+## SSR
+
+Os hooks têm snapshot de servidor constante (`/` e busca vazia): renderizam sem `window` e reconciliam com a URL real no primeiro render do cliente. Se a sua página precisa do path correto **no HTML servido**, isto não resolve — aí o path tem que vir do framework, por prop.
+
+O `navigate` **não** tem essa cortesia: ele toca `window` direto e estoura no servidor. É de propósito — ler a URL sem browser tem resposta razoável, navegar não tem, e engolir a chamada em silêncio esconderia o erro de uso.
+
+## Destino externo não é problema daqui
+
+`navigate` espera um caminho da própria origem. Validar destino que veio de terceiro — o `?redirect=` de um pós-login, por exemplo — é responsabilidade de quem recebe esse input, e a checagem certa é resolver com `new URL(valor, origin)` e comparar `origin`, não olhar prefixo.

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

@@ -0,0 +1,77 @@
+---
+title: Runtime & adapters
+---
+
+# Runtime & adapters
+
+O Opus não é framework — é **protocolo + SDK**: você compõe o runtime a partir de
+adapters plugáveis, e cada capacidade é opcional. O litmus é a inversão de controle:
+o runtime não toma o seu app; o seu app monta o runtime com as peças que quer.
+
+## O modelo
+
+> Todo adapter implementa `name`/`kind`; `init`/`dispose`/`healthCheck` são opcionais e
+> entram no ciclo de vida do runtime (start inicializa, dispose desliga em ordem reversa,
+> healthCheck agrega).
+
+```ts
+import { createRuntime } from '@softize/opus/core'
+
+const runtime = createRuntime({
+  server: fastifyServer({ app }),      // monta as actions como endpoints
+  data: kyselyData({ db }),            // fornece ctx.db
+  auth: makeAuthAdapter(),             // resolve user/tenant/can
+  audit: [pgAudit({ pool })],          // trilha de auditoria (N sinks)
+  storage: fsStorage({ root }),        // fornece ctx.storage (experimental)
+  config: { env, i18n: { defaultLocale: 'pt-BR' } },
+})
+
+runtime.register([dealsDomain, billingDomain]) // não registrado = não existe
+await runtime.start()
+```
+
+## As capacidades
+
+> Um subpath por driver; quem não usa, não instala (peers opcionais onde há dependência
+> pesada). A tabela é o mapa — cada linha é um recurso do protocolo.
+
+| Capacidade | Fornece | Driver pronto |
+|---|---|---|
+| `server` | monta as actions (HTTP) | `fastifyServer` — `@softize/opus/server/fastify` |
+| `data` | `ctx.db` + drift-check + CRUD | `kyselyData`, `kyselyRepo`, `crudActions` — `@softize/opus/data/kysely` |
+| `auth` | `user`/`tenantId`/`can` do contexto | `jwtAuth` — `…/auth/jwt` · `betterAuthSession` — `…/auth/better-auth` |
+| `audit` | trilha por execução de action | `pgAudit` — `…/audit/pg` · `consoleAudit` — `…/audit/console` |
+| `log` | `ctx.log` estruturado | `pinoLogger` — `@softize/opus/log/pino` |
+| `eventBus` | `ctx.emit` + **reactions** | `mittEvents` — `@softize/opus/events/mitt` |
+| `queue` | jobs em background | `bullmqQueue` — `@softize/opus/queue/bullmq` |
+| `scheduler` | **schedules** (cron/intervalo) | `nodeCronScheduler` — `@softize/opus/scheduler/node-cron` |
+| `storage` | `ctx.storage` (arquivos) | `fsStorage` — `…/storage/fs` · `s3Storage` — `…/storage/s3` |
+| `ai` | `ctx.ai` (complete/extract) | `anthropicAi` — `@softize/opus/ai/anthropic` |
+| `client` | chamar actions de fora (stubs) | `fetchClient` — `@softize/opus/client/fetch` |
+
+Fora do runtime, mas parte do protocolo: o harness de teste (`runAction`/`testContext`
+— `@softize/opus/testing`) roda uma action em unidade com o mesmo pipeline do
+`execute`. Ver **Testes de action**.
+
+## O contexto do handler
+
+> O `ctx` é a soma do que os adapters fornecem — sem adapter, o campo é `null`/`unknown`
+> e o handler decide como degradar.
+
+`user`/`tenantId`/`can` (auth) · `db` (data) · `log` (logger) · `emit` (eventBus) ·
+`storage` (storage) · `ai` (ai) · `provenance` (quem disparou: http, schedule,
+reaction…) · `meta`.
+
+## Reactions e schedules
+
+> Os dois jeitos de código rodar SEM request: evento de domínio dispara reaction;
+> tempo dispara schedule (que executa uma action, com provenance própria).
+
+Declarados como as actions e registrados no mesmo `runtime.register` — o manifest
+projeta os três (o Maestro mostra o wiring em Visão geral).
+
+## Referência profunda
+
+O contrato completo (tipos, garantias, ordem de execução, erros) vive no
+`docs/protocol.md` **dentro do pacote** — como o changelog, viaja com a versão
+que você instalou.

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

@@ -0,0 +1,66 @@
+---
+title: Agendador
+---
+
+# Agendador
+
+Rodar uma action no tempo — cron ou intervalo. Você declara o schedule (qual action, quando)
+e o runtime dispara na hora, com provenance `schedule` (rastreável no audit como qualquer
+execução). O contrato é o `SchedulerAdapter`.
+
+## O contrato
+
+```ts
+interface SchedulerAdapter {
+  register(spec: ScheduleDef, fire: () => Promise<void> | void): Unsubscribe
+}
+
+interface ScheduleDef {
+  name: string
+  action: string              // action do registry, executada quando dispara
+  cron?: string               // '0 9 * * *' (9h todo dia)
+  every?: string              // '1h', '30m', '15s' — atalho de intervalo
+  timezone?: string           // IANA, ex.: 'America/Sao_Paulo' (default UTC)
+  input?: unknown | (() => unknown | Promise<unknown>)   // estático ou dinâmico
+  enabled?: boolean
+}
+```
+
+O timing é exclusivo: `cron` **ou** `every`. A action referenciada tem que existir no
+registry.
+
+## Driver
+
+```ts
+import { nodeCronScheduler } from '@softize/opus/scheduler/node-cron'
+
+const scheduler = nodeCronScheduler()   // in-process
+```
+
+## No runtime
+
+```ts
+import { defineSchedule } from '@softize/opus/core'
+
+// Declarado no domínio, junto das actions:
+const fecharDia = defineSchedule({
+  name: 'fechar-dia',
+  action: 'caixa.fechar',
+  cron: '0 23 * * *',
+  timezone: 'America/Sao_Paulo',
+})
+
+const runtime = createRuntime({
+  // …server/data…
+  scheduler,
+})
+```
+
+O runtime registra os schedules do domínio no `start()` e chama a action quando o tempo bate
+— nada de disparar no handler.
+
+## Limites (por enquanto)
+
+Driver hoje: `node-cron` (in-process — some se o processo cair; num cluster, cada nó
+dispararia). Backends duráveis/distribuídos (BullMQ repeatable, Temporal…) entram por
+reincidência.

package/src/ui/docs/content/scroll-area.md

@@ -0,0 +1,89 @@
+## Lista de altura fixa
+
+Dê a altura ao ScrollArea (h-48) e ponha o conteúdo dentro — a barra vertical já vem por padrão, sem precisar de ScrollBar.
+
+```tsx preview col
+const sessions = [
+  { id: 'empresa-x-1842', title: 'Migrar billing pro novo schema', agent: 'developer' },
+  { id: 'empresa-x-1839', title: 'Revisar handoff do checkout', agent: 'reviewer' },
+  { id: 'empresa-x-1835', title: 'Redesenhar o painel de rotas', agent: 'designer' },
+  { id: 'empresa-x-1830', title: 'Corrigir flaky no teste de webhook', agent: 'developer' },
+  { id: 'empresa-x-1827', title: 'Vincular skill clean-code ao agente', agent: 'reviewer' },
+  { id: 'empresa-x-1821', title: 'Subir preview do worktree', agent: 'developer' },
+  { id: 'empresa-x-1818', title: 'Ajustar copy do empty state', agent: 'designer' },
+  { id: 'empresa-x-1814', title: 'Rodar opus check no monorepo', agent: 'reviewer' },
+]
+
+render(
+  <ScrollArea className="h-48 w-full rounded-md border border-border">
+    <div className="p-3">
+      {sessions.map((s) => (
+        <div key={s.id} className="rounded-md px-2 py-1.5 text-sm hover:bg-muted">
+          <p className="font-medium">{s.title}</p>
+          <p className="text-xs text-muted-foreground">{s.id} · {s.agent}</p>
+        </div>
+      ))}
+    </div>
+  </ScrollArea>,
+)
+```
+
+## Trilho horizontal
+
+Pra rolar na horizontal, acrescente <ScrollBar orientation="horizontal" /> como filho e deixe o conteúdo numa linha que não quebra (flex + w-max).
+
+```tsx preview col
+const skills = ['clean-code', 'code-style', 'ddd', 'test', 'create-action', 'opus', 'clean-architecture']
+
+render(
+  <ScrollArea className="w-full rounded-md border border-border whitespace-nowrap">
+    <div className="flex w-max gap-2 p-3">
+      {skills.map((skill) => (
+        <span key={skill} className="rounded-md border border-border bg-muted px-3 py-1.5 text-sm">
+          {skill}
+        </span>
+      ))}
+    </div>
+    <ScrollBar orientation="horizontal" />
+  </ScrollArea>,
+)
+```
+
+## Painel com divisórias
+
+O conteúdo é livre: aqui o log do agente, com Separator entre as linhas. A barra só aparece quando o conteúdo passa da altura.
+
+```tsx preview col
+const log = [
+  '12:04 developer clonou o worktree de empresa-x-api',
+  '12:05 developer rodou pnpm install',
+  '12:07 developer abriu a sessão empresa-x-1842',
+  '12:11 developer aplicou o diff no schema de billing',
+  '12:14 reviewer foi acionado no handoff',
+  '12:16 reviewer apontou 2 ajustes de microcopy',
+  '12:19 developer corrigiu a microcopy',
+  '12:22 opus check passou em todos os pacotes',
+  '12:24 reviewer aprovou o handoff',
+]
+
+render(
+  <ScrollArea className="h-40 w-full rounded-md border border-border">
+    <div className="p-3 text-sm">
+      {log.map((line, i) => (
+        <div key={i}>
+          {i > 0 && <Separator className="my-1.5" />}
+          <p className="text-muted-foreground">{line}</p>
+        </div>
+      ))}
+    </div>
+  </ScrollArea>,
+)
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `className (ScrollArea)` | `string` | | Onde a altura (h-48) ou a largura mora — é o que define a janela rolável. Sem dimensão, não há o que rolar. |
+| `children (ScrollArea)` | `React.ReactNode` | | O conteúdo da janela. Inclua um <ScrollBar orientation="horizontal" /> entre os filhos pra habilitar a rolagem lateral. |
+| `orientation (ScrollBar)` | `'vertical' \| 'horizontal'` | `'vertical'` | A direção da barra. A vertical já vem embutida; adicione a horizontal só quando precisar. |

package/src/ui/docs/content/section-shell.md

@@ -0,0 +1,121 @@
+## Seção com navegação própria
+
+O nível do meio do chrome. O `AppShell` é o quadro do app e o `Page` é o esqueleto de **uma** tela; entre os dois falta a **seção**: um grupo de telas irmãs (Configurações, Relatórios, a doc) que quer a lista **dentro** do conteúdo, não pendurada na sidebar do app.
+
+A nav é `w-56` — mais estreita que o `w-64` do `AppShell` de propósito, pra hierarquia ficar legível quando as duas aparecem lado a lado.
+
+```tsx preview col
+render(
+  <div className="h-96 w-full overflow-hidden rounded-lg border border-border">
+    <SectionShell
+      groups={[
+        { label: 'Acesso', items: [{ id: 'users', label: 'Usuários' }, { id: 'roles', label: 'Perfis' }] },
+        { label: 'Cadastros', items: [{ id: 'units', label: 'Unidades' }, { id: 'departments', label: 'Departamentos' }] },
+        { items: [{ id: 'audit', label: 'Auditoria' }, { id: 'integrations', label: 'Integrações', disabled: true }] },
+      ]}
+      activeId="users"
+      onSelect={() => {}}
+    >
+      <Page title="Usuários" description="As contas do IdP.">
+        <div className="rounded-lg border border-dashed border-border p-10 text-center text-sm text-muted-foreground">
+          A tela do item ativo (em geral um Page).
+        </div>
+      </Page>
+    </SectionShell>
+  </div>,
+)
+```
+
+## Quando usar — sidebar, tabs ou seção
+
+A regra da casa, pra não virar gosto pessoal:
+
+- **Sidebar do app** (`AppShell`) — os **contextos de negócio**, o mapa que a pessoa carrega na cabeça o dia todo. Custa caro: cada item aqui compete com todos os outros.
+- **`SectionShell`** — as telas de uma seção que a pessoa **visita raro e navega por dentro** quando visita. Configurações é o caso canônico: nenhum admin quer 6 itens de config disputando espaço com Vendas e Estoque. Também é a escolha quando a lista é **dinâmica** (relatórios, documentos) e não cabe num nav estático.
+- **Tabs** — quando são **facetas do mesmo objeto** (a mesma entidade vista de ângulos diferentes), não telas distintas. Se cada aba tem URL própria e faz sentido dar deep-link, provavelmente é seção, não aba.
+
+Sintoma de que uma seção devia sair da sidebar: o item de topo **não tem tela própria** e só existe pra abrir um accordion. Isso é um nó de menu, não um destino — e cobra o preço de um destino.
+
+## Roteamento fica de fora
+
+O componente é **controlado**: `activeId` + `onSelect`. Ele não lê nem escreve URL — quem roteia é o app, com o mecanismo que já usa (path, querystring, estado). Mesma decisão do `AppShell`: o shell é o quadro, não o conteúdo.
+
+O padrão comum é casar `activeId` com um segmento do path e navegar no `onSelect`:
+
+```tsx
+<SectionShell
+  groups={groups}
+  activeId={segments[1]}                          // /settings/users → 'users'
+  onSelect={(id) => navigate(`/settings/${id}`)}
+>
+  {screen}
+</SectionShell>
+```
+
+## O painel remonta na troca
+
+Trocar de item **remonta** o painel — é isso que zera o scroll (sem o remount, a tela nova abre na altura em que a anterior estava). É o detalhe que toda cópia à mão esquecia.
+
+A chave do remount é o `activeId`. `scrollResetKey` sobrescreve, e há dois usos legítimos — em direções opostas:
+
+```tsx
+// NUNCA remontar: a seção preserva o scroll ao trocar de item (chave constante).
+<SectionShell activeId={id} scrollResetKey="fixa" …>
+
+// Remontar MAIS: também dentro da mesma tela, quando a sub-rota troca de registro.
+<SectionShell activeId={id} scrollResetKey={`${id}/${recordId}`} …>
+```
+
+Passar `scrollResetKey={id}` com o mesmo valor do `activeId` é o default escrito à mão — não faz nada.
+
+## Nav redimensionável
+
+`resizable` põe uma divisa arrastável entre a nav e o painel — o mesmo mecanismo do `rail` do AppShell, agora no terceiro nível do chrome. Útil quando os rótulos da nav variam de tamanho (nome de sessão, de arquivo) e o `w-56` fixo ora aperta, ora sobra. Ligado, a largura passa a ser % (`navDefaultSize`/`navMinSize`); desligado, segue a coluna fixa de sempre.
+
+```tsx preview
+<div className="h-64 overflow-hidden rounded-md border">
+  <SectionShell
+    resizable
+    navDefaultSize={30}
+    groups={[{ items: [{ id: 'acoes', label: 'Ações' }, { id: 'entidades', label: 'Entidades' }] }]}
+    activeId="acoes"
+    onSelect={() => {}}
+  >
+    <div className="p-4 text-sm text-muted-foreground">Arraste a divisa à esquerda.</div>
+  </SectionShell>
+</div>
+```
+
+## Três níveis, quando precisar
+
+A maioria das seções é lista simples (`items` no grupo). Quando um grupo tem famílias internas — sub-pasta na doc, por exemplo — use `subgroups`: eles saem **depois** dos `items` soltos, com rótulo mais fraco e mais indentado.
+
+```tsx
+groups={[
+  {
+    label: 'Guias',
+    items: [{ id: 'deploy', label: 'Deploy' }],           // solto na seção
+    subgroups: [{ label: 'CI', items: [{ id: 'build', label: 'Build' }] }],
+  },
+]}
+```
+
+Rótulo vazio (`''`) conta como ausente — quem monta a lista a partir de dados não precisa normalizar antes.
+
+## Props
+
+| Prop | Tipo | O que faz |
+|---|---|---|
+| `groups` | `SectionNavGroup[]` | A nav: grupos (`label` opcional) → `items` e/ou `subgroups`. |
+| `activeId` | `string` | O item destacado (ganha `aria-current="page"`). Ausente = nenhum. |
+| `onSelect` | `(id: string) => void` | Clique no item. |
+| `navHeader` / `navFooter` | `ReactNode` | Topo e rodapé da nav (título da seção, busca, botão de criar). |
+| `navLabel` | `string` | Rótulo da landmark `<nav>`. Default: `Navegação da seção`. |
+| `scrollResetKey` | `string` | O que remonta o painel. Default: `activeId`. |
+| `resizable` | `boolean` | Nav arrastável pelo usuário (mesma divisa do `rail` do AppShell). Default: `false` — a nav é a coluna fixa `w-56`. |
+| `navDefaultSize` / `navMinSize` | `number` | Largura inicial e mínima da nav em %, quando `resizable`. Default: `18` e `12`. |
+| `className` / `navClassName` | `string` | Classes da raiz e da COLUNA da nav (o wrapper, não a `<nav>` de dentro). Com `resizable`, largura em `navClassName` não vale — quem manda é `navDefaultSize`. |
+
+Cada `SectionNavItem` tem `id`, `label` e, opcionais, `icon`, `badge` e `disabled` (visível mas inerte — a tela existe no mapa e ainda não abre).
+
+O `id` precisa ser único em **toda** a nav, não só dentro do grupo: o `activeId` casa por id, então id repetido marca dois itens como atuais e o painel não remonta ao alternar entre eles.