@seedgrid/ai-toolkit 0.3.0 → 0.3.2

package/seedgridKB/SeedGrid/SeedGrid-components/inputs-texto/Visao-geral.md

@@ -1,123 +1,123 @@
----
-tags: [seedgrid, component, frontend, react, inputs-texto]
-fonte: front/seedgrid-fe-components/packages/seedgrid-fe-components/src/inputs
-branch: main
-commit: ad30fc11de
-analisado-em: 2026-10-14
----
-
-# Inputs de texto (SgInput*)
-
-Este grupo reúne os 15 campos de digitação do pacote `@seedgrid/fe-components` (v`2026.7.1`). Todos estão em `src/inputs/` e todos são exportados pela raiz do pacote. Detalhe de props, eventos e ref: [[SeedGrid/SeedGrid-components/inputs-texto/API|API dos inputs de texto]]. Código: [[SeedGrid/SeedGrid-components/inputs-texto/Exemplos|Exemplos dos inputs de texto]]. Grupos vizinhos: [[SeedGrid/SeedGrid-components/inputs-selecao/Visao-geral|inputs de seleção]], [[SeedGrid/SeedGrid-components/datatable/Visao-geral|SgDatatable]], [[SeedGrid/SeedGrid-components/editor/Visao-geral|SgTextEditor]].
-
-## Objetivo
-
-Os componentes oferecem campos de formulário prontos, com as seguintes características comuns:
-- rótulo flutuante, no topo ou à esquerda;
-- validação embutida, com mensagens traduzidas;
-- máscaras brasileiras (CPF, CNPJ alfanumérico, telefone, CEP);
-- integração opcional com react-hook-form, por `register` ou por `control`.
-
-O padrão de nomes de eventos vem da casa: `onEnter` no foco, `onExit` no blur, `onChange(value)` com o valor já tratado e `onValidation(msg | null)`. **Confirmado**: comentários "padrao seedgrid" nos tipos.
-
-## Quando usar cada um
-
-| Componente | Use para | Base |
-|---|---|---|
-| `SgInputText` | Texto curto livre (nome, título, código). É a base dos demais. | própria |
-| `SgInputTextArea` | Texto longo multilinha, com mínimo de linhas e palavras. | própria (`<textarea>`) |
-| `SgInputTextSearch` | Caixa de busca com debounce (`onSearchChange`). | `SgInputText` |
-| `SgInputEmail` | E-mail com validação de formato e bloqueio de domínios temporários. | `SgInputText` |
-| `SgInputPassword` | Senha com política configurável, barra de força, olho e gerador. | `SgInputText` |
-| `SgInputPhone` | Telefone BR com máscara (10 ou 11 dígitos). | `SgInputText` |
-| `SgInputCPF` | CPF com máscara e dígito verificador. | `SgInputText` |
-| `SgInputCNPJ` | CNPJ numérico ou alfanumérico, com consulta pública opcional. | `SgInputText` |
-| `SgInputCPFCNPJ` | Campo único que aceita CPF ou CNPJ e detecta qual é. | `SgInputText` |
-| `SgInputPostalCode` | CEP/código postal de BR, PT, US, ES, UY, AR e PY, com ViaCEP opcional. | `SgInputText` |
-| `SgInputDate` | Data com o widget nativo (`type="date"`) e limites min/max. | `SgInputText` |
-| `SgInputBirthDate` | Data de nascimento com idade mínima/máxima. | `SgInputDate` |
-| `SgInputNumber` | Número decimal formatado pelo locale, com min/max. | própria |
-| `SgInputCurrency` | Valor monetário com símbolo via `Intl` (padrão BRL). | própria (derivada do código do `SgInputNumber`) |
-| `SgInputOTP` | Código de uso único segmentado, com máscara (`999999`, `###-###`). | própria |
-
-Para escolhas fechadas, como combos e listas, use o grupo [[SeedGrid/SeedGrid-components/inputs-selecao/Visao-geral|inputs de seleção]]. Para texto rico, use o [[SeedGrid/SeedGrid-components/editor/Visao-geral|SgTextEditor]]. Esses mesmos encaminhamentos aparecem nos `aiHints.avoidUseCases` de `SgInputText.meta.ts`. **Confirmado**.
-
-## Composição
-
-```mermaid
-graph TD
-  T[SgInputText] --> S[SgInputTextSearch]
-  T --> E[SgInputEmail]
-  T --> P[SgInputPassword]
-  T --> Ph[SgInputPhone]
-  T --> CPF[SgInputCPF]
-  T --> CNPJ[SgInputCNPJ]
-  T --> CC[SgInputCPFCNPJ]
-  T --> CEP[SgInputPostalCode]
-  T --> D[SgInputDate] --> B[SgInputBirthDate]
-  T -.também usado por.-> SEL[SgAutocomplete / SgCombobox / SgMultiSelect]
-```
-
-- Os wrappers usam `Omit<SgInputTextProps, …>`, acrescentam as próprias props e repassam o resto ao `SgInputText`. A integração com o RHF fica no `SgInputText`.
-- Cada wrapper mantém **o próprio erro interno** e o passa como `error` ao `SgInputText`, junto com o erro de `fieldState` via `resolveFieldError`. Como o `SgInputText` também valida (required/maxLength…), uma mensagem do wrapper tem precedência sobre a dele. **Confirmado**.
-- `SgInputTextArea`, `SgInputNumber`, `SgInputCurrency` e `SgInputOTP` repetem o padrão visual do `SgInputText`, mas têm implementação própria.
-
-## Dependências
-
-- **Peers obrigatórios do pacote:**
-  - `react` `^18.2.0 || ^19.0.0`;
-  - `react-hook-form` `^7.0.0`, importado estaticamente (`Controller`) pelos inputs, mesmo sem uso de formulário;
-  - `lucide-react` `^0.468.0 || ^1.0.0` (ícone `X` do botão limpar).
-
-  **Confirmado** em `package.json` e nos imports.
-- **Peers TipTap:** não são usados por este grupo, mas são carregados pela raiz do pacote. Ver [[SeedGrid/SeedGrid-components/editor/Visao-geral|SgTextEditor]].
-- **Rede:** `SgInputCNPJ` (`validateWithPublicaCnpj`) e `SgInputPostalCode` (`validateWithViaCep`) chamam `fetch` para `publica.cnpj.ws` e `viacep.com.br` por padrão. Ambos aceitam uma função de consulta própria (`publicaCnpjFetch`, `viaCepFetch`).
-- **APIs do navegador:** `SgInputPassword` usa `crypto.getRandomValues` para gerar senha.
-- **"use client":** todos os arquivos começam com `"use client"`, o que serve ao Next.js App Router.
-
-## Tema e estilos
-
-- O CSS compilado (Tailwind) é **injetado automaticamente** no `<head>` quando o pacote é importado (`ensureSeedgridStylesInjected()` em `src/injectStyles.ts`, chamado no topo de `src/index.ts`). A injeção tem proteção para SSR e para dupla injeção (id `seedgrid-fe-components-styles`). Também existe `@seedgrid/fe-components/style.css` para quem prefere importar o arquivo. **Confirmado**.
-- **Tokens:**
-  - Cores via variáveis CSS do tema: `hsl(var(--primary))`, `--destructive`, `--foreground`, `--muted`, `--border`.
-  - Variáveis específicas de input, com fallback: `--sg-input-bg`, `--sg-input-fg`, `--sg-input-placeholder`, `--sg-input-disabled-bg`, `--sg-input-disabled-fg`.
-
-  O pacote `@seedgrid/fe-theme` aparece só como devDependency. A relação exata entre ele e essas variáveis é **Inferência**.
-- **Customização:**
-  - Props: `className` (no `SgInputText` **substitui** as classes do input), `labelClassName`, `width`, `borderRadius`, `elevation`, `withBorder`, `filled`.
-  - Dark mode do `SgInputDate`: `color-scheme` via `useDarkFlag()`.
-
-## Internacionalização
-
-- **Provider:** textos padrão vêm de `useComponentsI18n()` (`src/i18n/index.ts`). Locales embutidos: `pt-BR`, `pt-PT`, `en-US` (alias `en`), `es`, `fr`.
-- **Sem provider:** vale o i18n global, que por padrão é **`en-US`**. Para trocar, use `<SgComponentsI18nProvider locale="pt-BR" messages={…}>` ou `setComponentsI18n(...)`. As mensagens passadas sobrescrevem as embutidas, chave por chave.
-- **Chaves deste grupo:** `components.inputs.*`, `components.password.*`, `components.validators.*` e `components.actions.clear`.
-- **Props `*Message`:** sempre têm precedência sobre a tradução.
-
-**Confirmado**.
-
-## Testes existentes (lidos, **não executados**)
-
-- `tests/inputs-dom.test.mjs` (jsdom) cobre:
-  - `SgInputText` controlado via `inputProps.value` e via RHF;
-  - `onChange` do `SgInputPassword` e o tamanho da senha gerada;
-  - asterisco do `SgInputPhone`;
-  - debounce, `minChars` e "distinct" do `SgInputTextSearch`.
-- `tests/inputs-i18n.test.mjs`: rótulos de acessibilidade do `SgInputOTP`.
-- `tests/rhf.test.mjs` e `tests/rhf-components-contract.test.mjs`: `resolveFieldError`, `mergeRequiredRule` e presença dos caminhos `register`/`control` no `SgInputTextArea`.
-- `tests/i18n-components-contract.test.mjs`: garante que os componentes usam `t(...)` em vez de texto fixo.
-
-O script `test` do pacote roda `pnpm run build` antes.
-
-## Limitações e pontos de atenção
-
-- `SgInputBirthDate` sem `minAge` nem `maxAge` acusa erro de configuração para qualquer data preenchida. **Confirmado**.
-- `SgInputPassword` tem `maxLength` padrão **15**. `SgInputCPF`, `SgInputCNPJ` e `SgInputCPFCNPJ` têm `maxLength` padrão 18. **Confirmado**.
-- `SgInputCPF`, `SgInputCNPJ`, `SgInputCPFCNPJ`, `SgInputPostalCode`, `SgInputDate` e `SgInputBirthDate` não repassam `required` ao `SgInputText`. Consequências:
-  - o rótulo fica sem `*`;
-  - as rules do RHF ficam sem `required` automático (a validação interna continua funcionando).
-
-  `SgInputPhone`, `SgInputEmail` e `SgInputPassword` repassam. **Confirmado** (`required={required}` só aparece nesses três).
-- O erro não é anunciado a leitores de tela no `SgInputText` (sem `aria-invalid`/`aria-describedby`). O `SgToggleSwitch` e o `SgInputOTP` fazem isso. **Confirmado**.
-- Para reagir ao foco, use `onEnter`: o `inputProps.onFocus` não é chamado pelo `SgInputText`. **Confirmado**; ver [[SeedGrid/SeedGrid-components/inputs-texto/API#Contrato base SgInputText|contrato base]].
-- Os tipos de props de `SgInputEmail`, `SgInputPassword`, `SgInputDate` e `SgInputBirthDate` não são reexportados. **Confirmado**.
+---
+tags: [seedgrid, component, frontend, react, inputs-texto]
+fonte: front/seedgrid-fe-components/packages/seedgrid-fe-components/src/inputs
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# Inputs de texto (SgInput*)
+
+Este grupo reúne os 15 campos de digitação do pacote `@seedgrid/fe-components` (v`2026.7.1`). Todos estão em `src/inputs/` e todos são exportados pela raiz do pacote. Detalhe de props, eventos e ref: [[SeedGrid/SeedGrid-components/inputs-texto/API|API dos inputs de texto]]. Código: [[SeedGrid/SeedGrid-components/inputs-texto/Exemplos|Exemplos dos inputs de texto]]. Grupos vizinhos: [[SeedGrid/SeedGrid-components/inputs-selecao/Visao-geral|inputs de seleção]], [[SeedGrid/SeedGrid-components/datatable/Visao-geral|SgDatatable]], [[SeedGrid/SeedGrid-components/editor/Visao-geral|SgTextEditor]].
+
+## Objetivo
+
+Os componentes oferecem campos de formulário prontos, com as seguintes características comuns:
+- rótulo flutuante, no topo ou à esquerda;
+- validação embutida, com mensagens traduzidas;
+- máscaras brasileiras (CPF, CNPJ alfanumérico, telefone, CEP);
+- integração opcional com react-hook-form, por `register` ou por `control`.
+
+O padrão de nomes de eventos vem da casa: `onEnter` no foco, `onExit` no blur, `onChange(value)` com o valor já tratado e `onValidation(msg | null)`. **Confirmado**: comentários "padrao seedgrid" nos tipos.
+
+## Quando usar cada um
+
+| Componente | Use para | Base |
+|---|---|---|
+| `SgInputText` | Texto curto livre (nome, título, código). É a base dos demais. | própria |
+| `SgInputTextArea` | Texto longo multilinha, com mínimo de linhas e palavras. | própria (`<textarea>`) |
+| `SgInputTextSearch` | Caixa de busca com debounce (`onSearchChange`). | `SgInputText` |
+| `SgInputEmail` | E-mail com validação de formato e bloqueio de domínios temporários. | `SgInputText` |
+| `SgInputPassword` | Senha com política configurável, barra de força, olho e gerador. | `SgInputText` |
+| `SgInputPhone` | Telefone BR com máscara (10 ou 11 dígitos). | `SgInputText` |
+| `SgInputCPF` | CPF com máscara e dígito verificador. | `SgInputText` |
+| `SgInputCNPJ` | CNPJ numérico ou alfanumérico, com consulta pública opcional. | `SgInputText` |
+| `SgInputCPFCNPJ` | Campo único que aceita CPF ou CNPJ e detecta qual é. | `SgInputText` |
+| `SgInputPostalCode` | CEP/código postal de BR, PT, US, ES, UY, AR e PY, com ViaCEP opcional. | `SgInputText` |
+| `SgInputDate` | Data com o widget nativo (`type="date"`) e limites min/max. | `SgInputText` |
+| `SgInputBirthDate` | Data de nascimento com idade mínima/máxima. | `SgInputDate` |
+| `SgInputNumber` | Número decimal formatado pelo locale, com min/max. | própria |
+| `SgInputCurrency` | Valor monetário com símbolo via `Intl` (padrão BRL). | própria (derivada do código do `SgInputNumber`) |
+| `SgInputOTP` | Código de uso único segmentado, com máscara (`999999`, `###-###`). | própria |
+
+Para escolhas fechadas, como combos e listas, use o grupo [[SeedGrid/SeedGrid-components/inputs-selecao/Visao-geral|inputs de seleção]]. Para texto rico, use o [[SeedGrid/SeedGrid-components/editor/Visao-geral|SgTextEditor]]. Esses mesmos encaminhamentos aparecem nos `aiHints.avoidUseCases` de `SgInputText.meta.ts`. **Confirmado**.
+
+## Composição
+
+```mermaid
+graph TD
+  T[SgInputText] --> S[SgInputTextSearch]
+  T --> E[SgInputEmail]
+  T --> P[SgInputPassword]
+  T --> Ph[SgInputPhone]
+  T --> CPF[SgInputCPF]
+  T --> CNPJ[SgInputCNPJ]
+  T --> CC[SgInputCPFCNPJ]
+  T --> CEP[SgInputPostalCode]
+  T --> D[SgInputDate] --> B[SgInputBirthDate]
+  T -.também usado por.-> SEL[SgAutocomplete / SgCombobox / SgMultiSelect]
+```
+
+- Os wrappers usam `Omit<SgInputTextProps, …>`, acrescentam as próprias props e repassam o resto ao `SgInputText`. A integração com o RHF fica no `SgInputText`.
+- Cada wrapper mantém **o próprio erro interno** e o passa como `error` ao `SgInputText`, junto com o erro de `fieldState` via `resolveFieldError`. Como o `SgInputText` também valida (required/maxLength…), uma mensagem do wrapper tem precedência sobre a dele. **Confirmado**.
+- `SgInputTextArea`, `SgInputNumber`, `SgInputCurrency` e `SgInputOTP` repetem o padrão visual do `SgInputText`, mas têm implementação própria.
+
+## Dependências
+
+- **Peers obrigatórios do pacote:**
+  - `react` `^18.2.0 || ^19.0.0`;
+  - `react-hook-form` `^7.0.0`, importado estaticamente (`Controller`) pelos inputs, mesmo sem uso de formulário;
+  - `lucide-react` `^0.468.0 || ^1.0.0` (ícone `X` do botão limpar).
+
+  **Confirmado** em `package.json` e nos imports.
+- **Peers TipTap:** não são usados por este grupo, mas são carregados pela raiz do pacote. Ver [[SeedGrid/SeedGrid-components/editor/Visao-geral|SgTextEditor]].
+- **Rede:** `SgInputCNPJ` (`validateWithPublicaCnpj`) e `SgInputPostalCode` (`validateWithViaCep`) chamam `fetch` para `publica.cnpj.ws` e `viacep.com.br` por padrão. Ambos aceitam uma função de consulta própria (`publicaCnpjFetch`, `viaCepFetch`).
+- **APIs do navegador:** `SgInputPassword` usa `crypto.getRandomValues` para gerar senha.
+- **"use client":** todos os arquivos começam com `"use client"`, o que serve ao Next.js App Router.
+
+## Tema e estilos
+
+- O CSS compilado (Tailwind) é **injetado automaticamente** no `<head>` quando o pacote é importado (`ensureSeedgridStylesInjected()` em `src/injectStyles.ts`, chamado no topo de `src/index.ts`). A injeção tem proteção para SSR e para dupla injeção (id `seedgrid-fe-components-styles`). Também existe `@seedgrid/fe-components/style.css` para quem prefere importar o arquivo. **Confirmado**.
+- **Tokens:**
+  - Cores via variáveis CSS do tema: `hsl(var(--primary))`, `--destructive`, `--foreground`, `--muted`, `--border`.
+  - Variáveis específicas de input, com fallback: `--sg-input-bg`, `--sg-input-fg`, `--sg-input-placeholder`, `--sg-input-disabled-bg`, `--sg-input-disabled-fg`.
+
+  O pacote `@seedgrid/fe-theme` aparece só como devDependency. A relação exata entre ele e essas variáveis é **Inferência**.
+- **Customização:**
+  - Props: `className` (no `SgInputText` **substitui** as classes do input), `labelClassName`, `width`, `borderRadius`, `elevation`, `withBorder`, `filled`.
+  - Dark mode do `SgInputDate`: `color-scheme` via `useDarkFlag()`.
+
+## Internacionalização
+
+- **Provider:** textos padrão vêm de `useComponentsI18n()` (`src/i18n/index.ts`). Locales embutidos: `pt-BR`, `pt-PT`, `en-US` (alias `en`), `es`, `fr`.
+- **Sem provider:** vale o i18n global, que por padrão é **`en-US`**. Para trocar, use `<SgComponentsI18nProvider locale="pt-BR" messages={…}>` ou `setComponentsI18n(...)`. As mensagens passadas sobrescrevem as embutidas, chave por chave.
+- **Chaves deste grupo:** `components.inputs.*`, `components.password.*`, `components.validators.*` e `components.actions.clear`.
+- **Props `*Message`:** sempre têm precedência sobre a tradução.
+
+**Confirmado**.
+
+## Testes existentes (lidos, **não executados**)
+
+- `tests/inputs-dom.test.mjs` (jsdom) cobre:
+  - `SgInputText` controlado via `inputProps.value` e via RHF;
+  - `onChange` do `SgInputPassword` e o tamanho da senha gerada;
+  - asterisco do `SgInputPhone`;
+  - debounce, `minChars` e "distinct" do `SgInputTextSearch`.
+- `tests/inputs-i18n.test.mjs`: rótulos de acessibilidade do `SgInputOTP`.
+- `tests/rhf.test.mjs` e `tests/rhf-components-contract.test.mjs`: `resolveFieldError`, `mergeRequiredRule` e presença dos caminhos `register`/`control` no `SgInputTextArea`.
+- `tests/i18n-components-contract.test.mjs`: garante que os componentes usam `t(...)` em vez de texto fixo.
+
+O script `test` do pacote roda `pnpm run build` antes.
+
+## Limitações e pontos de atenção
+
+- `SgInputBirthDate` sem `minAge` nem `maxAge` acusa erro de configuração para qualquer data preenchida. **Confirmado**.
+- `SgInputPassword` tem `maxLength` padrão **15**. `SgInputCPF`, `SgInputCNPJ` e `SgInputCPFCNPJ` têm `maxLength` padrão 18. **Confirmado**.
+- `SgInputCPF`, `SgInputCNPJ`, `SgInputCPFCNPJ`, `SgInputPostalCode`, `SgInputDate` e `SgInputBirthDate` não repassam `required` ao `SgInputText`. Consequências:
+  - o rótulo fica sem `*`;
+  - as rules do RHF ficam sem `required` automático (a validação interna continua funcionando).
+
+  `SgInputPhone`, `SgInputEmail` e `SgInputPassword` repassam. **Confirmado** (`required={required}` só aparece nesses três).
+- O erro não é anunciado a leitores de tela no `SgInputText` (sem `aria-invalid`/`aria-describedby`). O `SgToggleSwitch` e o `SgInputOTP` fazem isso. **Confirmado**.
+- Para reagir ao foco, use `onEnter`: o `inputProps.onFocus` não é chamado pelo `SgInputText`. **Confirmado**; ver [[SeedGrid/SeedGrid-components/inputs-texto/API#Contrato base SgInputText|contrato base]].
+- Os tipos de props de `SgInputEmail`, `SgInputPassword`, `SgInputDate` e `SgInputBirthDate` não são reexportados. **Confirmado**.

package/seedgridKB/SeedGrid/SeedGrid-components/navegacao-e-overlay/Exemplos.md

@@ -480,65 +480,65 @@ export default function Example() {
 `apps/showcase/src/app/components/sg-wizard/samples/nextdisabled.tsx.sample`
 
 ```tsx
-import React from "react";
-import { SgInputText, SgWizard, SgWizardPage } from "@seedgrid/fe-components";
-
-/**
- * `nextDisabled` — bloqueio JA conhecido.
- *
- * `onBeforeNext` e `validateStep` so agem no clique: o botao continua com aparencia de habilitado
- * e, quando eles recusam, nada acontece na tela. Quando o consumidor JA sabe que a etapa nao pode
- * avancar — tipicamente o resultado de uma checagem assincrona que ja terminou —, `nextDisabled`
- * deixa isso visivel: botao opaco, cursor de bloqueio e stepper sem oferecer as proximas etapas.
- */
-export default function Example() {
-  const [codigo, setCodigo] = React.useState("");
-  const [checando, setChecando] = React.useState(false);
-  const [jaUsado, setJaUsado] = React.useState(false);
-
-  // Simula a consulta ao servidor ao sair do campo.
-  async function verificarCodigo() {
-    if (!codigo.trim()) return;
-    setChecando(true);
-    await new Promise((resolve) => setTimeout(resolve, 600));
-    setJaUsado(codigo.trim().toUpperCase() === "SG-123");
-    setChecando(false);
-  }
-
-  return (
-    <SgWizard
-      // Durante a consulta o wizard ja desabilita sozinho enquanto aguarda onBeforeNext; aqui o
-      // bloqueio PERMANECE depois que a resposta chegou.
-      nextDisabled={jaUsado}
-      onFinish={() => undefined}
-    >
-      <SgWizardPage title="Convite">
-        <SgInputText
-          id="wizard-codigo-convite"
-          label="Codigo do convite"
-          error={jaUsado ? "Este codigo ja foi utilizado." : undefined}
-          onChange={(value) => {
-            setCodigo(value);
-            setJaUsado(false); // digitou de novo: reabre o avanco ate a proxima checagem
-          }}
-          onExit={() => void verificarCodigo()}
-        />
-        <p className="mt-2 text-sm text-muted-foreground">
-          {checando
-            ? "Verificando o codigo..."
-            : 'Digite "SG-123" e saia do campo: o botao Proximo fica desabilitado.'}
-        </p>
-      </SgWizardPage>
-      <SgWizardPage title="Conclusao">
-        <div className="rounded border border-border bg-foreground/5 p-4">
-          <div className="text-sm font-semibold">Codigo aceito</div>
-          <p className="mt-1 text-sm text-muted-foreground">
-            So se chega aqui com um codigo que a checagem liberou.
-          </p>
-        </div>
-      </SgWizardPage>
-    </SgWizard>
-  );
+import React from "react";
+import { SgInputText, SgWizard, SgWizardPage } from "@seedgrid/fe-components";
+
+/**
+ * `nextDisabled` — bloqueio JA conhecido.
+ *
+ * `onBeforeNext` e `validateStep` so agem no clique: o botao continua com aparencia de habilitado
+ * e, quando eles recusam, nada acontece na tela. Quando o consumidor JA sabe que a etapa nao pode
+ * avancar — tipicamente o resultado de uma checagem assincrona que ja terminou —, `nextDisabled`
+ * deixa isso visivel: botao opaco, cursor de bloqueio e stepper sem oferecer as proximas etapas.
+ */
+export default function Example() {
+  const [codigo, setCodigo] = React.useState("");
+  const [checando, setChecando] = React.useState(false);
+  const [jaUsado, setJaUsado] = React.useState(false);
+
+  // Simula a consulta ao servidor ao sair do campo.
+  async function verificarCodigo() {
+    if (!codigo.trim()) return;
+    setChecando(true);
+    await new Promise((resolve) => setTimeout(resolve, 600));
+    setJaUsado(codigo.trim().toUpperCase() === "SG-123");
+    setChecando(false);
+  }
+
+  return (
+    <SgWizard
+      // Durante a consulta o wizard ja desabilita sozinho enquanto aguarda onBeforeNext; aqui o
+      // bloqueio PERMANECE depois que a resposta chegou.
+      nextDisabled={jaUsado}
+      onFinish={() => undefined}
+    >
+      <SgWizardPage title="Convite">
+        <SgInputText
+          id="wizard-codigo-convite"
+          label="Codigo do convite"
+          error={jaUsado ? "Este codigo ja foi utilizado." : undefined}
+          onChange={(value) => {
+            setCodigo(value);
+            setJaUsado(false); // digitou de novo: reabre o avanco ate a proxima checagem
+          }}
+          onExit={() => void verificarCodigo()}
+        />
+        <p className="mt-2 text-sm text-muted-foreground">
+          {checando
+            ? "Verificando o codigo..."
+            : 'Digite "SG-123" e saia do campo: o botao Proximo fica desabilitado.'}
+        </p>
+      </SgWizardPage>
+      <SgWizardPage title="Conclusao">
+        <div className="rounded border border-border bg-foreground/5 p-4">
+          <div className="text-sm font-semibold">Codigo aceito</div>
+          <p className="mt-1 text-sm text-muted-foreground">
+            So se chega aqui com um codigo que a checagem liberou.
+          </p>
+        </div>
+      </SgWizardPage>
+    </SgWizard>
+  );
 }
 ```
 

package/seedgridKB/SeedGrid/Toolkit/agents/arquiteto.md

@@ -2,7 +2,7 @@
 id: arquiteto
 description: Porta de entrada de toda tarefa não trivial - classifica (feature, bug, hotfix, refactor), faz as perguntas que tirem as dúvidas e entrega o plano com tarefas, paralelismo e critérios de aceite.
 capabilities: [read-files]
-preferred_skills: [planejar-mudanca]
+preferred_skills: [sg-plan-change]
 ---
 
 # Arquiteto

package/seedgridKB/SeedGrid/Toolkit/agents/backend-java.md

@@ -2,7 +2,7 @@
 id: backend-java
 description: Implementa APIs Java, regras de negócio e persistência quando a tarefa altera o backend.
 capabilities: [read-files, edit-files, run-checks]
-preferred_skills: [seedgrid-backend-crud, validar-mudanca]
+preferred_skills: [sg-crud-back, sg-validate-change]
 ---
 
 # Backend Java
@@ -26,7 +26,7 @@ Implementar mudanças no backend Java com código coerente com o projeto, testes
 
 - Seguir `.ai/rules/backend-java-seedgrid.md` (estrutura, injeção por construtor, `BaseEntity`/`publicId`, Flyway, testes).
 - **Usar as extensions SeedGrid para acelerar**: antes de escrever autenticação, permissões, auditoria, notificação, billing, cache, storage ou criptografia, consulte o índice da KB (`.ai/brain/SeedGrid/Extensions/Indice.md`) e use a extension que já cobre a necessidade, configurada pelas propriedades documentadas. Só escreva código próprio quando nenhuma cobrir, e diga isso na entrega.
-- **LGPD**: dado pessoal (CPF, CNPJ de pessoa física, telefone, e-mail, endereço, data de nascimento) segue o `seedgrid-privacy`: `@EncryptedField` (com `searchField` quando precisar buscar) e mascaramento nas saídas de auditoria, log e API (`@PersonalData`/`@MaskRule`). Cadastro novo usa a skill `seedgrid-backend-crud`.
+- **LGPD**: dado pessoal (CPF, CNPJ de pessoa física, telefone, e-mail, endereço, data de nascimento) segue o `seedgrid-privacy`: `@EncryptedField` (com `searchField` quando precisar buscar) e mascaramento nas saídas de auditoria, log e API (`@PersonalData`/`@MaskRule`). Cadastro novo usa a skill `sg-crud-back`.
 - **Auditoria**: operações de criação, alteração e exclusão de entidades de negócio usam `@Audit` (extension `audit`).
 - Seguir o framework, a estrutura de pacotes e as convenções já usadas no projeto; descobri-las lendo o código.
 - Manter compatibilidade de contratos públicos, salvo decisão explícita em contrário.

package/seedgridKB/SeedGrid/Toolkit/agents/backend-rust.md

@@ -2,7 +2,7 @@
 id: backend-rust
 description: Implementa APIs, regras de negócio e persistência em Rust com os crates SeedGrid (portes das extensions Java) quando a tarefa altera um backend Rust.
 capabilities: [read-files, edit-files, run-checks]
-preferred_skills: [validar-mudanca]
+preferred_skills: [sg-validate-change]
 ---
 
 # Backend Rust

package/seedgridKB/SeedGrid/Toolkit/agents/frontend-react.md

@@ -2,7 +2,7 @@
 id: frontend-react
 description: Implementa telas, componentes e integração com APIs em React quando a tarefa altera o frontend.
 capabilities: [read-files, edit-files, run-checks]
-preferred_skills: [seedgrid-crud, seedgrid-new-screen, validar-mudanca]
+preferred_skills: [sg-crud-front, sg-new-screen, sg-validate-change]
 ---
 
 # Frontend React

package/seedgridKB/SeedGrid/Toolkit/agents/qa.md

@@ -2,7 +2,7 @@
 id: qa
 description: Garante a qualidade da entrega - cria e executa testes (unitários, integração, regressão) a partir dos critérios de aceite e valida cada critério com evidência executada.
 capabilities: [read-files, edit-files, run-checks]
-preferred_skills: [validar-mudanca]
+preferred_skills: [sg-validate-change]
 ---
 
 # QA
@@ -31,7 +31,7 @@ Provar, com testes escritos e executados, que a mudança atende aos critérios d
 - Executar build, lint, testes afetados e a suíte relevante; exercitar o comportamento alterado quando possível.
 - Registrar comandos, resultados e evidências no formato do relatório de validação (`.ai/templates/relatorio-validacao.md`).
 - Diferenciar "passou", "falhou" e "não executado (motivo)". Teste instável é repetido uma vez e relatado, nunca ocultado.
-- Conferir que o código segue o padrão SeedGrid quando a tarefa pedir (skill `seedgrid-review`).
+- Conferir que o código segue o padrão SeedGrid quando a tarefa pedir (skill `sg-review`).
 
 ## Limites
 

package/seedgridKB/SeedGrid/Toolkit/agents/revisor.md

@@ -2,7 +2,7 @@
 id: revisor
 description: Revisa mudanças de código procurando defeitos, riscos de segurança e desvios das convenções antes da entrega.
 capabilities: [read-files, run-checks]
-preferred_skills: [revisar-codigo, seedgrid-review]
+preferred_skills: [sg-code-review, sg-review]
 ---
 
 # Revisor
@@ -28,7 +28,7 @@ Encontrar problemas reais na mudança antes que ela seja entregue, com achados v
 - Procurar defeitos de lógica, casos de borda, tratamento de erro, segurança, concorrência, compatibilidade e testes ausentes.
 - Classificar cada achado (bloqueante, importante, sugestão) com arquivo, linha e cenário concreto de falha.
 - Descartar achados que não consegue sustentar com um cenário concreto.
-- Conferir o padrão SeedGrid do que foi alterado (skill `seedgrid-review`): componentes e regras `FE-nn`, `BE-nn`.
+- Conferir o padrão SeedGrid do que foi alterado (skill `sg-review`): componentes e regras `FE-nn`, `BE-nn`.
 
 ## Limites
 

package/seedgridKB/SeedGrid/Toolkit/references/fluxo-de-trabalho.md

@@ -69,10 +69,10 @@ flowchart TD
 
 ## Manutenção (chore)
 
-Bump de versão do projeto, atualização de configuração e tarefas parecidas vão direto para a skill adequada (por exemplo `seedgrid-bump`), sem plano; o `qa` confere build e testes ao final.
+Bump de versão do projeto, atualização de configuração e tarefas parecidas vão direto para a skill adequada (por exemplo `sg-bump`), sem plano; o `qa` confere build e testes ao final.
 
 ## Skills que os papéis usam
 
-- `planejar-mudanca` (arquiteto), `validar-mudanca` (qa), `revisar-codigo` e `seedgrid-review` (revisor).
-- `seedgrid-backend-crud` (backend-java), `seedgrid-crud` e `seedgrid-new-screen` (frontend-react), `seedgrid-bump` (versão do projeto).
+- `sg-plan-change` (arquiteto), `sg-validate-change` (qa), `sg-code-review` e `sg-review` (revisor).
+- `sg-crud-back` (backend-java), `sg-crud-front` e `sg-new-screen` (frontend-react), `sg-bump` (versão do projeto).
 - A lista completa, com o que cada skill faz, está em `.ai/skills/index.md`.

package/seedgridKB/SeedGrid/Toolkit/rules/backend-java-seedgrid.md

@@ -3,7 +3,7 @@ description: "Padrões obrigatórios do back-end Java SeedGrid: estrutura de pas
 ---
 # Padrões do back-end Java SeedGrid
 
-Regras **obrigatórias** para novos projetos e bibliotecas SeedGrid. Cada regra tem um id (`BE-nn`) para citar em revisões (`seedgrid-review`). Para as extensions existentes (propriedades, enums, exemplos), consulte a KB: comece por `.ai/brain/SeedGrid/Extensions/Indice.md`.
+Regras **obrigatórias** para novos projetos e bibliotecas SeedGrid. Cada regra tem um id (`BE-nn`) para citar em revisões (`sg-review`). Para as extensions existentes (propriedades, enums, exemplos), consulte a KB: comece por `.ai/brain/SeedGrid/Extensions/Indice.md`.
 
 ## Estrutura e nomes
 
@@ -47,7 +47,7 @@ Regras **obrigatórias** para novos projetos e bibliotecas SeedGrid. Cada regra
 - **BE-63.** Dado pessoal **não** vai em claro para auditoria, log, exportação ou resposta de erro: use `@PersonalData`/`@MaskRule` (e `remove = true` para senha e segredos).
 - **BE-64.** Criação, alteração e exclusão de entidades de negócio são auditadas com `@Audit` (`entityFqcn`, `operation`, `description`) no método de serviço, dentro de `@Transactional`.
 - **BE-65.** Endpoints protegidos com as anotações de segurança do Quarkus (`@Authenticated`, `@RolesAllowed`, `@PermissionsAllowed`) e permissões registradas conforme a extension `security`; a UI esconder um botão não substitui a checagem no back.
-- **BE-66.** Cadastros novos seguem a skill `seedgrid-backend-crud`.
+- **BE-66.** Cadastros novos seguem a skill `sg-crud-back`.
 
 ## Ao terminar
 

package/seedgridKB/SeedGrid/Toolkit/rules/coordenacao.md

@@ -36,4 +36,4 @@ Se o projeto exigir um fluxo obrigatório (por exemplo, revisão antes de todo c
 
 ## Artefatos
 
-Os templates em `.ai/templates/` são modelos distribuídos pelo toolkit. Especificações, decisões e relatórios produzidos em tarefas reais pertencem ao projeto: salve-os onde o projeto definir (por exemplo, `docs/`), nunca dentro de `.ai/templates/`, `.ai/agents/` ou `.ai/rules/`, que são gerenciados e podem ser atualizados.
+Os templates em `.ai/templates/` são modelos distribuídos pelo toolkit. Planos, handoffs, decisões, especificações e relatórios produzidos em tarefas reais são salvos em `.ai/docs/<tipo>/`, conforme [documentos](documentos.md), nunca dentro de `.ai/templates/`, `.ai/agents/` ou `.ai/rules/`, que são gerenciados e podem ser atualizados.

package/seedgridKB/SeedGrid/Toolkit/rules/documentos.md

@@ -0,0 +1,26 @@
+---
+description: "Onde salvar os documentos que a IA gera (planos, handoff, decisões, relatórios, especificações): sempre em .ai/docs/<tipo>/. Leia antes de criar qualquer arquivo .md de trabalho."
+---
+# Documentos gerados pela IA
+
+Todo documento de trabalho que a IA produzir (plano, handoff, decisão, especificação, relatório, análise, anotações de sessão) é salvo em **`.ai/docs/<tipo>/`**, nunca na raiz do projeto, em `docs/` do projeto ou dentro de `.ai/rules/`, `.ai/agents/`, `.ai/templates/` e `.ai/skills/`, que o toolkit gerencia e reescreve no `update`.
+
+## Pastas por tipo
+
+| Tipo | Pasta | Quando |
+| --- | --- | --- |
+| Plano | `.ai/docs/plans/` | Plano de uma mudança, aprovado ou não, antes de implementar |
+| Handoff | `.ai/docs/handoff/` | Estado e próximos passos para outra sessão, papel ou pessoa continuar |
+| Decisão | `.ai/docs/decisions/` | Decisão de arquitetura e o porquê (modelo: `decisao-arquitetura.md`) |
+| Especificação | `.ai/docs/specs/` | Especificação de tarefa (modelo: `especificacao-tarefa.md`) |
+| Validação | `.ai/docs/reports/` | Relatórios de validação, revisão e testes (modelo: `relatorio-validacao.md`) |
+| Outros | `.ai/docs/<assunto>/` | Qualquer outro documento; crie a pasta com um nome curto no plural |
+
+## Convenções
+
+- Crie a pasta quando precisar. O toolkit não a cria nem a altera: o conteúdo é do projeto e sobrevive ao `update` e ao `remove`.
+- Nome do arquivo: `AAAA-MM-DD-assunto-curto.md` (minúsculas, hífens, sem acentos), por exemplo `2026-10-15-crud-clientes.md`.
+- Comece com um título e uma linha de contexto (tarefa, autor/papel, data). Não grave segredos, tokens nem dados pessoais.
+- Antes de criar, veja se já existe documento do mesmo assunto na pasta e atualize-o em vez de duplicar.
+- Ao citar um documento em outro, use caminho relativo.
+- Versionar ou não é decisão do projeto: se o time não quiser versionar, ele ignora `.ai/docs/` no Git.

package/seedgridKB/SeedGrid/Toolkit/rules/frontend-seedgrid.md

@@ -3,7 +3,7 @@ description: "Padrões obrigatórios do front-end SeedGrid: usar sempre os compo
 ---
 # Padrões do front-end SeedGrid
 
-Regras **obrigatórias** para telas React que usam `@seedgrid/fe-components`. Cada regra tem um id (`FE-nn`) para citar em revisões (`seedgrid-review`). Para detalhes de props e exemplos, consulte a KB: comece por `.ai/brain/SeedGrid/SeedGrid-components/Indice.md` e abra só a nota do grupo necessário.
+Regras **obrigatórias** para telas React que usam `@seedgrid/fe-components`. Cada regra tem um id (`FE-nn`) para citar em revisões (`sg-review`). Para detalhes de props e exemplos, consulte a KB: comece por `.ai/brain/SeedGrid/SeedGrid-components/Indice.md` e abra só a nota do grupo necessário.
 
 ## Componentes SeedGrid primeiro
 
@@ -44,4 +44,4 @@ Nunca use `SgInputText` (nem `<input>` com máscara própria) para um dado que t
 
 ## CRUDs
 
-Telas de cadastro seguem a skill `seedgrid-crud` (páginas `*_list` e `*_edit`, `publicId` nas URLs, proxy em `app/api/...`). Nunca exponha o `id` numérico ao navegador quando houver `publicId`.
+Telas de cadastro seguem a skill `sg-crud-front` (páginas `*_list` e `*_edit`, `publicId` nas URLs, proxy em `app/api/...`). Nunca exponha o `id` numérico ao navegador quando houver `publicId`.

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-bump → sg-bump}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: seedgrid-bump
+name: sg-bump
 description: Sobe a versão do projeto inteiro de uma vez, mantendo a mesma versão no back (pom.xml) e em todos os apps de front (package.json), e no que mais a exibir. Use quando pedirem bump, nova versão ou release do projeto (patch, minor, major ou uma versão informada). Não altera dependências.
 metadata:
   toolkit: seedgrid-ai

package/seedgridKB/SeedGrid/Toolkit/skills/{revisar-codigo → sg-code-review}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: revisar-codigo
+name: sg-code-review
 description: Revisa um diff ou conjunto de arquivos alterados procurando defeitos de lógica, segurança, tratamento de erros, compatibilidade e testes ausentes, com achados priorizados e cenário concreto de falha. Use após implementar uma mudança substancial ou quando pedirem revisão de código.
 metadata:
   toolkit: seedgrid-ai

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-backend-crud → sg-crud-back}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: seedgrid-backend-crud
+name: sg-crud-back
 description: Cria ou padroniza um CRUD de back-end Java com as extensions SeedGrid - entidade com BaseEntity e publicId, migration Flyway, campos pessoais cifrados com seedgrid-privacy (LGPD), auditoria com @Audit, permissões, controller com RestControllerPath, DTOs e testes. Use ao criar uma entidade nova com API, ou ao adicionar campo pessoal, auditoria ou permissão a um cadastro existente.
 metadata:
   toolkit: seedgrid-ai
@@ -25,5 +25,5 @@ Monta um cadastro completo no padrão `.ai/rules/backend-java-seedgrid.md` (regr
 ## Cuidados
 
 - Cifra de campo é opt-in: exige `seedgrid.privacy.encryption.enabled=true`, `seedgrid.privacy.crypto.key` e `seedgrid.privacy.search.key` fornecidos por variável de ambiente ou segredo, nunca versionados (BE-62). Sem a chave configurada, a leitura de valor já cifrado falha.
-- A tela correspondente segue a skill `seedgrid-crud`; menu e permissão da tela, a `seedgrid-new-screen`.
-- Para conferir o resultado contra o padrão, use `seedgrid-review back`.
+- A tela correspondente segue a skill `sg-crud-front`; menu e permissão da tela, a `sg-new-screen`.
+- Para conferir o resultado contra o padrão, use `sg-review back`.

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-crud → sg-crud-front}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: seedgrid-crud
+name: sg-crud-front
 description: Create or refactor SeedGrid CRUD flows in a Next.js app built on the SeedGrid boilerplate, using the project standard of separate `*_list` and `*_edit` pages, `publicId` routing, Next API proxy routes, and SeedGrid components. Use when you need to build or standardize an entity CRUD (users, roles, plans, API keys, audit screens, etc.) with `SgDatatable`, `SgInputTextSearch`, permissions, user-facing copy, and menu/breadcrumb integration.
 ---
 
@@ -13,7 +13,7 @@ Read the existing screens of the project before writing a new one and copy their
 hooks, helpers). The names below (`Shell`, `useSavedToast`, `ListLoadError`, `adminProxyClient`, ...)
 are the boilerplate's own; if the project names them differently, use the project's equivalents.
 
-To register the menu item, icon and permission of a new screen, use the `seedgrid-new-screen` skill.
+To register the menu item, icon and permission of a new screen, use the `sg-new-screen` skill.
 
 ## Workflow
 

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-crud → sg-crud-front}/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "SeedGrid CRUD"
   short_description: "Padrao CRUD SeedGrid"
-  default_prompt: "Use $seedgrid-crud to create a SeedGrid CRUD with list/edit pages, publicId routing, and SgInputTextSearch."
+  default_prompt: "Use $sg-crud-front to create a SeedGrid CRUD with list/edit pages, publicId routing, and SgInputTextSearch."

package/seedgridKB/SeedGrid/Toolkit/skills/{seedgrid-crud → sg-crud-front}/references/routing.md

@@ -63,4 +63,4 @@ Resources behind a CRUD should:
 - Menu item should point to the real list route
 - Breadcrumb items must use valid `href` values
 - Parent sections like `/security` must resolve to a real child route if there is no standalone page
-- Registering the menu item, icon and permission is covered by the `seedgrid-new-screen` skill
+- Registering the menu item, icon and permission is covered by the `sg-new-screen` skill