@softize/opus 19.0.0 → 20.1.0

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

@@ -1,6 +1,11 @@
 ## Escolha booleana
 
-Sempre em par com Label (htmlFor↔id) — clicar no texto alterna a caixa. defaultChecked para o modo não controlado.
+Use `Checkbox` quando a pessoa precisar marcar uma opção que só vale ao salvar um formulário, como
+aceitar uma condição ou incluir uma etapa. Para uma preferência que entra em vigor no clique, use
+[`Switch`](/ui/switch).
+
+Associe cada caixa a um [`Label`](/ui/label) pelo par `htmlFor` e `id`: clicar no texto também
+alterna a caixa. `defaultChecked` define o estado inicial no modo não controlado.
 
 ```tsx preview
 <div className="flex items-center gap-2">
@@ -11,7 +16,8 @@ Sempre em par com Label (htmlFor↔id) — clicar no texto alterna a caixa. defa
 
 ## Controlado
 
-onCheckedChange recebe boolean | 'indeterminate' — compare com true para guardar um boolean.
+Use `checked` e `onCheckedChange` quando o estado pertencer ao consumidor. O callback recebe
+`boolean` ou `'indeterminate'`; compare com `true` para guardar um booleano.
 
 ```tsx preview
 const [autoReview, setAutoReview] = useState(true)
@@ -30,7 +36,8 @@ render(
 
 ## Lista de opções
 
-Várias caixas, um estado: o conjunto marcado é a lista de valores — o padrão para anexar skills a um agente.
+Quando várias caixas alimentam um único valor, guarde a lista dos itens marcados. É o caso de
+escolher as habilidades de um agente.
 
 ```tsx preview col-start
 const [skills, setSkills] = useState(['clean-code', 'test'])
@@ -50,9 +57,53 @@ render(
 )
 ```
 
+## Seleção parcial
+
+Quando uma caixa controla um grupo, como “Selecionar todas”, ela precisa mostrar também o caso em
+que só parte do grupo está marcada. Passe `checked="indeterminate"` nesse caso: a caixa fica
+preenchida e mostra um traço no lugar do visto, e leitores de tela a anunciam como parcialmente
+marcada. Ao clicar em uma caixa indeterminada, `onCheckedChange` recebe `true`.
+
+```tsx preview col-start
+const all = ['clean-code', 'code-style', 'ddd', 'test']
+const [skills, setSkills] = useState(['clean-code', 'test'])
+const allState = skills.length === all.length ? true : skills.length > 0 ? 'indeterminate' : false
+const toggleSkill = (skill: string): void => {
+  setSkills((prev) => (prev.includes(skill) ? prev.filter((s) => s !== skill) : [...prev, skill]))
+}
+
+render(
+  <>
+    <div className="flex items-center gap-2">
+      <Checkbox
+        id="skills-all"
+        checked={allState}
+        onCheckedChange={(v) => setSkills(v === true ? all : [])}
+      />
+      <Label htmlFor="skills-all">Selecionar todas</Label>
+    </div>
+    <div className="flex flex-col gap-2 pl-6">
+      {all.map((skill) => (
+        <div key={skill} className="flex items-center gap-2">
+          <Checkbox
+            id={`partial-${skill}`}
+            checked={skills.includes(skill)}
+            onCheckedChange={() => toggleSkill(skill)}
+          />
+          <Label htmlFor={`partial-${skill}`}>{skill}</Label>
+        </div>
+      ))}
+    </div>
+  </>,
+)
+```
+
+Com o grupo inteiro marcado, o clique em “Selecionar todas” recebe `false` e limpa a lista.
+
 ## Desabilitado
 
-disabled esmaece a caixa e o rótulo em par (peer-disabled no Label) — marcado ou não.
+`disabled` esmaece e bloqueia a caixa, marcada ou não. O `Label` escrito logo depois da caixa, no
+mesmo contêiner, esmaece junto.
 
 ```tsx preview col-start
 <div className="flex items-center gap-2">
@@ -65,11 +116,26 @@ disabled esmaece a caixa e o rótulo em par (peer-disabled no Label) — marcado
 </div>
 ```
 
+## Estado inválido
+
+Quando a marcação for obrigatória e estiver ausente, declare `aria-invalid` na caixa e explique o
+que falta com `FieldError`. `data-invalid="true"` no [`Field`](/ui/field) leva o contexto de erro
+também ao rótulo.
+
+```tsx preview col-start
+<Field orientation="horizontal" data-invalid="true">
+  <Checkbox id="accept-terms" aria-invalid aria-describedby="accept-terms-error" />
+  <FieldLabel htmlFor="accept-terms">Li e aceito os termos de uso</FieldLabel>
+</Field>
+<FieldError id="accept-terms-error">Aceite os termos para continuar.</FieldError>
+```
+
 ## Propriedades de Checkbox
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `checked` | `boolean \| 'indeterminate'` | | O estado, no modo controlado — parear com onCheckedChange. |
-| `onCheckedChange` | `(checked: boolean \| 'indeterminate') => void` | | Chamado a cada alternância. Para guardar um boolean, compare com true. |
+| `checked` | `boolean \| 'indeterminate'` | | Estado no modo controlado. Use com `onCheckedChange`. |
+| `onCheckedChange` | `(checked: boolean \| 'indeterminate') => void` | | Chamado a cada alternância. Para guardar um booleano, compare com `true`. |
 | `defaultChecked` | `boolean` | `false` | Estado inicial no modo não controlado. |
-| `disabled` | `boolean` | `false` | Esmaece e bloqueia — o Label em par esmaece junto (peer-disabled). |
+| `disabled` | `boolean` | `false` | Esmaece e bloqueia a caixa; o `Label` irmão posterior esmaece junto. |
+| `aria-invalid` | `boolean` | | Aplica a borda e o anel de erro. |

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

@@ -4,14 +4,14 @@ title: CLI opus
 
 # CLI opus
 
-O Opus traz um CLI que cobre o ciclo: faz o bootstrap, gera artefatos a partir das declarações,
-valida as convenções e expõe o estado vivo para os agentes via MCP. `opus --help` lista os
-comandos e `opus <comando> --help` detalha cada um.
+O CLI `opus` acompanha o projeto do início à entrega: cria o app, gera artefatos a partir das
+declarações, valida as convenções e oferece a estrutura do projeto a agentes por MCP. `opus --help`
+lista os comandos e `opus <comando> --help` detalha cada um.
 
 ## Gates
 
-> Use os gates no CI e antes de entregar uma mudança. Cada um informa o que precisa de ajuste e
-> encerra com sucesso (exit 0) quando não encontra violação.
+Use os gates no CI e antes de entregar uma mudança. Cada um informa o que precisa de ajuste e
+encerra com sucesso (exit 0) quando não encontra violação.
 
 ```bash
 opus check src        # convenções das actions e da UI (exit ≠ 0 se violar)
@@ -20,33 +20,37 @@ opus db check         # drift entidade ↔ banco (read-only)
 opus seed check       # bindings, dependências, ciclos e scripts paralelos de seed
 ```
 
-`opus check` lê o source sem executar nada e aplica regras em três grupos: actions
-(`action-name`, `kind`, `field-order`, `export`, `requires-sem-authorize`), UI
-(`ui-structure`, `ui-semantic-api`, `removed-ui-token`, `unpaired-ui-surface`) e Produtos de Dados
-(`data-product-export`, `-id`, `-duplicate`, `-version`, `-interfaces`, `-interface`, `-entities`
-e `-entity`, todas com o prefixo `data-product`). Um projeto
-marcado com `opus.json` e ainda sem actions passa vacuamente; sem o marcador, zero actions
-falha, porque um gate vazio não é aprovação. `opus check --help` descreve cada regra.
+`opus check` lê o código-fonte sem executá-lo e aplica regras em três grupos: actions
+(`action-name`, `kind`, `field-order`, `export`, `requires-sem-authorize`, `ignored-by-kind`), UI
+(`ui-structure`, `ui-structure-split`, `ui-semantic-api`, `removed-ui-token`, `unpaired-ui-surface`) e
+[Produtos de Dados](/docs/data-products) (`data-product-export`, `-id`, `-duplicate`, `-version`,
+`-interfaces`, `-interface`, `-entities` e `-entity`, todas com o prefixo `data-product`). Um projeto
+marcado com `opus.json` e ainda sem actions passa sem achados; sem o marcador, nenhuma action
+encontrada é falha, porque um gate que não verificou nada não é aprovação. `opus check --help` descreve cada regra.
 
 ### Hook de pré-push
 
-O hook Git que `opus setup` instala roda, antes de cada push: `opus copy --check`; depois
-`opus pre-push materialization` na raiz, para confirmar que os artefatos Opus materializados
-(skills, hooks, instruções) correspondem à versão adotada; e `opus check` em cada app com
-`opus.json`. Qualquer um com exit ≠ 0 bloqueia o push. Os mesmos comandos podem ser executados à
-mão para antecipar o resultado:
+O hook Git que `opus setup` instala executa, antes de cada push:
+
+1. `opus copy --check`;
+2. `opus pre-push materialization` na raiz, que confirma se os artefatos Opus materializados
+   (skills, hooks e instruções) correspondem à versão adotada;
+3. `opus check` em cada app com `opus.json`.
+
+Qualquer comando com exit ≠ 0 bloqueia o push. Para antecipar o resultado, execute os mesmos
+comandos manualmente:
 
 ```bash
 opus pre-push                  # o mesmo opus check no diretório atual
 opus pre-push apps/portal      # o check de um app específico
-opus pre-push materialization  # só a freshness dos artefatos materializados
+opus pre-push materialization  # só confere se os artefatos materializados estão atualizados
 ```
 
 ## Seeds de desenvolvimento e teste
 
-> Seeds registrados no `opus.config.ts` têm perfis, métricas e escopos explícitos. Listagem e gate
-> não abrem o banco; planejamento, aplicação e verificação só conectam com
-> `NODE_ENV=development` ou `NODE_ENV=test`.
+Seeds registrados no `opus.config.ts` têm perfis, métricas e escopos explícitos. Listagem e gate
+não abrem o banco; planejamento, aplicação e verificação só conectam com `NODE_ENV=development` ou
+`NODE_ENV=test`.
 
 ```bash
 opus seed list
@@ -58,7 +62,7 @@ NODE_ENV=development opus seed verify customers.scenarios --profile smoke --scop
 Com qualquer outro valor de `NODE_ENV`, inclusive ausente, esses três comandos falham antes de
 abrir a conexão. O escopo informado também precisa constar em `safety.scopes` do seed.
 
-`--profile` escolhe o perfil (default: o `defaultProfile` do seed) e `--scope` declara o escopo
+`--profile` escolhe o perfil (padrão: o `defaultProfile` do seed) e `--scope` declara o escopo
 dos dados (a variável `OPUS_SEED_SCOPE` é a alternativa). `--json` devolve o resultado
 estruturado, inclusive em caso de erro. `apply` converge quando repetido; não há reset ou
 truncate no contrato. A skill `$create-opus-seed` estrutura um novo dataset, e
@@ -66,33 +70,47 @@ truncate no contrato. A skill `$create-opus-seed` estrutura um novo dataset, e
 
 ## Geração e introspecção
 
-> As declarações (`description` de entidades/actions) são a fonte; o `gen` as projeta. O manifest
-> é um lockfile versionado. A diferença do manifest torna a revisão objetiva.
+As declarações, incluindo a `description` de entidades e actions, são a fonte; `opus gen` as
+projeta. O manifest é versionado como um lockfile, e sua diferença mostra na revisão o que mudou
+no contrato.
 
 ```bash
 opus gen                                    # manifest / openapi / docs / stubs a partir do opus.config.ts
 opus gen --config ./apps/api/opus.config.ts # config fora do diretório atual
-opus gen --output ./custom/gen              # pasta de saída (default: a do config, ou ./.gen)
+opus gen --output ./custom/gen              # pasta de saída (padrão: a do config, ou ./.gen)
 opus copy                                   # inventário semântico de copy dos contratos
-opus introspect                             # modelo da estrutura (actions/reactions/schedules + wiring)
+opus introspect                             # modelo da estrutura: actions, reactions, schedules e ligações
 opus introspect --json
 ```
 
 `opus copy` projeta os textos de `defineAction`/`defineContract` no inventário que a política de
-copy da `@softize/base` valida. O caminho vem de `base.json` (`copy.inventory`; default
+copy da `@softize/base` valida. O caminho vem de `base.json` (`copy.inventory`; padrão
 `.base/copy-inventory.json` na raiz Git), a escrita é atômica e o arquivo gerado deve ser
 versionado. `--check` compara sem escrever e falha quando o inventário está ausente,
 desatualizado ou contém copy dinâmica não declarada.
 
+`opus introspect` lê o código sem executá-lo e só reconhece `defineAction`, `defineReaction`,
+`defineSchedule` e `defineDataProduct`. Actions do par `defineContract` e `bindAction`, reactions do
+par `defineReactionContract` e `bindReaction` e schedules declarados sem `defineSchedule` ficam fora
+do modelo. Para conferir as actions do split, use `opus check`.
+
 `--config` vale para `gen`, `db` e `seed` e sempre aponta para um caminho dentro do projeto. O
-`gen` aceita `--force` por compatibilidade, mas a flag não altera nada: a saída mora em um
+`gen` aceita `--force` por compatibilidade, mas a flag não altera nada: a saída fica em um
 diretório dedicado e é sempre sobrescrita.
 
+### Variáveis de ambiente
+
+`gen`, `db` e `seed` carregam o `.env` que está ao lado do `opus.config.ts` antes de importar o
+config. Assim, a conexão aberta pelo config usa as mesmas variáveis do projeto. Uma variável já
+definida no ambiente vence o arquivo: `DATABASE_URL=… opus db migrate` usa a URL informada no
+comando. A ausência do `.env` não é erro, porque containers e CI costumam injetar as variáveis
+diretamente.
+
 ## Banco
 
-> Os comandos `db` carregam o `opus.config.ts` e abrem conexão; por isso rodam num runner isolado
-> via `tsx`. O padrão é um schema idempotente: um script SQL evolutivo re-rodável, não migrations
-> versionadas.
+Os comandos `db` carregam o `opus.config.ts` e abrem conexão; por isso rodam num processo separado,
+com `tsx`. O padrão é um schema idempotente: um único script SQL que pode ser executado de novo a
+cada mudança, em vez de migrations numeradas.
 
 ```bash
 opus db check      # compara o schema do banco com as entidades (read-only)
@@ -100,36 +118,57 @@ opus db migrate    # aplica o schema idempotente e roda o drift-check na sequên
 opus db scaffold   # rascunho kysely a partir do diff, como referência para escrever o SQL
 ```
 
-`db scaffold` gera um rascunho para revisão à mão; a verdade continua sendo o script. `db migrate
-down` está aposentado e encerra com erro: sem histórico de migrations não há o que reverter —
-rollback é editar o schema e rodar `opus db migrate` de novo. O `opus.config.ts` precisa expor a
-factory lazy `database`, as entidades (ou domínios) e, opcionalmente, `schema` e `migrations`;
-`opus db --help` detalha.
+`db scaffold` gera um rascunho para revisão manual; a fonte continua sendo o script. `db migrate
+down` foi descontinuado e encerra com erro: sem histórico de migrations, não há o que reverter.
+Para desfazer uma mudança, edite o schema e rode `opus db migrate` de novo.
+
+O `opus.config.ts` precisa expor a factory `database`, chamada só quando um comando precisa do
+banco, as entidades ou os domínios e, opcionalmente, `schema` e `migrations`; `opus db --help`
+detalha cada campo.
 
 ## Bootstrap
 
-> `create` scaffolda um app novo com os pré-requisitos plugados; `setup` é per-app
-> (idempotente, nunca sobrescreve o seu).
+`create` gera um app novo com os pré-requisitos configurados. `setup` roda em cada app, pode ser
+repetido e não sobrescreve arquivos do projeto.
 
 ```bash
-opus create meu-app                 # app canônico do zero: protocolo + UI + preview + automação
-opus create meu-cliente --monorepo  # a RAIZ de um workspace (apps/* + packages/*)
+opus create meu-app                 # app novo: protocolo, UI, preview e automação
+opus create meu-cliente --monorepo  # a raiz de um workspace (apps/* + packages/*)
 opus create apps/portal             # dentro de um workspace: só o app (modo detectado)
 opus setup                          # grava opus.json e materializa a camada específica do SDK
 ```
 
-O esqueleto do `create` versiona com o Opus (sai do mesmo pacote que o SDK que ele
-configura) e nasce com os gates verdes: domínio-exemplo canônico, teste, manifest e o dev
-server pronto para o preview do Maestro. O método geral, a memória e a revisão vêm da Base
-depois de `pnpm run setup`. Dois modos, por detecção:
-repo standalone (template inteiro) ou **app em monorepo** (dentro de um workspace pnpm:
-só os arquivos do app; o que a raiz precisa ter vira aviso, sem clobber).
-
-## MCP — estado vivo para os agentes
-
-> O server MCP expõe introspecção, check e scaffold de action. É como um agente lê a estrutura e cria
-> action no formato canônico sem decorar convenção.
-
-`opus mcp` sobe o server (configurado em `.mcp.json`): o agente consulta a estrutura, roda o
-check e gera o esqueleto de uma action nova pela skill `$create-opus-action` — a mesma régua do
-`opus check`, por construção.
+O esqueleto do `create` vem do mesmo pacote que o SDK e acompanha sua versão. O app nasce com os
+gates aprovados: domínio de exemplo, teste, manifest e dev server que respeita a variável `PORT`,
+para que um orquestrador de preview escolha a porta. O método geral, a memória e a revisão vêm da
+Base depois de `pnpm run setup`.
+
+O `create` detecta o modo. Fora de um workspace pnpm, gera o repositório inteiro. Dentro de um
+workspace, gera só os arquivos do app e lista como aviso o que a raiz precisa ter, sem alterar os
+arquivos dela.
+
+## MCP para agentes de desenvolvimento
+
+`opus mcp` inicia, por stdio, um servidor MCP para o agente que trabalha no código do projeto. Com
+ele, o agente consulta a estrutura, valida convenções, gera actions no formato esperado e
+consulta o catálogo de componentes. Esse servidor não executa actions do app; para expor actions a
+agentes em produção, use o [servidor MCP do runtime](/docs/mcp).
+
+| Tool | O que faz |
+| --- | --- |
+| `opus_introspect` | Devolve o modelo de `opus introspect`, com os mesmos limites descritos acima. |
+| `opus_check` | Executa as regras de `opus check` e devolve os achados. |
+| `opus_create_action` | Devolve, sem gravar, o contrato e o binding iniciais de uma action a partir de recurso, verbo e kind. A skill `$create-opus-action` usa o mesmo gerador. |
+| `opus_list_components` | Lista os componentes da UI, quando usar cada um e o que importar. |
+| `opus_get_component` | Detalha um componente pelo nome. |
+
+O setup não cria a configuração do cliente MCP. Em clientes que leem `.mcp.json` na raiz do
+projeto, registre o servidor assim:
+
+```json
+{
+  "mcpServers": {
+    "opus": { "command": "pnpm", "args": ["exec", "opus", "mcp"] }
+  }
+}
+```

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

@@ -1,38 +1,44 @@
 ## Seção recolhível
 
-CollapsibleTrigger alterna o CollapsibleContent — o Trigger já é o <button>. defaultOpen deixa o estado com o componente.
+Use `Collapsible` para esconder um bloco secundário atrás de um gatilho, mantendo o restante da
+tela visível. `CollapsibleTrigger` já renderiza um `<button>` e alterna o `CollapsibleContent`.
+Sem `open`, o componente guarda o próprio estado; `defaultOpen` apenas define se ele começa aberto.
 
 ```tsx preview col
 <Collapsible defaultOpen className="w-full max-w-sm space-y-2">
-  <CollapsibleTrigger className="flex w-full items-center justify-between rounded-md border border-border px-3 py-2 text-sm font-medium hover:bg-muted">
-    Repositórios do workspace
-    <ChevronsUpDown className="h-4 w-4 text-muted-foreground" />
+  <CollapsibleTrigger className="flex w-full items-center justify-between rounded-md border border-border px-3 py-2 text-sm font-medium hover:bg-muted [&[data-state=open]>svg]:rotate-180">
+    Serviços incluídos na revisão
+    <ChevronDown className="size-4 text-muted-foreground transition-transform" />
   </CollapsibleTrigger>
   <CollapsibleContent className="space-y-1 px-3 text-sm text-muted-foreground">
-    <p>empresa-x-api</p>
-    <p>empresa-x-web</p>
-    <p>empresa-x-infra</p>
+    <p>Troca de óleo</p>
+    <p>Filtro de ar</p>
+    <p>Alinhamento</p>
   </CollapsibleContent>
 </Collapsible>
 ```
 
+O gatilho recebe `data-state="open"` ou `data-state="closed"`. O seletor
+`[&[data-state=open]>svg]:rotate-180` usa esse atributo para girar o ícone sem estado próprio.
+
 ## Controlado
 
-open + onOpenChange põem o estado nas suas mãos — dá para refletir no gatilho (aqui o chevron gira) ou guardar a preferência.
+Use `open` e `onOpenChange` quando outra parte da tela precisar conhecer o estado, por exemplo para
+trocar o texto do gatilho ou guardar a preferência da pessoa.
 
 ```tsx preview col
 const [open, setOpen] = useState(false)
 
 render(
   <Collapsible open={open} onOpenChange={setOpen} className="w-full max-w-sm space-y-2">
-    <CollapsibleTrigger className="flex w-full items-center justify-between rounded-md border border-border px-3 py-2 text-sm font-medium hover:bg-muted">
-      Skills do agente developer
-      <ChevronDown className={open ? 'h-4 w-4 rotate-180 transition-transform' : 'h-4 w-4 transition-transform'} />
+    <CollapsibleTrigger className="flex w-full items-center justify-between rounded-md border border-border px-3 py-2 text-sm font-medium hover:bg-muted [&[data-state=open]>svg]:rotate-180">
+      {open ? 'Ocultar peças utilizadas' : 'Mostrar peças utilizadas'}
+      <ChevronDown className="size-4 text-muted-foreground transition-transform" />
     </CollapsibleTrigger>
     <CollapsibleContent className="space-y-1 px-3 text-sm text-muted-foreground">
-      <p>clean-code</p>
-      <p>code-style</p>
-      <p>ddd</p>
+      <p>Filtro de óleo</p>
+      <p>Pastilhas de freio</p>
+      <p>Velas de ignição</p>
     </CollapsibleContent>
   </Collapsible>,
 )
@@ -40,16 +46,17 @@ render(
 
 ## Desabilitado
 
-disabled no Collapsible trava o gatilho — a seção fica fixa no estado atual (aqui, fechada).
+Use `disabled` no `Collapsible` quando a seção não puder mudar de estado por enquanto. O gatilho
+fica desabilitado e a seção permanece como está; no exemplo, fechada.
 
 ```tsx preview col
 <Collapsible disabled className="w-full max-w-sm space-y-2">
   <CollapsibleTrigger className="flex w-full items-center justify-between rounded-md border border-border px-3 py-2 text-sm font-medium disabled:cursor-not-allowed disabled:opacity-50">
-    Sessões arquivadas
-    <ChevronsUpDown className="h-4 w-4 text-muted-foreground" />
+    Revisões anteriores
+    <ChevronDown className="size-4 text-muted-foreground" />
   </CollapsibleTrigger>
   <CollapsibleContent className="px-3 text-sm text-muted-foreground">
-    <p>Nada para mostrar enquanto o workspace está em sincronização.</p>
+    <p>O histórico fica disponível depois da sincronização com a concessionária.</p>
   </CollapsibleContent>
 </Collapsible>
 ```
@@ -61,4 +68,21 @@ disabled no Collapsible trava o gatilho — a seção fica fixa no estado atual
 | `defaultOpen` | `boolean` | `false` | Estado inicial no modo não controlado. |
 | `open` | `boolean` | | Estado no modo controlado. Use com `onOpenChange`. |
 | `onOpenChange` | `(open: boolean) => void` | | Chamado a cada abertura ou fechamento. |
-| `disabled` | `boolean` | `false` | Bloqueia o gatilho e mantém a seção no estado atual. |
+| `disabled` | `boolean` | `false` | Desabilita o gatilho e mantém a seção no estado atual. |
+| `className` | `string` | | Ajusta o contêiner. |
+
+## Propriedades de CollapsibleTrigger
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `asChild` | `boolean` | `false` | Usa o filho como gatilho, como um `Button`, sem criar outro `<button>`. |
+| `className` | `string` | | Ajusta o gatilho. O estado chega em `data-state`. |
+| `children` | `ReactNode` | | Rótulo do gatilho e, quando houver, o ícone de estado. |
+
+## Propriedades de CollapsibleContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `forceMount` | `boolean` | `false` | Mantém o conteúdo montado mesmo fechado, por exemplo para animá-lo por CSS. |
+| `className` | `string` | | Ajusta a região recolhível. |
+| `children` | `ReactNode` | | Conteúdo exibido quando a seção está aberta. |

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

@@ -1,7 +1,9 @@
 ## Lista filtrável inline
 
-Digite para filtrar uma coleção com navegação por teclado, grupos e estado vazio. Command é a base
-do Select pesquisável; para uma escolha em formulário, use Select.
+Use `Command` quando a pessoa precisar encontrar um item ou uma ação digitando parte do nome e
+escolher pelo teclado. A lista filtra enquanto a busca muda, organiza os itens em grupos e mostra
+um estado vazio quando nada corresponde. `Command` também é a base do `Select` pesquisável; para
+escolher um valor em um formulário, use [`Select`](/ui/select).
 
 ```tsx preview
 <Command className="max-w-sm rounded-lg border border-border">
@@ -14,26 +16,38 @@ do Select pesquisável; para uma escolha em formulário, use Select.
     </CommandGroup>
     <CommandSeparator />
     <CommandGroup heading="Ações">
-      <CommandItem><Plus /> Nova sessão <CommandShortcut>⌘N</CommandShortcut></CommandItem>
+      <CommandItem><Plus /> Criar sessão <CommandShortcut>⌘N</CommandShortcut></CommandItem>
       <CommandItem><Play /> Iniciar ambiente</CommandItem>
     </CommandGroup>
   </CommandList>
 </Command>
 ```
 
-## Palette modal (CommandDialog)
+## Paleta de comandos em modal
 
-O Command embrulhado em um Dialog mantém um header compacto com título e close. A descrição
-permanece disponível para tecnologias assistivas. O atalho ⌘K (keydown no app) só troca o open —
-o conteúdo é o mesmo do inline.
+`CommandDialog` apresenta a mesma lista dentro de um [`Dialog`](/ui/dialog), com um cabeçalho
+compacto que mostra o título e o botão de fechar. A descrição fica disponível somente para
+tecnologias assistivas. O componente não registra atalho de teclado: para abrir a paleta com
+⌘K, o aplicativo escuta o evento e altera `open`, como no exemplo.
 
 ```tsx preview
 const [open, setOpen] = useState(false)
 
+useEffect(() => {
+  const onKeyDown = (event: KeyboardEvent): void => {
+    if (event.key.toLowerCase() === 'k' && (event.metaKey || event.ctrlKey)) {
+      event.preventDefault()
+      setOpen((current) => !current)
+    }
+  }
+  document.addEventListener('keydown', onKeyDown)
+  return () => document.removeEventListener('keydown', onKeyDown)
+}, [])
+
 render(
   <>
     <Button variant="outline" onClick={() => setOpen(true)}>
-      Abrir palette <CommandShortcut>⌘K</CommandShortcut>
+      Abrir paleta <CommandShortcut>⌘K</CommandShortcut>
     </Button>
     <CommandDialog open={open} onOpenChange={setOpen}>
       <CommandInput placeholder="Buscar comando…" />
@@ -80,6 +94,7 @@ render(
 | `title` | `string` | `'Paleta de comandos'` | Título exibido no header compacto; também nomeia o diálogo para tecnologias assistivas. |
 | `description` | `string` | `'Busque um comando para executar…'` | Descrição disponível somente para tecnologias assistivas. |
 | `showCloseButton` | `boolean` | `true` | Exibe o botão de fechamento. |
+| `className` | `string` | | Classes do conteúdo do diálogo, como a largura. |
 
 ## Propriedades de CommandItem
 
@@ -96,3 +111,10 @@ render(
 |---|---|---|---|
 | `heading` | `React.ReactNode` | | Título exibido acima dos itens do grupo. |
 | `value` | `string` | | Identificador do grupo; obrigatório e único quando não há `heading`. |
+
+`CommandList` limita a altura a `18.75rem` e rola o excedente; `CommandEmpty` aparece somente quando
+nenhum item corresponde à busca; `CommandSeparator` divide grupos; e `CommandShortcut` mostra, à
+direita do item, a combinação de teclas que o aplicativo associou à ação. Esses componentes não têm
+propriedades próprias além das props nativas do elemento que renderizam; `className` soma classes
+ao estilo padrão de cada um. O atalho exibido por `CommandShortcut` é apenas informativo:
+registrar o evento continua com o aplicativo.

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

@@ -1,6 +1,14 @@
 ## Envio de texto
 
-A caixa de escrever da casa: textarea em uma pílula elevada (`rounded-xl` + `border` + `shadow-sm`), **Enter** envia / **Shift+Enter** quebra linha, enviar dentro. É o composer do [Chat](/ui/chat) extraído — use sozinho quando há entrada de texto mas não um chat (ex.: criar uma sessão). Controlado: o dono do texto é você. Os callbacks opcionais `onHistoryPrevious` e `onHistoryNext` permitem que esse dono consuma **↑/↓**; sem eles, as setas mantêm o comportamento nativo da textarea.
+Use `Composer` quando a tela precisar receber um texto para envio sem apresentar uma conversa, como
+a descrição que abre uma nova sessão de trabalho. É a mesma caixa de escrita do [Chat](/ui/chat):
+um campo que cresce com o texto, com o botão de enviar dentro da moldura. **Enter** envia e
+**Shift+Enter** quebra a linha.
+
+O componente é controlado: `value` e `onChange` pertencem a quem o compõe, que também limpa o texto
+depois do envio. Os callbacks opcionais `onHistoryPrevious` e `onHistoryNext` permitem que esse
+dono use **↑** e **↓** para navegar por um histórico próprio; sem eles, as setas mantêm o
+comportamento nativo do campo.
 
 ```tsx preview col
 const [text, setText] = React.useState('')
@@ -15,9 +23,15 @@ render(
 )
 ```
 
-## Com seletores (barra de ações)
+## Com seletores na barra de ações
+
+Com `actions`, o composer passa a ter duas linhas: o campo em cima e, embaixo, uma barra com os
+seletores à esquerda e o botão de enviar à direita. Use ali escolhas que definem o destino do texto,
+como o aplicativo, a tarefa ou o agente. Mantenha os controles discretos, como um `Button` `ghost` ou
+um [`Select`](/ui/select) `variant="ghost"`: a barra acompanha o texto e não é um formulário.
 
-Passe `actions` e o composer vira **duas linhas**: textarea em cima, uma barra limpa embaixo com os seletores à ESQUERDA e o enviar à direita. Estilize os controles como discretos (ghost, sem borda) — a barra não é um formulário. É onde o Maestro prende **app + task** e a GB, o **agente**. O `submitDisabled` trava o enviar além de vazio/busy (ex.: falta escolher o app), sem esconder a barra.
+`submitDisabled` impede o envio enquanto falta uma condição além do texto, como escolher o
+aplicativo, sem esconder a barra.
 
 ```tsx preview col
 const [text, setText] = React.useState('')
@@ -55,11 +69,12 @@ render(
 |---|---|---|---|
 | `value` | `string` | | Texto controlado; o dono do estado é quem compõe. |
 | `onChange` | `(value: string) => void` | | Recebe cada alteração do texto. |
-| `onSubmit` | `() => void` | | Enter (sem Shift) ou o botão enviar; só dispara quando dá para enviar. |
+| `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. |
 | `onHistoryPrevious` / `onHistoryNext` | `() => boolean` | | Navegação por ↑/↓ no histórico do dono; retorne `true` quando a tecla foi consumida. |
-| `busy` | `boolean` | `false` | Trava o composer enquanto o turno corre; o enviar vira spinner. |
-| `submitDisabled` | `boolean` | `false` | Gate extra de envio além de vazio e `busy` (ex.: falta escolher o app). |
+| `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. |
 | `placeholder` | `string` | `'Escreva uma mensagem…'` | Texto de orientação do campo. |
-| `rows` | `number` | `1` | Linhas iniciais do textarea; ele cresce com o conteúdo. |
+| `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 enviar; presente, o composer vira duas linhas. |
+| `actions` | `ReactNode` | | Controles discretos à esquerda do botão de enviar; com eles, o composer passa a ter duas linhas. |
+| `className` | `string` | | Classes aplicadas à moldura do composer. |