ai: melhoria de arquivos de agentes com novas instruções

Author: mobius1qwe

.agents/AGENT_QUICKSTART.md

@@ -0,0 +1,61 @@
+# AGENT_QUICKSTART (PascalRAL-dev)
+
+Guia mínimo para agentes de IA navegarem o projeto com **baixo consumo de contexto**.
+
+> Regra: quando você terminar uma etapa, volte aqui e escolha o próximo arquivo-alvo. Não “passeie” pelo repo.
+
+---
+
+## 0) Identifique seu objetivo (escolha 1)
+
+1. **Criar/entender rotas e execução no Server** → `src/base/RALRoutes.pas` + `src/base/RALServer.pas`
+2. **Criar/entender Client (como faz requests e decodifica respostas)** → `src/base/RALClient.pas` + `src/engine/*`
+3. **Entender Request/Response/Params (Body, Headers, Query, Answer)** → `src/base/RALParams.pas` + `src/base/RALRequest.pas` + `src/base/RALResponse.pas`
+4. **Multipart (upload/download)** → `src/utils/RALMultipartCoder.pas`
+5. **JSON / Storage (serialização)** → `src/utils/RALJson.pas` + `src/utils/RALStorage*.pas`
+6. **Compress/Cripto/Stream (pipeline de bytes)** → `src/utils/RALStream.pas` + `src/utils/RALCompress*.pas` + `src/utils/RALCripto*.pas`
+7. **DBWare/DBModule (integrar com banco)** → `src/database/RALDBModule.pas` + `src/database/*` + `src/utils/RALStorage*.pas`
+8. **Swagger/Postman (export de rotas/documentação)** → `src/base/modules/RALSwaggerExporter.pas` + `src/base/modules/RALSwaggerModule.pas` + `src/base/modules/RALPostmanExporter.pas`
+9. **Autenticação/Security** → `src/base/plugins/RALAuthentication.pas` + `src/base/RALRoutes.pas` (checagens/allowed methods)
+
+---
+
+## 1) Fluxos mentais (para não perder contexto)
+
+### Server
+- `RALServer` (loop/config)
+- `RALRoutes` (resolução de rota)
+- Engine de transporte (CGI/fpHTTP/Indy/etc.) traduz bytes ⇄ `TRALRequest/TRALResponse`
+- Handler de rota preenche `AResponse` (ex.: `AResponse.Answer(...)`)
+
+### Client
+- `RALClient` orquestra
+- Engine do transporte envia request
+- `TRALRequest` é serializado (params/headers/body + compress/cripto quando configurado)
+- Resposta vira `TRALResponse` e é decodificada
+
+---
+
+## 2) Padrão de handler (exemplo “não inventar”)
+
+Ao criar um handler em mensagens/chat:
+1. confirme a **assinatura exata** no repo em `RALServer`/`RALRoutes` (ou um exemplo de engine)
+2. use `AResponse.Answer(...)` com constantes quando existirem no repo
+
+---
+
+## 3) Próximo arquivo recomendado (sempre)
+
+Comece por:
+- `src/base/RALRoutes.pas`
+
+Se você estiver preso, volte e escolha o objetivo do item (0).
+
+---
+
+## 4) Recursos “para agente” (cache de navegação)
+
+- Mapa do repo (com detalhes): `.agents/PROJECT_MAP.md`
+- Guidelines anti-custo: `.agents/SKILLS.md`
+- Playbooks por tarefa: `.agents/TASK_PLAYBOOKS.md`
+

.agents/PROJECT_MAP.md

@@ -6,8 +6,20 @@ Este arquivo foi criado para ajudar agentes de IA a entenderem rapidamente a est
 
 ---
 
+## 0) TL;DR (leia primeiro)
+
+- Se você está em dúvida: comece por `.agents/AGENT_QUICKSTART.md`.
+
+
+- Se você precisa “onde começar”, use `.agents/AGENT_QUICKSTART.md`.
+- Para entender o fluxo geral, use a visão conceitual (seções 4.1/4.2/4.3).
+- Para navegação por tarefa: use `.agents/TASK_PLAYBOOKS.md`.
+
+---
+
 ## 1) Estrutura raiz
 
+
 - `.gitignore`
 - `.gitmodules`
 - `CHANGELOG.md` — histórico de mudanças, releases e notas de correções.

.agents/README.md

@@ -2,7 +2,10 @@
 
 Pasta para materiais auxiliares de automação e agentes de IA.
 
+- `AGENT_QUICKSTART.md` — guia mínimo (baixo consumo de contexto) para escolher o próximo arquivo-alvo.
 - `PROJECT_MAP.md` — mapa amigável do repositório para acelerar entendimento e navegação por agentes de IA.
 - `SKILLS.md` — instruções e guidelines para melhorar desempenho/eficiência dos agentes.
 
+> Use primeiro `AGENT_QUICKSTART.md` quando a janela de contexto for pequena.
+
 

.agents/SKILLS.md

@@ -4,10 +4,12 @@ Instruções para acelerar desempenho de agentes de IA usando este repositório.
 
 ---
 
-## 1) Primeiro passo: use o `PROJECT_MAP.md`
-- Leia **`.agents/PROJECT_MAP.md`** para entender onde está o código.
+## 1) Primeiro passo: use o `AGENT_QUICKSTART.md`
+- Leia **`.agents/AGENT_QUICKSTART.md`** para escolher o primeiro arquivo-alvo com baixo consumo de contexto.
+- Em seguida, use **`.agents/PROJECT_MAP.md`** para navegação e entendimento de fluxo.
 - Em seguida, escolha a seção do mapa que corresponde ao seu objetivo:
 
+
 > Para reduzir gasto de tokens, use um cache local (abaixo) antes de refazer indexações/leitura repetitiva.
 
   - Rotas/servidor → `src/base/RALRoutes.pas`, `src/base/RALServer.pas`

.agents/TASK_PLAYBOOKS.md

@@ -0,0 +1,128 @@
+# TASK_PLAYBOOKS (PascalRAL-dev)
+
+Playbooks curtos para tarefas comuns. Cada playbook aponta exatamente **onde ler** antes de responder/codar.
+
+---
+
+## Playbook A — “Quero uma rota ping (Server)”
+
+1) Leia:
+- `src/base/RALRoutes.pas` (como rotas são registradas/descobertas)
+- `src/base/RALServer.pas` (como o ciclo executa handlers)
+
+2) Depois escolha engine:
+- `src/engine/indy/RALIndyServer.pas` (ou fpHTTP/synopse/cgi)
+
+3) Confirme a assinatura do handler no repo.
+
+4) No handler, preencha resposta usando o padrão do projeto:
+- procure exemplos de `AResponse.Answer(...)` em `src/base/RALResponse.pas` e handlers existentes.
+
+---
+
+## Playbook B — “Quero consumir a rota via Client”
+
+1) Leia:
+- `src/base/RALClient.pas` (orquestra)
+- `src/base/RALRequest.pas` / `src/base/RALResponse.pas`
+
+2) Escolha engine do transporte:
+- `src/engine/indy/RALIndyClient.pas`
+- `src/engine/fpHTTP/RALfpHTTPClient.pas`
+- `src/engine/netHTTP/RALnetHTTPClient.pas`
+- `src/engine/synopse/RALSynopseClient.pas`
+- `src/engine/unigui/RALUniGUIRegister.pas` (se aplicável)
+
+3) Confirme:
+- como setar BaseURL/route
+- como passa body/headers
+- como ler status/response text/json
+
+---
+
+## Playbook C — “Enviar JSON e ler JSON”
+
+1) Leia:
+- `src/utils/RALJson.pas`
+- `src/base/RALParams.pas` (conversion helpers)
+- `src/base/RALResponse.pas`
+
+2) Confirme onde fica o encoder/decoder do repo.
+
+3) Em handlers:
+- use `AResponse.Answer(HTTP_OK, <payload>, <content-type/rct...>)` (procure os tipos constantes no repo)
+
+---
+
+## Playbook D — “Multipart/form-data”
+
+1) Leia:
+- `src/utils/RALMultipartCoder.pas`
+- `src/base/RALParams.pas` (quando faz decode do body)
+
+2) Confirme:
+- como adicionar File vs Text no `TRALParams`
+- como ler de volta do `TRALParams` no server handler
+
+---
+
+## Playbook E — “Compressão e Criptografia (pipeline de bytes)”
+
+1) Leia:
+- `src/utils/RALStream.pas` (bytes/stream helpers)
+- `src/utils/RALCompress*.pas`
+- `src/utils/RALCripto*.pas`
+
+2) Leia as dependências no pipeline:
+- `src/base/RALRequest.pas` / `src/base/RALResponse.pas`
+- `src/base/RALParams.pas` (EncodeBody/DecodeBody)
+
+3) Só então ajuste engine:
+- procure onde `Content-Encoding`, `Accept-Encoding`, flags de compress/cripto são checados.
+
+---
+
+## Playbook F — “DBWare/DBModule (ExecSQL/Open/ApplyUpdates)”
+
+1) Leia:
+- `src/database/RALDBModule.pas` (mapeia requests → ações)
+- `src/database/RALDBBase.pas` (base comum)
+
+2) Conectores:
+- `src/database/FireDAC/*`
+- `src/database/sqldb/*`
+- `src/database/Zeos/*`
+
+3) Persistência/serialização do resultado:
+- `src/utils/RALStorage*.pas`
+
+---
+
+## Playbook G — “Swagger e Postman”
+
+1) Leia:
+- `src/base/modules/RALSwaggerExporter.pas` + `src/base/modules/RALSwaggerModule.pas`
+- `src/base/modules/RALPostmanExporter.pas`
+
+2) Se precisar customizar:
+- procure no repo onde `SwaggerModule` recebe URLs/paths/titles.
+
+---
+
+## Playbook H — “Security/Auth (Allowed/Skip + plugin)”
+
+1) Leia:
+- `src/base/plugins/RALAuthentication.pas`
+- `src/base/RALRoutes.pas` (allowed/skip e validações)
+
+2) Leia o fluxo:
+- `src/base/RALServer.pas` (quando valida e quando responde)
+
+---
+
+## Regra geral (evitar gastar tokens)
+
+- Comece por **um** arquivo (o mais central do playbook).
+- Só depois abra os 1-2 dependentes listados.
+- Não use `compiled/` como fonte.
+

README.md

@@ -5,7 +5,8 @@ Pascal REST API Lite is a component suite to allow creating and consuming APIs i
 
 ## Minimal workflow for AI agents (compact)
 This repo has a short, agent-oriented guide optimized for small context windows:
-- `.agents\README.md`
+- `.agents/README.md`
+
 
 ## Security
 See `SECURITY.md` for supported versions and how to report vulnerabilities.

READMEES.md

@@ -5,10 +5,10 @@ Pascal REST API Lite es un conjunto de componentes para crear y consumir APIs de
 
 ## Flujo mínimo para agentes de IA (compacto)
 Existe un guía corto orientado a agentes, optimizado para ventanas de contexto pequeñas:
-- `.agents\README.md` (EN)
+- `.agents/README.md` (EN)
 
 ## Seguridad
-Ver `SECURITY.md` para versiones soportadas y cómo reportar vulnerabilidades.
+Ver `SECURITY.md` para las versiones soportadas y cómo reportar vulnerabilidades.
 
 
 
@@ -38,3 +38,4 @@ Comparativo Lazarus Windows
 
 Comparativo Lazarus Linux
 <br/><img src="https://docs.google.com/spreadsheets/d/e/2PACX-1vQQ-tumA_HFJdvoFoztRWFVokDwf_6UrzdFswFo5a-u0QLRFBuLMlmOoa3Hp2qiq0k1S5kE-8IjQein/pubchart?oid=1479879994&format=image" width=640px/>
+

READMEPT.md

@@ -5,7 +5,8 @@ Pascal REST API Lite é uma suíte de componentes de criação e consumo de APIs
 
 ## Fluxo mínimo para agentes de IA (compacto)
 Existe um guia curto e orientado a agentes, otimizado para janelas de contexto pequenas:
-- `.agents\README.md` (EN)
+- `.agents/README.md` (EN)
+
 
 ## Segurança
 Veja `SECURITY.md` para versões suportadas e como relatar vulnerabilidades.