@seedgrid/ai-toolkit 0.3.2 → 0.3.3

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

@@ -0,0 +1,105 @@
+---
+tags: [seedgrid, produto, pulse, servidor, instalacao, deploy]
+fonte: seedgrid-products/seedgrid-pulse/backend
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse (servidor) — instalação e execução
+
+O **servidor Pulse** é o backend Rust (Axum): API REST, WebSocket, entrega, retry, DLQ, presença e módulos de plataforma. A UI é outro componente: [[SeedGrid/Produtos/Pulse/UI/Visao-geral|Pulse UI]].
+
+Voltar: [[SeedGrid/Produtos/Pulse/Visao-geral|Visão geral]] · variáveis: [[SeedGrid/Produtos/Pulse/Servidor/Configuracao|Configuração do servidor]] · brokers: [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers (Redis, Valkey, Dragonfly, NATS, RabbitMQ)]]
+
+## Modos de execução
+
+| Modo | Quando | Persistência |
+|---|---|---|
+| **Memória** (sem `POSTGRES_URL`) | desenvolvimento rápido, testes | nenhuma; plataforma (login, audit, apikeys) **desabilitada** — só o núcleo realtime |
+| **Postgres** | produção de instância única | mensagens, contas, usuários, audit |
+| **Distribuído** | várias réplicas | Postgres + broker pub/sub + presença em Redis |
+
+Exemplos de `env` (Confirmado — `backend/README.md`):
+
+```env
+# simples
+BROKER_PROVIDER=memory
+PRESENCE_BACKEND=memory
+DELIVERY_STORE_BACKEND=memory
+
+# com Postgres
+DELIVERY_STORE_BACKEND=postgres
+POSTGRES_URL=postgres://<user>:<senha>@<host>:5432/<db>
+
+# distribuído
+BROKER_PROVIDER=redis
+PRESENCE_BACKEND=redis
+DELIVERY_STORE_BACKEND=postgres
+BROKER_REDIS_URL=redis://<host>:6379/0
+```
+
+## Subir com Docker/Podman Compose
+
+Em `backend/`:
+
+```bash
+docker compose up -d --build
+```
+
+Sobe `postgres`, `redis`, `seedgrid-pulse`, `prometheus`, `grafana` e `seedgrid-pulse-ui`. Portas locais (Confirmado — `docker-compose.yml`): API `18080`, Prometheus `19090`, Grafana `13001`, UI `13000`.
+
+O compose de desenvolvimento traz valores de exemplo (chave de servidor, segredo do token, admin inicial). **Troque todos** em qualquer ambiente real. 🔒
+
+## Rodar a partir do fonte
+
+Pré-requisitos: Rust estável recente (edition 2024) e o repositório de crates da plataforma clonado ao lado (path dependencies).
+
+```text
+<raiz>/
+├─ seedgrid-platform/rust/              # crates seedgrid-rust-crate-*
+└─ seedgrid-products/seedgrid-pulse/    # este repo
+```
+
+O prefixo `../../../seedgrid-platform/rust/` está em `backend/Cargo.toml`; ajuste-o se o layout for outro.
+
+```bash
+cd backend
+docker compose up -d postgres redis
+cargo run
+```
+
+O build não precisa de banco (não há `sqlx::query!` verificada em compilação).
+
+## Primeiro acesso
+
+Com `POSTGRES_URL` e o par RSA do JWT, o boot roda as migrations e cria a company da plataforma e o **primeiro admin** a partir de `SEEDGRID_SECURITY_FIRST_ADMIN_USER_*` e `SEEDGRID_SECURITY_DEFAULT_COMPANY_*` ([[SeedGrid/Produtos/Pulse/Servidor/Configuracao|Configuração]]). Entre na UI com esse admin, crie a **conta** do seu produto e as **chaves** (Contas → conta → Chaves → Nova chave). O segredo da chave aparece **uma única vez**.
+
+Par RSA do JWT (exemplo):
+
+```bash
+openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private.pem
+openssl rsa -pubout -in private.pem -out public.pem
+```
+
+Aponte `SECURITY_PRIVATE_KEY_LOCATION` / `SECURITY_PUBLIC_KEY_LOCATION` (ou use PEM inline).
+
+## Imagem e deploy
+
+- Imagem no GHCR: `ghcr.io/seedgrid/seedgrid-pulse-backend` (Confirmado — `.github/workflows/deploy.yml`).
+- `push` em `main` dispara o workflow, que detecta o que mudou, publica a imagem e chama o webhook do EasyPanel (secret `EASYPANEL_DEPLOY_URL_PULSE_BACKEND`). Commit só de documentação **não** redeploya.
+- O container escuta `8080`; use `HTTP_HOST=0.0.0.0` em container.
+- Probes: liveness `GET /health`, readiness `GET /ready` (200/503 com o estado de store, broker e presença).
+- Migrations rodam no boot (`POSTGRES_RUN_MIGRATIONS`, padrão `true`).
+
+## Checklist de produção
+
+- [ ] `POSTGRES_URL` + `DELIVERY_STORE_BACKEND=postgres`.
+- [ ] Mais de uma réplica ⇒ broker pub/sub (`redis`, ou `nats`/`rabbitmq` — ver [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers]]) **e** `PRESENCE_BACKEND=redis`.
+- [ ] `SEEDGRID_PULSE_SERVER_KEY` e `SEEDGRID_PULSE_CONNECT_TOKEN_SECRET` longos e aleatórios, só em ENV. 🔒
+- [ ] `SEEDGRID_PULSE_PUBLIC_WS_URL` com o endereço público do WebSocket (`wss://…`), se há clientes de navegador.
+- [ ] `CORS_ALLOWED_ORIGINS` com a origem da UI.
+- [ ] Par RSA do JWT próprio; admin inicial trocado.
+- [ ] `SEEDGRID_SHOW_DEV_MESSAGE` desligado (padrão).
+- [ ] Proxy reverso **não** repassa `x-seedgrid-company-id` / `x-seedgrid-all-companies` vindos do cliente.
+- [ ] Retenção do histórico decidida (padrão: nunca apagar) — [[SeedGrid/Produtos/Pulse/Servidor/Operacao|Operação]].

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

@@ -0,0 +1,86 @@
+---
+tags: [seedgrid, produto, pulse, servidor, operacao, lixeira, retencao]
+fonte: seedgrid-products/seedgrid-pulse/backend (docs/LIXEIRA-mensagens-e-contas.md, README.md)
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse (servidor) — operação
+
+Lixeira, retenção, auditoria, observabilidade e escala. Voltar: [[SeedGrid/Produtos/Pulse/Visao-geral|Visão geral]] · variáveis: [[SeedGrid/Produtos/Pulse/Servidor/Configuracao|Configuração]].
+
+## Princípios
+
+- O **histórico de entregas é prova**: por padrão **nunca é apagado sozinho**.
+- Apagar é **sempre ação humana**, com permission própria, confirmação na UI e **audit** (quem, o quê, quantos).
+- A chave de servidor **não apaga nada** (401): toda exclusão tem um autor.
+
+## Lixeira de mensagens
+
+- **Só mensagens `pending`** podem ir para a lixeira (mensagens entregues/processadas são histórico; só saem com a exclusão da conta).
+- Na UI: **Mensagens**, filtro de status **"Na lixeira"**. Mover (`PULSE_MESSAGE_DELETE`), restaurar (volta a `pending`) e limpar de vez (`PULSE_MESSAGE_PURGE`, apaga também as entregas por destinatário).
+- API: `POST /api/v1/messages/trash` · `/trash/restore` · `/trash/purge`, lote de até **1000** ids (`400 BATCH_TOO_LARGE`), resposta `{requested, affected, skipped}`.
+- Mensagem na lixeira não é entregue, não expira por TTL e some das listas padrão.
+- **Descartar** (tela Pendências, `PULSE_BACKLOG_DISCARD`) e **Lixeira** coexistem como ações distintas; só a lixeira tem restaurar e limpar de vez.
+- Tarefas `delivered` sem `result` e sem prazo de execução (as anteriores ao Pulse 0.3.0, ou quando `resultTimeoutSeconds` não foi usado) só saem por **descarte**; veja [[SeedGrid/Produtos/Pulse/Protocolo-e-API#Prazo de execução (resultTimeoutSeconds)|Prazo de execução]].
+
+## Lixeira de contas
+
+- A lixeirinha da lista de contas pede confirmação e leva a conta para `pending_delete` (`PULSE_ACCOUNT_DELETE`). A conta **deixa de autenticar** e suas conexões são derrubadas.
+- **Lixeira de contas** (menu): restaurar (volta ao status anterior) ou **apagar definitivamente** (`PULSE_ACCOUNT_PURGE`), que remove a conta, suas chaves e **todas as suas mensagens** em cascata. O diálogo mostra antes quantas chaves e mensagens saem (`GET /accounts/{id}/deletion-summary`).
+- O apagar definitivo **não é uma transação única**: mensagens primeiro, conta por último. Se falhar no meio, a conta continua na lixeira e dá para repetir.
+
+## Retenção e limpeza automática
+
+| Variável | Padrão | Efeito |
+|---|---|---|
+| `DELIVERY_CLEANUP_RETENTION_DAYS` | `0` | Dias que uma mensagem **final** (`completed`/`dead_letter`/`expired`) é mantida. `0` = **nunca apaga**. |
+| `DELIVERY_TRASH_AUTO_CLEAN_DAYS` | `0` | Dias na lixeira antes de apagar sozinho. `0` = só manual. Cada limpeza vai ao audit como `system:pulse`. |
+
+As duas **não se sobrepõem**: a primeira atua no histórico (estados finais), a segunda na lixeira (`trashed`). Mensagens `pending` e `delivered` nunca são limpas pela retenção. A obsoleta `DELIVERY_CLEANUP_RETENTION_SECONDS` só vale se a de dias não existir. Ambas são editáveis em **Configurações**, sem redeploy.
+
+> **Mudança de comportamento (2026-10-15):** o padrão era 7 dias e `0` apagava tudo. Ambientes que definem a variável explicitamente (EasyPanel) mantêm o valor definido.
+
+Sem consumidor, uma `pending` não fica para sempre: o TTL (`DELIVERY_TTL_SECONDS`, 1 dia) a expira.
+
+## Ordem das listas e paginação
+
+As telas listam **da mais recente para a mais antiga** (quem acabou de publicar vê a sua primeira): contas por `created_at`, mensagens por `published_at` e entregas por destinatário por `delivered_at`, todas **com desempate por id**. A paginação é 1-based (`page`, `pageSize`; a Auditoria usa `page`/`size` e o backend dela é base 0, convertido pela UI). Até o Pulse 0.2.1 a lista de contas ordenava sem desempate, e contas criadas no mesmo segundo repetiam ou sumiam entre páginas (corrigido no 0.2.2). O **replay** e as pendências devidas continuam em ordem cronológica (do mais antigo ao mais novo), porque entregar na ordem de publicação é o comportamento certo (Confirmado em `delivery/repo.rs`).
+
+## Auditoria
+
+Toda operação destrutiva (mover para lixeira, restaurar, limpar; contas e mensagens) grava em `audit_log` o autor (claim `sub` do JWT, e-mail na descrição), a ação e as contagens, **somente se algo mudou**. Visível em **Segurança → Auditoria** (escopo por `company_id`).
+
+## Observabilidade
+
+| O quê | Onde |
+|---|---|
+| Liveness / readiness | `GET /health` · `GET /ready` (200 `READY` / 503 `NOT_READY`, com store, broker e presença) |
+| Métricas | `GET /metrics` (JSON) · `GET /metrics/prometheus` |
+| Dashboards | Prometheus + Grafana no compose (`SeedGrid Pulse Overview`) |
+| Telas | dashboard, conexões, backlog, DLQ, mensagens, entregas por destinatário |
+
+Métricas úteis: `publish_requests_total`, `delivery_attempts_total`, `delivery_success_total`, `delivery_dead_letter_total`, `delivery_expired_total`, `delivery_result_timeout_total` (prazo de execução estourado), `ack_total`, `ws_connections_opened_total`/`_closed_total`, latências `publish_to_deliver_*` e `deliver_to_ack_*`.
+
+## Escala (várias réplicas)
+
+- Estado durável no **Postgres** (`DELIVERY_STORE_BACKEND=postgres`).
+- Entrega entre instâncias via **broker pub/sub** (`BROKER_PROVIDER`) e presença em Redis (`PRESENCE_BACKEND=redis`): ver [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers]].
+- Revogação de credencial atravessa o broker (tópico `pulse.revocations`) e derruba as conexões em **todas** as instâncias.
+- Limites de emissão de token são **por instância**: com N réplicas o efetivo é até N vezes.
+
+## Diagnóstico rápido
+
+| Sintoma | Verifique |
+|---|---|
+| Publicou e ninguém recebeu | `accountId`/conta ativa; `channel` e `event` batem com o `subscribe`; `user` do destino = `subject` da conexão; entrega fica `pending` até alguém conectar |
+| 403 ao publicar | está usando chave `client` ou a chave de servidor; use a `project` |
+| WebSocket 401 | credencial ausente/revogada; token `pct_` vencido antes de conectar |
+| Conexão fecha com `4403` | chave/conta revogada: não reconecte com a mesma credencial |
+| `connect-tokens` 503 | falta `SEEDGRID_PULSE_CONNECT_TOKEN_SECRET` |
+| E-mail/2FA por e-mail não chega | `SECURITY_MAILER_USERNAME`/`_PASSWORD` ausentes (só loga) |
+| Histórico "sumiu" | retenção definida no ambiente (`DELIVERY_CLEANUP_RETENTION_*`) |
+| Réplica B não recebe o que A publicou | broker `memory` em produção multi-réplica |
+
+Testes e CI: `cargo test` (unitários e e2e); com Docker/Podman, `cargo test redis_ -- --ignored`, `postgres_ -- --ignored` e `--test trash_integration -- --ignored --test-threads=1` sobem Postgres/Redis via testcontainers.

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/rules/backend-java-seedgrid.md

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

package/seedgridKB/SeedGrid/Toolkit/skills/sg-code-review/SKILL.md

@@ -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/sg-crud-back/SKILL.md

@@ -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.

package/seedgridKB/SeedGrid/Toolkit/skills/sg-crud-front/SKILL.md

@@ -31,10 +31,10 @@ To register the menu item, icon and permission of a new screen, use the `sg-new-
 
 ## Required Patterns
 
-- Use the list/edit split described in `references/patterns.md`.
-- Use `publicId` routing and proxy conventions from `references/routing.md`.
+- Use the list/edit split described in `references/crud-front-patterns.md`.
+- Use `publicId` routing and proxy conventions from `references/crud-front-routing.md`.
 - Use `SgInputTextSearch` as the standard remote-search input.
-- Use the checklist in `references/checklist.md` before closing the task.
+- Use the checklist in `references/crud-front-checklist.md` before closing the task.
 
 ## Required UI Components
 

package/seedgridKB/SeedGrid/Toolkit/skills/sg-new-screen/SKILL.md

@@ -19,7 +19,7 @@ Nao executar sem o usuario pedir.)
 
 ## Passo a passo
 
-Detalhes e exemplos de codigo de cada passo em `references/steps.md`.
+Detalhes e exemplos de codigo de cada passo em `references/new-screen-steps.md`.
 
 1. **Permissao (backend)** - migration nova em `backend/src/main/resources/db/migration/app/`
    (`V3xxx__<assunto>.sql`, nunca editar uma ja aplicada): `insert into permissions` com o `audience` certo,
@@ -43,7 +43,7 @@ Detalhes e exemplos de codigo de cada passo em `references/steps.md`.
 
 ## Verificacao
 
-Rodar o checklist de `references/checklist.md` antes de encerrar. No minimo:
+Rodar o checklist de `references/new-screen-checklist.md` antes de encerrar. No minimo:
 
 ```bash
 # os dois catalogos do cliente iguais (ignorando fim de linha)