@seedgrid/ai-toolkit 0.3.1 → 0.3.3

package/seedgridKB/SeedGrid/Produtos/Pulse/Servidor/Providers.md

@@ -0,0 +1,121 @@
+---
+tags: [seedgrid, produto, pulse, servidor, broker, redis, valkey, dragonfly, nats, rabbitmq, postgres]
+fonte: seedgrid-products/seedgrid-pulse/backend (src/config.rs, src/broker.rs, tests/) + seedgrid-platform/rust/seedgrid-rust-crate-broker
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse (servidor) — providers: broker, presença e store
+
+O Pulse separa três responsabilidades, cada uma com seu provider. Voltar: [[SeedGrid/Produtos/Pulse/Servidor/Configuracao|Configuração do servidor]] · [[SeedGrid/Produtos/Pulse/Servidor/Instalacao|Instalação]].
+
+| Responsabilidade | Variável | Opções | Para quê |
+|---|---|---|---|
+| **Broker** (pub/sub entre instâncias) | `BROKER_PROVIDER` | `memory`, `redis`, `nats`, `rabbitmq` | levar uma publicação a **todas** as instâncias, para a que tem o WebSocket entregar; e propagar revogação de credencial |
+| **Presença** (quem está conectado em quê) | `PRESENCE_BACKEND` | `memory`, `redis` | presença por canal/grupo compartilhada entre instâncias |
+| **Store de entregas** (mensagens, estados, DLQ) | `DELIVERY_STORE_BACKEND` | `memory`, `postgres` | durabilidade, replay, histórico |
+
+## Quando precisa de quê
+
+| Cenário | Broker | Presença | Store |
+|---|---|---|---|
+| Desenvolvimento / uma instância sem persistência | `memory` | `memory` | `memory` |
+| **Uma instância em produção** | `memory` | `memory` | `postgres` |
+| **Várias réplicas (escala)** | `redis` \| `nats` \| `rabbitmq` | **`redis`** | `postgres` |
+
+- Sem broker compartilhado, uma réplica não entrega o que outra publicou (ver [[SeedGrid/Produtos/Pulse/Servidor/Operacao|Operação — diagnóstico]]).
+- **A presença só tem `memory` e `redis`.** Com NATS ou RabbitMQ como broker em várias réplicas, ainda é preciso um servidor Redis-compatível para `PRESENCE_BACKEND=redis` (Confirmado — `config.rs`).
+- O estado de entrega vive no **Postgres**; o broker é só o barramento. Por isso um broker sem persistência (NATS core) não perde mensagem do Pulse: o replay a recupera do banco.
+
+## Redis e compatíveis (Valkey, Dragonfly, KeyDB…)
+
+Usa pub/sub do protocolo Redis. Variáveis:
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `BROKER_PROVIDER=redis` | | |
+| `BROKER_REDIS_URL` (fallback `REDIS_URL`) | — | `redis://host:6379/0`; use `rediss://` para TLS. 🔒 |
+| `BROKER_REDIS_CHANNEL` (fallback `REDIS_PUBSUB_CHANNEL`) | `seedgrid:pulse:events` | canal pub/sub |
+| `PRESENCE_BACKEND=redis` | | usa a mesma `BROKER_REDIS_URL` |
+
+Como o Pulse só fala o protocolo Redis (cliente `redis` 0.32), qualquer servidor compatível serve — **basta apontar a URL**. Verificado em 2026-10-16 rodando a suíte `redis_integration` (broker pub/sub, presença com expiração/heartbeat e revogação entre instâncias) contra:
+
+| Servidor | Imagem testada | Resultado |
+|---|---|---|
+| Redis | `redis:7.2.4` | 5/5 ✅ |
+| Valkey | `valkey/valkey:8` | 5/5 ✅ |
+| Dragonfly | `docker.dragonflydb.io/dragonflydb/dragonfly:latest` | 5/5 ✅ |
+
+KeyDB e serviços gerenciados (ElastiCache, Memorystore, Upstash…) **não foram testados** aqui; devem funcionar por falarem o mesmo protocolo (Inferência) — rode a suíte antes de adotar.
+
+Para validar outro servidor:
+
+```bash
+SG_PULSE_TEST_REDIS_IMAGE=<imagem>:<tag> \
+DOCKER_HOST='npipe:////./pipe/podman-machine-default' TESTCONTAINERS_RYUK_DISABLED=true \
+cargo test --test redis_integration -- --ignored --test-threads=1
+```
+
+Exemplo de troca (compose): no serviço `redis`, use a imagem `valkey/valkey:8` (ou Dragonfly) e mantenha `BROKER_REDIS_URL=redis://redis:6379/0`; nenhuma outra variável muda.
+
+## NATS
+
+Pub/sub **core** do NATS em um `subject`; cada instância assina o mesmo subject e recebe tudo (fan-out).
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `BROKER_PROVIDER=nats` | | |
+| `BROKER_NATS_URL` (fallback `NATS_URL`) | — | `nats://host:4222`. **Obrigatória.** 🔒 |
+| `BROKER_NATS_SUBJECT` | `seedgrid.pulse.events` | sem espaços nem curingas `*`/`>` |
+| `PRESENCE_BACKEND` | `memory` | `redis` em multi-réplica |
+
+- Entrega **at-most-once**, sem persistência (NATS core). Aceitável porque o estado de entrega está no Postgres e volta pelo replay.
+- Sem reconexão automática do stream do broker (igual ao Redis): se a conexão cair, o stream termina com `warn`. Mantenha supervisão/restart do serviço.
+
+Exemplo:
+
+```env
+BROKER_PROVIDER=nats
+BROKER_NATS_URL=nats://nats:4222
+PRESENCE_BACKEND=redis
+BROKER_REDIS_URL=redis://redis:6379/0
+DELIVERY_STORE_BACKEND=postgres
+POSTGRES_URL=postgres://<user>:<senha>@<host>:5432/<db>
+```
+
+## RabbitMQ
+
+Exchange **fanout** durável declarada no boot; cada instância cria a **própria fila exclusiva e auto-delete**, ligada ao exchange (fan-out entre instâncias).
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `BROKER_PROVIDER=rabbitmq` | | |
+| `BROKER_RABBITMQ_URL` (fallbacks `RABBITMQ_URL`, `AMQP_URL`) | — | `amqp://user:senha@host:5672/%2f` (vhost codificado). **Obrigatória.** 🔒 |
+| `BROKER_RABBITMQ_EXCHANGE` | `seedgrid.pulse.events` | nome do exchange fanout |
+| `PRESENCE_BACKEND` | `memory` | `redis` em multi-réplica |
+
+- `amqps://` (TLS) está habilitado na crate mas **não foi testado**.
+- Sem reconexão automática do broker; filas exclusivas somem quando a instância cai (comportamento desejado no fan-out).
+
+## Memória
+
+`BROKER_PROVIDER=memory` (padrão; valor desconhecido também cai nele): barramento em processo. Só serve para **uma instância**.
+
+## Readiness
+
+`GET /ready` testa store, broker e presença e responde 200 `READY` ou 503 `NOT_READY` com o detalhe por componente. Para NATS e RabbitMQ a sonda é um `ping` com timeout de 5 s.
+
+## Postgres (store de entregas e plataforma)
+
+`POSTGRES_URL` é o interruptor da plataforma (login, audit, apikeys) e `DELIVERY_STORE_BACKEND=postgres` liga a persistência de entregas. As migrations rodam no boot (`POSTGRES_RUN_MIGRATIONS=true`); cada módulo usa a própria tabela de histórico (`_sqlx_migrations_*`). Qualquer Postgres gerenciado serve. Banco único, separação lógica por `company_id`.
+
+## Como foi verificado
+
+| Item | Evidência |
+|---|---|
+| Redis / Valkey / Dragonfly | `tests/redis_integration.rs`, 5/5 por servidor (Podman, testcontainers) |
+| NATS e RabbitMQ | testes de container nas crates `seedgrid-broker-nats`/`-rabbitmq` (fan-out para 3 subscribers em 2 instâncias, payload malformado sem derrubar o stream, `ping`) e `tests/broker_providers_integration.rs` no Pulse (`build_broker` entrega a todos; `/ready` UP) |
+| Postgres | `tests/postgres_integration.rs` |
+
+Código-fonte dos brokers: `seedgrid-platform/rust/seedgrid-rust-crate-broker` (crates `-spi`, `-memory`, `-redis`, `-nats`, `-rabbitmq`); README da crate descreve o contrato `Broker` (`publish`/`subscribe`).

package/seedgridKB/SeedGrid/Produtos/Pulse/UI/Configuracao.md

@@ -0,0 +1,61 @@
+---
+tags: [seedgrid, produto, pulse, ui, configuracao, variaveis]
+fonte: seedgrid-products/seedgrid-pulse/frontend/seedgrid-pulse-ui (.env.example, src/app/layout.tsx)
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse UI — variáveis de ambiente
+
+Variáveis da **UI**. As do servidor estão em [[SeedGrid/Produtos/Pulse/Servidor/Configuracao|Configuração do servidor]]. Lidas em **runtime** (layout `force-dynamic`): no EasyPanel são env do container, sem rebuild. Visão geral: [[SeedGrid/Produtos/Pulse/UI/Visao-geral|Pulse UI]].
+
+## Conexão com o Pulse
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `SEEDGRID_PULSE_SERVER_BASE_URL` | `http://127.0.0.1:18080` (exemplo do `.env.example`) | Base URL da API Pulse **alcançável pelo navegador**. Única informação de conexão entregue ao client. Fallback legado: `NEXT_PUBLIC_PULSE_BASE_URL`. |
+| `SEEDGRID_PULSE_INTERNAL_BASE_URL` | = a anterior | Base URL usada pelo **servidor da UI** nos proxies (`/api/security/*`, `/api/pulse/messages`). Só precisa quando difere (containers na mesma rede, ex.: `http://seedgrid-pulse:8080`). |
+
+Não existe credencial aqui: nem usuário/senha nem chave. As telas autenticam com o JWT do operador logado.
+
+## Aparência e idioma
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `SEEDGRID_PULSE_DEFAULT_THEME_SEED` | `#16803D` | Cor semente do tema. Legado: `NEXT_PUBLIC_DEFAULT_THEME_SEED`. |
+| `SEEDGRID_PULSE_DEFAULT_THEME_MODE` | `light` | `light` ou `dark`. Legado: `NEXT_PUBLIC_DEFAULT_THEME_MODE`. |
+| `SEEDGRID_PULSE_UI_DEFAULT_LOCALE` | `pt-BR` | Idioma padrão: `en`, `pt-BR`, `pt-PT`, `fr`, `es`. Legado: `NEXT_PUBLIC_PULSE_UI_DEFAULT_LOCALE`. |
+
+Os nomes `NEXT_PUBLIC_*` antigos seguem aceitos como fallback para imagens antigas; prefira os `SEEDGRID_PULSE_*`.
+
+## Auto-refresh (polling, em segundos)
+
+Padrão de todos: **30**.
+
+| Variável | Tela |
+|---|---|
+| `NEXT_PUBLIC_DASHBOARD_REFRESH_SECONDS` | dashboard |
+| `NEXT_PUBLIC_CONNECTIONS_REFRESH_SECONDS` | conexões |
+| `NEXT_PUBLIC_MESSAGES_REFRESH_SECONDS` | mensagens |
+| `NEXT_PUBLIC_BACKLOG_REFRESH_SECONDS` | backlog |
+| `NEXT_PUBLIC_DELIVERIES_REFRESH_SECONDS` | entregas |
+| `NEXT_PUBLIC_DLQ_REFRESH_SECONDS` | DLQ |
+
+> **Não confirmado se mudar estes valores tem efeito.** A UI lê cada uma com `process.env[nome]` dinâmico (`src/lib/ui-refresh.ts`); em componente client o Next só substitui acessos estáticos (`process.env.NEXT_PUBLIC_X`) no build. Se o intervalo não mudar após definir a variável, o padrão de 30 s está valendo. Tratar como pendência a verificar antes de contar com este ajuste.
+
+## Exemplo mínimo de produção
+
+```env
+SEEDGRID_PULSE_SERVER_BASE_URL=https://pulse.<seu-dominio>
+SEEDGRID_PULSE_INTERNAL_BASE_URL=http://seedgrid-pulse:8080
+SEEDGRID_PULSE_UI_DEFAULT_LOCALE=pt-BR
+```
+
+No servidor correspondente: `CORS_ALLOWED_ORIGINS=https://pulse-ui.<seu-dominio>`.
+
+## O que NÃO colocar na UI
+
+- `SEEDGRID_PULSE_SERVER_KEY` (chave de servidor) — a UI não a usa e ela não publica.
+- Qualquer chave `project` ou `client`.
+- Usuário/senha de operador em ENV (removido; o login é pela tela).

package/seedgridKB/SeedGrid/Produtos/Pulse/UI/Visao-geral.md

@@ -0,0 +1,74 @@
+---
+tags: [seedgrid, produto, pulse, ui, nextjs]
+fonte: seedgrid-products/seedgrid-pulse/frontend/seedgrid-pulse-ui
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse UI — visão geral, instalação e execução
+
+Painel web **operacional/administrativo** do Pulse (Next.js + React + `@seedgrid/fe-components`). É um componente separado do servidor: tem imagem, deploy e variáveis próprios. Variáveis: [[SeedGrid/Produtos/Pulse/UI/Configuracao|Configuração da UI]]. Servidor: [[SeedGrid/Produtos/Pulse/Servidor/Instalacao|Pulse (servidor)]].
+
+Voltar: [[SeedGrid/Produtos/Pulse/Visao-geral|Visão geral do Pulse]]
+
+## O que a UI faz
+
+| Área | Telas |
+|---|---|
+| Visão operacional | dashboard, conexões ativas, métricas e agregados |
+| Mensagens | listagem (mais recente primeiro), detalhe (entregas por destinatário e tentativas, com o motivo `result_timeout` traduzido), publicação manual (inclui o campo opcional "Prazo de execução (s)"), **lixeira** (filtro "Na lixeira") |
+| Pendências | backlog, descarte |
+| Falhas | DLQ (reprocessar, limpar), lixeira da DLQ |
+| Entregas | entregas por destinatário |
+| Contas | contas, chaves (criar, rotacionar, revogar), **lixeira de contas** |
+| Segurança | usuários, perfis/permissions, auditoria |
+| Configurações | ajustes de entrega em runtime (retry, TTL, retenção, lixeira) |
+
+Idiomas: en, pt-BR, pt-PT, fr, es.
+
+## Como ela autentica
+
+A UI **não guarda credencial de conexão**. As telas usam o **JWT do operador logado** (login do `security`) e cada ação exige a **permission** correspondente (RBAC) — ver [[SeedGrid/Produtos/Pulse/Autenticacao-e-chaves|Autenticação e chaves]]. Antes existiam `NEXT_PUBLIC_PULSE_BASIC_USER/_PASSWORD`; foram removidas porque o Next as embutia no bundle e elas ficavam legíveis no HTML. A tela de publicação publica **como o operador** (`PULSE_MESSAGE_PUBLISH`), não com a chave de servidor.
+
+## Instalação e execução
+
+Requisitos: Node 22 (a imagem usa `node:22-bookworm-slim`; Next 16, React 19).
+
+```bash
+cd frontend/seedgrid-pulse-ui
+npm install
+npm run dev          # http://127.0.0.1:3000
+```
+
+Variáveis em `.env` (copie de `.env.example`). Com o `podman-compose`/`docker compose` da pasta, a UI sobe em `http://127.0.0.1:13000` junto de Pulse, Postgres e Redis.
+
+Qualidade e testes:
+
+```bash
+npm run lint
+npm run build
+npm test                  # unitários (vitest)
+npm run test:integration  # sobe um mock do Pulse com testcontainers
+```
+
+## Imagem e deploy
+
+- Imagem no GHCR: `ghcr.io/seedgrid/seedgrid-pulse-ui` (Confirmado — `.github/workflows/deploy.yml`).
+- `push` em `main` com mudança em `frontend/**` publica a imagem e chama o webhook do EasyPanel (secret `EASYPANEL_DEPLOY_URL_PULSE_UI`).
+- As variáveis são lidas em **runtime** pelo layout (`force-dynamic`): troca-se de ambiente mudando o env do container, **sem rebuild**.
+
+## Rede: dois endereços do mesmo servidor
+
+| Quem acessa | Variável | Exemplo |
+|---|---|---|
+| **Navegador** do operador | `SEEDGRID_PULSE_SERVER_BASE_URL` | `https://pulse.exemplo.com` |
+| **Servidor da UI** (proxies `/api/security/*`, `/api/pulse/messages`) | `SEEDGRID_PULSE_INTERNAL_BASE_URL` | `http://seedgrid-pulse:8080` (mesma rede de containers) |
+
+Se a UI e o servidor estão em containers na mesma rede, defina os dois; o interno é opcional e, ausente, usa o primeiro.
+
+## Atenção
+
+- A UI não deve receber `SEEDGRID_PULSE_SERVER_KEY`: a chave de servidor não publica e não pertence ao serviço da UI.
+- O servidor precisa de `CORS_ALLOWED_ORIGINS` com a origem da UI.
+- Papel `ADMIN` herda as permissions de lixeira (`PULSE_MESSAGE_DELETE/PURGE`, `PULSE_ACCOUNT_DELETE/PURGE`); outros perfis precisam recebê-las para ver os botões.

package/seedgridKB/SeedGrid/Produtos/Pulse/Visao-geral.md

@@ -0,0 +1,96 @@
+---
+tags: [seedgrid, produto, pulse, realtime]
+fonte: seedgrid-products/seedgrid-pulse
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# SeedGrid Pulse — visão geral
+
+Hub **realtime** da plataforma SeedGrid: um produto (servidor Rust + UI Next.js + SDKs) que qualquer sistema SeedGrid usa para **publicar** eventos/comandos por HTTP e **entregar** a clientes conectados por WebSocket, sem reimplementar WebSocket, replay, retry, presença, backlog e isolamento de destino.
+
+> O Pulse é um **produto** (`seedgrid-products/seedgrid-pulse`), não uma extension de `seedgrid-platform`. Ele *consome* crates da plataforma (security, login-tenancy, audit, apikeys); ver [[SeedGrid/Visao-geral|visão geral da plataforma]].
+
+## O que o Pulse resolve
+
+| Necessidade | Como o Pulse atende |
+|---|---|
+| Backend precisa avisar usuário/grupo/conta inteira em tempo real | `POST /api/v1/messages` com a chave `project` |
+| Navegador/app precisa receber, sem segredo no cliente | **token curto** (`pct_…`) emitido pelo backend do produto |
+| Agente instalado na máquina do cliente precisa ficar conectado | chave `client` + WebSocket com reconexão e **replay** |
+| Confirmar recebimento e execução | `ack` (recebimento) e `result` (execução, com retry e DLQ) |
+| Operar: ver conexões, backlog, falhas, apagar com segurança | UI operacional, métricas Prometheus, lixeira e audit |
+
+## Duas funções: mensagens e tarefas
+
+O Pulse faz dois trabalhos diferentes com o mesmo caminho `publisher → Pulse → subscriber`. Quem publica escolhe o trabalho com o `deliveryMode`:
+
+| | **Mensagem** (envio simples) | **Tarefa** (execução) |
+|---|---|---|
+| Para que serve | avisar, notificar, atualizar tela: "o pedido mudou" | mandar alguém **fazer** algo e saber se deu certo: "renderize este relatório" |
+| `deliveryMode` | `notification` (padrão) ou `acknowledged` | `processed` |
+| O que o subscriber devolve | nada (`notification`) ou só o `ack` de recebimento (`acknowledged`) | `ack` e depois o `result`: `success`, `retryable` ou `permanent` |
+| Se a execução falhar | não existe execução: não há o que falhar | retry automático e, esgotado o retry, **DLQ**; se o consumidor travar, o prazo de execução (`resultTimeoutSeconds`, Pulse 0.3.0) conta como falha |
+| Termina quando | o servidor escreve no socket (`notification`) ou o `ack` chega (`acknowledged`) | `result: success` |
+| Pode ir à DLQ | **nunca** | **sim**, e só ela |
+
+Regra prática: se você só precisa que a informação **chegue**, use mensagem. Se precisa que algo seja **executado** e quer ser avisado (e poder reprocessar) quando falhar, use tarefa. Detalhes: [[SeedGrid/Produtos/Pulse/Protocolo-e-API#Delivery modes|Delivery modes]] e [[SeedGrid/Produtos/Pulse/Protocolo-e-API#DLQ: quando uma mensagem vai para lá|DLQ]].
+
+## Peças
+
+| Peça | Onde (no repo) | Tecnologia |
+|---|---|---|
+| Servidor | `backend/` | Rust, Axum, Postgres, Redis opcional |
+| UI operacional | `frontend/seedgrid-pulse-ui/` | Next.js + `@seedgrid/fe-components` |
+| SDKs publisher | `components/publishers/` | Java, Next, Dart, PHP, Rust, Delphi |
+| SDKs subscriber | `components/subscribers/` | React, Angular, Flutter, Rust, Delphi |
+| Exemplos prontos | `examples/` | Delphi VCL, Flutter, React (e Angular) |
+| Harness de integração | `integration/seedgrid-pulse-sdk-it/` | contra Pulse real |
+
+Versão do servidor e da UI na análise: **0.3.0** (Confirmado — `backend/Cargo.toml`, `frontend/seedgrid-pulse-ui/package.json`).
+
+## Modelo mental (3 minutos)
+
+```
+ backend do produto ──(chave project)──▶  POST /api/v1/messages ─┐
+                                                                 ▼
+ navegador/app ◀──WebSocket──  Pulse  ◀── conta (fronteira de isolamento)
+   (token curto)               │  └─ canal › grupo › usuário › evento
+ agente instalado ◀──────────  │
+   (chave client)              └─ pendente? fica guardado e é reentregue (replay)
+```
+
+- **Conta** é a fronteira: entrega e replay nunca cruzam contas.
+- **Credenciais têm papéis distintos** e nunca se substituem — ver [[SeedGrid/Produtos/Pulse/Autenticacao-e-chaves|Autenticação e chaves]].
+- **Delivery mode** escolhe o ciclo de vida: `notification` (padrão), `acknowledged`, `processed` — ver [[SeedGrid/Produtos/Pulse/Protocolo-e-API|Protocolo e API]].
+
+## Mapa desta documentação
+
+**Pulse (servidor)** — o backend Rust, com variáveis próprias:
+- [[SeedGrid/Produtos/Pulse/Servidor/Instalacao|Instalação e execução]]
+- [[SeedGrid/Produtos/Pulse/Servidor/Configuracao|Variáveis de ambiente do servidor]]
+- [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers: Redis, Valkey, Dragonfly, NATS, RabbitMQ, Postgres]]
+- [[SeedGrid/Produtos/Pulse/Servidor/Operacao|Operação: lixeira, retenção, auditoria, métricas, escala]]
+
+**Pulse UI** — o painel Next.js, com variáveis próprias:
+- [[SeedGrid/Produtos/Pulse/UI/Visao-geral|Visão geral, instalação e deploy]]
+- [[SeedGrid/Produtos/Pulse/UI/Configuracao|Variáveis de ambiente da UI]]
+
+**Transversal:**
+- [[SeedGrid/Produtos/Pulse/Autenticacao-e-chaves|Autenticação, chaves, token curto e permissions]]
+- [[SeedGrid/Produtos/Pulse/Protocolo-e-API|Protocolo realtime e API HTTP]]
+- [[SeedGrid/Produtos/Pulse/SDKs|SDKs (publisher e subscriber por linguagem)]]
+- [[SeedGrid/Produtos/Pulse/Exemplos|Exemplos executáveis (Delphi, Flutter, React, Angular)]]
+
+## Como usar o Pulse em um projeto SeedGrid (receita curta)
+
+1. Peça à operação do Pulse uma **conta** para o seu produto e as chaves: uma `project` (backend) e, se houver agentes, `client`.
+2. Guarde a chave `project` **só no backend** (env/secret). Nunca em código de navegador/mobile.
+3. No backend, instale o SDK **publisher** da sua linguagem e publique.
+4. Se o cliente é navegador/app: crie uma rota autenticada no backend que chama `issueConnectToken` com o `subject` **da sessão**; o front usa o SDK **subscriber** com `getToken`.
+5. Defina `channel`/`event` por convenção do produto (ex.: `orders` / `order.updated`) e use o `publicId` do usuário, nunca e-mail.
+
+## Confiabilidade das informações
+
+Conteúdo extraído de `README.md`, `backend/README.md`, `backend/env.md`, `backend/PROTOCOL.md`, `backend/docs/LIXEIRA-mensagens-e-contas.md`, `backend/src/config.rs`, `backend/migrations/` e dos READMEs dos SDKs. Quando algo vem só de documentação (não relido no código nesta análise), a nota diz.

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
 
@@ -11,7 +11,31 @@ Regras **obrigatórias** para novos projetos e bibliotecas SeedGrid. Cada regra
 - **BE-02.** Toda pasta (pacote) no **plural**.
 - **BE-03.** Resources REST terminam em `Controller`, não `Resource` (`ClienteController`).
 - **BE-04.** Use sempre a biblioteca `seedgrid-commons` nos projetos.
-- **BE-05.** DTOs: sufixo `Request` para entrada e `Response` para saída; se o mesmo DTO serve aos dois, sufixo `DTO`. O Request tem só as propriedades necessárias (um update não precisa do `id`). O Response é "raso": ids e descrições em vez de objetos aninhados (`categoriaId`, `categoriaDescricao`).
+- **BE-05.** DTOs: sufixo `DTOReq` para entrada (request) e `DTORes` para saída (response): `ClienteDTOReq`, `ClienteDTORes`.
+  - O **Req** leva só as propriedades necessárias (um update não precisa do `id`) e, para relacionamentos, **somente a chave estrangeira** pelo `publicId` (`cidadePublicId`), nunca campos nem objeto da entidade relacionada. Validações (`@NotNull`, `@Size`...) ficam no próprio record; para exigir os obrigatórios só no POST/PUT, use um grupo `Full extends Default` dentro do record.
+  - O **Res** é **plano** ("plain"): tudo no mesmo nível, sem objetos aninhados. Traz o `publicId` (nunca o `id` interno) e, para cada relacionamento, o `publicId` e a descrição (`cidadePublicId`, `cidadeDescricao`), inclusive os de mais de um nível (`paisPublicId`, `paisDescricao`). Pode existir mais de um Res para a mesma entidade, com menos campos, conforme o uso (por exemplo uma listagem enxuta).
+  - Records Java, na pasta `dtos/` (BE-01).
+
+```java
+public record ClienteDTOReq(
+        @NotNull(groups = ClienteDTOReq.Full.class, message = "Informe o nome.")
+        @Pattern(regexp = ".*\\S.*", message = "Informe o nome.")
+        @Size(max = 255) String nome,
+        @NotNull(groups = ClienteDTOReq.Full.class) String cidadePublicId,
+        @NotNull(groups = ClienteDTOReq.Full.class) String categoriaPublicId
+) {
+    /** Grupo do POST/PUT: exige os obrigatórios. Estende Default para manter @Size e @Pattern. */
+    public interface Full extends Default {}
+}
+
+public record ClienteDTORes(
+        String publicId,
+        String nome,
+        String cidadePublicId, String cidadeDescricao,
+        String paisPublicId, String paisDescricao,
+        String categoriaPublicId, String categoriaDescricao
+) {}
+```
 - **BE-06.** Todo SPI criado é indexado com o `jandex-maven-plugin` (goal `jandex`).
 
 ## Injeção e exceptions
@@ -47,7 +71,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
@@ -13,7 +13,7 @@ Encontre problemas reais e verificáveis; evite comentários de estilo sem impac
 
 1. **Escopo.** Obtenha o diff (por exemplo, `git diff` ou `git diff <base>...HEAD`) e o objetivo da mudança. Sem diff disponível, peça a lista de arquivos alterados.
 2. **Contexto.** Leia o código ao redor de cada trecho alterado e os pontos que o chamam.
-3. **Análise.** Percorra o [checklist](references/checklist.md). Para cada suspeita, construa um cenário concreto: entrada/estado → comportamento errado.
+3. **Análise.** Percorra o [checklist](references/code-review-checklist.md). Para cada suspeita, construa um cenário concreto: entrada/estado → comportamento errado.
 4. **Filtro.** Descarte suspeitas que não sustentam um cenário concreto. Não reporte preferências pessoais como defeitos.
 5. **Verificações somente leitura.** Se útil, rode testes ou lint existentes para confirmar um achado. Não altere arquivos.
 

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
@@ -17,7 +17,7 @@ Monta um cadastro completo no padrão `.ai/rules/backend-java-seedgrid.md` (regr
 4. **Migration Flyway** (BE-20, BE-22, BE-24): tabela com `id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY`, as colunas da base escolhida (`public_id`, `created_at`, `updated_at` como `timestamptz`, `create_user_public_id`, `update_user_public_id`, e `active` só no `BaseEntity`; a lib não traz migrations), colunas cifradas com `VARCHAR(512)` e de hash com `VARCHAR(64)`, e `CREATE UNIQUE INDEX idx_<tabela>_public_id ON <tabela>(public_id)`. A pasta segue `db/migration/<projeto>`.
 5. **Repository** (`repositories/`, JPA puro em libs; Panache só em hosts, BE-21). Busca por campo cifrado usa o hash: `CryptoProvider.getSecureSearch().hashForSearch(valor, <mesma normalização>)`.
 6. **Service** (`services/`, injeção por construtor, BE-10): regras de negócio e exceptions tipadas (BE-11). Criar, alterar e excluir com `@Transactional` e `@Audit(entityFqcn = "...", operation = AuditOperationEnum.CREATE|UPDATE|DELETE, description = "...")` (BE-64). Para UPDATE/DELETE, o repository precisa expor `findByIdOptional` (é por ele que o `@Audit` captura o "antes").
-7. **DTOs** (`dtos/`, BE-05): `...Request` só com o necessário, `...Response` raso, com `publicId` e **sem** `id`. Nada de dado pessoal em claro em respostas de erro ou log.
+7. **DTOs** (`dtos/`, BE-05): `...DTOReq` só com o necessário e relacionamentos apenas pela chave estrangeira (`cidadePublicId`); `...DTORes` plano, com `publicId` e **sem** `id`, e `publicId`+descrição de cada relacionamento (`cidadePublicId`, `cidadeDescricao`, `paisPublicId`...). Nada de dado pessoal em claro em respostas de erro ou log.
 8. **Controller** (`controllers/`, BE-03, BE-31): primeiro acrescente a seção do recurso em `RestControllerPath` (base, `..._BY_PUBLIC_ID`, `..._FULL`; o controller usa base e sub-paths, o teste usa os `_FULL`); `GET` paginado (`page`, `size`, `sortField`, `sortOrder`, com `LIKE` por prefixo, BE-32), `GET` por `publicId`, `POST`, `PUT`, `DELETE`. Proteja com `@PermissionsAllowed("<ENTIDADE>_READ|CREATE|EDIT|DELETE")` (ou `@RolesAllowed`), conforme a extension `security` (BE-65), e registre as permissões como o projeto faz.
 9. **Testes** (BE-40, BE-41): unitário do service e de integração do controller com Testcontainers + PostgreSQL, cobrindo CRUD, validação, permissão negada, **dado pessoal gravado cifrado** (consulta direta na coluna), busca pelo hash e registro de auditoria sem dado pessoal em claro. Vários asserts: `assertAll`.
 10. **Fechar** (BE-50): rode build e testes, remova o que sobrou e liste os TODO.
@@ -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`.