@jaimevalasek/aioson 1.3.0 → 1.5.1

package/docs/openclaw-bridge.md

@@ -0,0 +1,308 @@
+# OpenClaw + AIOSON Bridge
+
+> AIOSON receives external triggers. OpenClaw delivers them. Neither system changes — the bridge is pure configuration.
+
+## Overview
+
+```
+[External channel]          [OpenClaw]            [AIOSON squad-webhook]
+ WhatsApp, Telegram,   →   gateway de canal   →   POST /trigger
+ Slack, webhook ERP         identifica sessão       executa squad
+                                                    ↓
+                            ←   callback HTTP   ←   POST callback_url
+                            envia resposta
+                            ao canal
+```
+
+## Quick start
+
+### 1. Start the webhook server
+
+```bash
+export AIOSON_WEBHOOK_TOKEN=your-secret-token
+aioson squad:webhook start --port 3210
+```
+
+The server auto-discovers all squads in `.aioson/squads/`. Output:
+
+```
+AIOSON squad webhook server started on port 3210
+Available squads: atendimento, vendas, logistica
+Endpoints: POST /trigger  GET /status/:run_id  GET /health
+```
+
+### 2. Generate the OpenClaw configuration
+
+```bash
+aioson squad:webhook config --channel whatsapp --squad atendimento
+```
+
+Copy the output into your `openclaw.json`.
+
+### 3. Verify
+
+```bash
+curl http://localhost:3210/health
+# {"ok":true,"version":"x.x.x","squads":["atendimento","vendas","logistica"]}
+```
+
+---
+
+## Endpoints
+
+### `GET /health`
+
+No authentication required.
+
+```json
+{ "ok": true, "version": "1.4.0", "squads": ["atendimento", "vendas"] }
+```
+
+---
+
+### `POST /trigger`
+
+Async squad execution. Returns immediately with a `run_id`.
+
+**Headers:**
+```
+Authorization: Bearer <AIOSON_WEBHOOK_TOKEN>
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "squad": "atendimento",
+  "input": "quero dipirona 500mg",
+  "session_id": "wa:5511999000",
+  "callback_url": "https://your-server/callback",
+  "metadata": {
+    "channel": "whatsapp",
+    "phone": "+5511999000",
+    "user_name": "João"
+  }
+}
+```
+
+| Field          | Required | Description |
+|----------------|----------|-------------|
+| `squad`        | yes      | Squad slug to execute |
+| `input`        | yes      | User message |
+| `session_id`   | no       | Opaque string — enables conversation continuity |
+| `callback_url` | no       | Where to POST the response when done |
+| `metadata`     | no       | Arbitrary key/value, echoed back in the callback |
+
+**Response (202):**
+```json
+{ "run_id": "a1b2c3d4e5f6a7b8", "status": "queued" }
+```
+
+**Callback payload (async POST to `callback_url`):**
+```json
+{
+  "run_id": "a1b2c3d4e5f6a7b8",
+  "session_id": "wa:5511999000",
+  "response": "Temos dipirona 500mg por R$8,90. Deseja adicionar ao carrinho?",
+  "status": "completed",
+  "metadata": { "channel": "whatsapp", "phone": "+5511999000", "user_name": "João" }
+}
+```
+
+Callback delivery: 3 retries with exponential backoff (30s → 60s → 120s).
+
+---
+
+### `GET /status/:run_id`
+
+Poll execution state when no `callback_url` was provided.
+
+```
+GET /status/a1b2c3d4e5f6a7b8
+Authorization: Bearer <token>
+```
+
+```json
+{
+  "run_id": "a1b2c3d4e5f6a7b8",
+  "status": "running",
+  "response": null,
+  "error": null
+}
+```
+
+`status` values: `queued` → `running` → `completed` | `failed`
+
+---
+
+### `POST /query`
+
+Synchronous query — for fast lookups that don't need a full squad session (e.g., product search from a website). Timeout: 10 seconds.
+
+```json
+{
+  "squad": "catalogo",
+  "query": "dipirona 500mg",
+  "max_results": 10
+}
+```
+
+```json
+{
+  "results": [{ "id": 42, "name": "Dipirona 500mg", "price": 8.90 }],
+  "squad": "catalogo",
+  "latency_ms": 340
+}
+```
+
+---
+
+## Session continuity
+
+When `session_id` is provided, AIOSON maintains conversation history across multiple calls.
+
+**First call:**
+```json
+{ "squad": "atendimento", "input": "quero dipirona", "session_id": "wa:5511999000" }
+```
+→ Squad receives: `quero dipirona`
+
+**Second call (same session):**
+```json
+{ "squad": "atendimento", "input": "qual o preço?", "session_id": "wa:5511999000" }
+```
+→ Squad receives:
+```
+[Conversation history]
+user: quero dipirona
+assistant: Temos dipirona 500mg por R$8,90. Deseja adicionar ao carrinho?
+
+[Current message]
+qual o preço?
+```
+
+Session files are stored in `.aioson/sessions/` and expire after 24 hours of inactivity (configurable via `AIOSON_SESSION_TTL_HOURS`).
+
+---
+
+## OpenClaw configuration
+
+### WhatsApp (full example)
+
+```yaml
+# openclaw.json
+hooks:
+  whatsapp:
+    auto_reply:
+      - pattern: ".*"
+        action: webhook
+        url: "http://localhost:3210/trigger"
+        headers:
+          Authorization: "Bearer ${AIOSON_WEBHOOK_TOKEN}"
+        body_template: |
+          {
+            "squad": "atendimento",
+            "input": "{{message.text}}",
+            "session_id": "wa:{{message.from}}",
+            "callback_url": "{{openclaw.callback_url}}",
+            "metadata": {
+              "channel": "whatsapp",
+              "phone": "{{message.from}}",
+              "user_name": "{{message.contact_name}}"
+            }
+          }
+```
+
+### Telegram
+
+```yaml
+hooks:
+  telegram:
+    auto_reply:
+      - pattern: ".*"
+        action: webhook
+        url: "http://localhost:3210/trigger"
+        headers:
+          Authorization: "Bearer ${AIOSON_WEBHOOK_TOKEN}"
+        body_template: |
+          {
+            "squad": "suporte",
+            "input": "{{message.text}}",
+            "session_id": "tg:{{message.chat_id}}",
+            "callback_url": "{{openclaw.callback_url}}",
+            "metadata": { "channel": "telegram" }
+          }
+```
+
+### Multiple squads by intent
+
+Route different message patterns to different squads:
+
+```yaml
+hooks:
+  whatsapp:
+    auto_reply:
+      - pattern: "^(pedido|comprar|quero|carrinho)"
+        action: webhook
+        url: "http://localhost:3210/trigger"
+        headers:
+          Authorization: "Bearer ${AIOSON_WEBHOOK_TOKEN}"
+        body_template: |
+          { "squad": "vendas", "input": "{{message.text}}", "session_id": "wa:{{message.from}}", "callback_url": "{{openclaw.callback_url}}" }
+
+      - pattern: "^(onde|entrega|rastreio|pedido)"
+        action: webhook
+        url: "http://localhost:3210/trigger"
+        headers:
+          Authorization: "Bearer ${AIOSON_WEBHOOK_TOKEN}"
+        body_template: |
+          { "squad": "logistica", "input": "{{message.text}}", "session_id": "wa:{{message.from}}", "callback_url": "{{openclaw.callback_url}}" }
+
+      - pattern: ".*"
+        action: webhook
+        url: "http://localhost:3210/trigger"
+        headers:
+          Authorization: "Bearer ${AIOSON_WEBHOOK_TOKEN}"
+        body_template: |
+          { "squad": "atendimento", "input": "{{message.text}}", "session_id": "wa:{{message.from}}", "callback_url": "{{openclaw.callback_url}}" }
+```
+
+---
+
+## Security
+
+| Concern | Mechanism |
+|---------|-----------|
+| Authentication | Bearer token (`AIOSON_WEBHOOK_TOKEN`) on all endpoints except `/health` |
+| Rate limiting | 60 req/min per IP by default |
+| Squad allowlist | Only squads in `.aioson/squads/` are accessible |
+| Callback security | Callbacks only POST to URLs provided by the caller |
+| Session isolation | Each `session_id` maps to a separate file; no cross-session access |
+
+Set `AIOSON_WEBHOOK_TOKEN` to a random secret (minimum 32 chars):
+
+```bash
+openssl rand -hex 32
+```
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AIOSON_WEBHOOK_TOKEN` | — | Bearer token (required for security) |
+| `AIOSON_WEBHOOK_PORT` | `3210` | Server port |
+| `AIOSON_SESSION_TTL_HOURS` | `24` | Session expiry in hours |
+
+---
+
+## CLI reference
+
+```bash
+# Start webhook server
+aioson squad:webhook start [path] [--port 3210] [--token TOKEN]
+
+# Generate OpenClaw config snippet
+aioson squad:webhook config [--channel whatsapp] [--squad atendimento] [--port 3210]
+```

package/docs/pt/README.md

@@ -8,9 +8,15 @@ Bem-vindo à documentação em português do AIOSON — um framework leve de age
 |---|---|
 | [Início Rápido](./inicio-rapido.md) | Instale, configure e comece em menos de 10 minutos |
 | [Comandos CLI](./comandos-cli.md) | Referência em português dos comandos do `aioson`, com descrição, exemplos e usos práticos |
+| [Memória e Contexto](./memoria-contexto.md) | Guia prático dos arquivos de memória, descoberta, índices e pacotes mínimos de contexto |
+| [Deyvin](./deyvin.md) | Guia do agente de continuidade e pair programming do AIOSON |
 | [Cenários de Uso](./cenarios.md) | Exemplos completos e práticos para projetos MICRO, SMALL e MEDIUM |
 | [Guia de Agentes](./agentes.md) | Quando usar cada agente e o que ele entrega |
-| [Squad e Genoma](./squad-genoma.md) | Como criar squads modulares, diferenciar skill de genoma, aplicar genomas e publicar entregáveis HTML |
+| [Squad e Genome](./squad-genome.md) | Como criar squads modulares, diferenciar skill de genome, aplicar genomes e publicar entregáveis HTML |
+| [Agentes Customizados](./agentes-customizados.md) | Criar agentes personalizados com `squad:agent-create` — tipos, Voice DNA, infra operacional, maturity scoring |
+| [Skills](./skills.md) | Sistema de skills: tipos, instalação, mapeamento por framework e compatibilidade cross-tool |
+| [Automação de Squads](./automacao-squads.md) | Transformar processos de squad em scripts executáveis (Python/Node.js) que rodam sem LLM |
+| [Output Strategy e Delivery](./output-strategy-delivery.md) | Configurar webhooks, automatizar entrega de conteúdo, monitorar delivery e troubleshoot |
 | [Suporte Web3](./web3.md) | Guia para projetos dApp (Ethereum, Solana, Cardano) |
 
 ## Documentação em inglês
@@ -39,8 +45,62 @@ Depois, abra seu AI IDE e digite `/setup` para começar.
 
 Fluxo recomendado:
 - `@setup` primeiro
-- em projeto existente sem documentação, rode `scan:project --folder=src` ou `scan:project --folder=app` para gerar `scan-index.md`, `scan-folders.md`, `scan-<pasta>.md` e `scan-aioson.md`; adicione `--with-llm` se quiser `discovery.md` e `skeleton-system.md`
+- em projeto existente sem documentação, rode `scan:project --folder=src` ou `scan:project --folder=app` para gerar `scan-index.md`, `scan-folders.md`, `scan-<pasta>.md`, `scan-aioson.md`, `memory-index.md` e `module-<pasta>.md`
+- se existir `spec.md`, o scan local também deriva `spec-current.md` e `spec-history.md`
+- depois rode novamente com `--with-llm` para gerar ou atualizar `discovery.md` e `skeleton-system.md`
+- quando quiser mandar só o contexto mínimo para uma tarefa, use `context:pack`
+- quando quiser entender como o `@deyvin` trabalha, leia [Deyvin](./deyvin.md)
+- quando quiser continuar uma sessao, corrigir um recorte pequeno ou trabalhar em modo companheiro tecnico, use `@deyvin`
 - `@discovery-design-doc` quando o escopo ainda estiver vago ou a feature for grande
 - `@analyst` / `@architect` / `@dev` conforme a clareza e o tipo do trabalho
 
 Esse passo de `discovery-design-doc` e recomendado, nao obrigatorio.
+
+## Brownfield sem duvida
+
+Se voce instalou o AIOSON num projeto que ja existe, este e o fluxo inicial mais seguro:
+
+```bash
+# 1. Instale/atualize o AIOSON no repositorio
+npx @jaimevalasek/aioson install
+
+# 2. Gere o contexto principal
+npx @jaimevalasek/aioson setup:context --defaults
+
+# 3. Gere os mapas locais do codigo
+npx @jaimevalasek/aioson scan:project . --folder=src,app
+
+# 4. Gere ou atualize a memoria brownfield consolidada com LLM
+npx @jaimevalasek/aioson scan:project . --folder=src,app --with-llm --provider=openai
+
+# 5. Monte um pacote minimo de contexto para a tarefa atual
+npx @jaimevalasek/aioson context:pack . --agent=dev --goal="ajustar captions do editor" --module=src
+```
+
+O que cada etapa entrega:
+
+- `scan:project` sem `--with-llm`: gera `scan-index.md`, `scan-folders.md`, `scan-<pasta>.md`, `scan-aioson.md`, `memory-index.md`, `module-<pasta>.md` e, quando houver `spec.md`, também `spec-current.md` + `spec-history.md`
+- `scan:project` com `--with-llm`: gera ou atualiza `discovery.md` e `skeleton-system.md`
+- `scan:project` nunca gera `architecture.md`; esse arquivo vem depois com `@architect`
+- `context:pack`: gera `.aioson/context/context-pack.md` com o pacote mínimo recomendado para a tarefa atual
+
+Sem API LLM no `aioson`, ainda existe um caminho valido:
+
+- rode `scan:project . --folder=...` para gerar os mapas locais
+- rode `context:pack` se quiser entregar menos contexto e gastar menos tokens
+- abra Codex, Claude Code, Gemini CLI ou outro cliente de IA
+- ative `@analyst`
+- o `@analyst` pode usar `scan-index.md`, `scan-folders.md`, `scan-<pasta>.md` e `scan-aioson.md` para escrever `discovery.md`
+- se o cliente permitir escolher modelo, prefira um modelo rapido/barato nessa etapa
+
+Fluxo recomendado depois do scanner em projeto SMALL brownfield:
+
+- `@analyst` para consolidar ou revisar a descoberta do sistema e do escopo atual
+- `@architect` para transformar essa descoberta em `architecture.md`
+- `@dev` somente depois da memoria estar pronta
+
+Regra importante sobre atualizacao:
+
+- `scan:project --with-llm` usa `merge` por padrao quando `discovery.md` ou `skeleton-system.md` ja existem
+- antes de sobrescrever, ele cria backup automatico em `.aioson/backups/`
+- se voce quiser regenerar do zero, use `--context-mode=rewrite`

package/docs/pt/advisor-spec.md

@@ -9,7 +9,7 @@
 
 ## O que é um Advisor
 
-Um Advisor é um agente operacional completo baseado no perfil cognitivo inferido de uma pessoa real. Ele não é um genoma aplicado passivamente; ele opera diretamente em modo consultivo.
+Um Advisor é um agente operacional completo baseado no perfil cognitivo inferido de uma pessoa real. Ele não é um genome aplicado passivamente; ele opera diretamente em modo consultivo.
 
 Capacidades esperadas:
 
@@ -21,16 +21,16 @@ Capacidades esperadas:
 
 ---
 
-## Advisor versus Genoma
+## Advisor versus Genome
 
-| Aspecto | Genoma | Advisor |
+| Aspecto | Genome | Advisor |
 |---------|--------|---------|
 | Tipo | Artefato passivo de conhecimento | Agente ativo |
 | Execução direta | Não | Sim, em modo consultivo |
 | Web search | Não | Sim |
 | Memória | Não | Sim |
 | Uso principal | Enriquecer executores | Opinar, desafiar, aconselhar |
-| Localização | `.aioson/genomas/` | `.aioson/advisors/` |
+| Localização | `.aioson/genomes/` | `.aioson/advisors/` |
 
 ---
 
@@ -53,7 +53,7 @@ mbti: "[XXXX]"
 confidence: [low|medium|high]
 
 profiler_report: ".aioson/profiler-reports/[slug]/enriched-profile.md"
-genome: ".aioson/genomas/[slug].md"
+genome: ".aioson/genomes/[slug].md"
 
 web_search: true
 memory: true