constellai 0.3.0

package/docs/pt/ARCHITECTURE.md

@@ -0,0 +1,334 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/ARCHITECTURE.md) · [✦ Constella](../../README.pt-BR.md)
+
+# 🌌 Arquitetura — a nave central
+
+A Constella é um plano de controle local-first: um único processo Node supervisiona um **servidor web** e um **worker 24/7**, ambos orbitando uma raiz de runtime em disco onde cada organização mantém um workspace isolado. O diretório é a fonte da verdade; o SQLite é o índice que mantém a UI e a busca em acordo.
+
+> ✦ Este documento mapeia a camada *estrutural*: topologia de processos, raiz de runtime + isolamento de organização, a jaula de filesystem, o armazenamento SQLite/Drizzle, o motor de sincronização + watcher de arquivos, e o cron tick que conduz o trabalho autônomo. Para a camada *cognitiva* (como os agentes pensam, RAG, KB) veja [AI_ARCHITECTURE](./AI_ARCHITECTURE.md).
+
+---
+
+## 🛰️ Quando usar este doc
+
+- Você precisa entender **como a Constella inicializa** e qual processo faz o quê.
+- Está depurando **por que uma edição de arquivo não apareceu** na UI (motor de sincronização).
+- Está raciocinando sobre **isolamento multi-tenant** (uma raiz de runtime, várias organizações).
+- Está reforçando ou auditando a fronteira de confiança **worker ↔ web**.
+- Quer o **mapa em nível de tabela** do banco de dados (`src/db/schema.ts`).
+
+---
+
+## 🚀 Como funciona (visão geral)
+
+Um único launcher — `bin/constella.mjs` — resolve o modo de execução, prepara a raiz de runtime e os segredos, aplica as migrações do banco e então **supervisiona dois filhos de longa duração**:
+
+| Filho | Entrada | Papel |
+| --- | --- | --- |
+| **web** | `next start -H <host> -p <port>` (a partir de `PKG_ROOT`) | A app Next.js 16: UI, server actions, todas as rotas `/api`, orquestração de agentes. |
+| **worker** | `bin/worker.mjs` | Condutor headless 24/7: cron tick, o watcher de arquivos chokidar, o long-poll do Telegram. Fala com a web por HTTP em loopback. |
+
+O worker nunca toca no banco diretamente. Ele apenas faz chamadas HTTP autenticadas de volta para o servidor web (`x-worker-secret`), de modo que todas as escritas passam por um único processo e um único conjunto de server actions. Isso mantém a fronteira de confiança pequena e o banco com um único escritor.
+
+```mermaid
+flowchart TB
+  subgraph Launcher["bin/constella.mjs (supervisor)"]
+    SUP["supervise(): reinicia em crash<br/>máx 5 / 60s"]
+  end
+
+  SUP -->|spawn| WEB["web<br/>next start @ host:port<br/>cwd = PKG_ROOT"]
+  SUP -->|spawn| WK["worker<br/>bin/worker.mjs"]
+
+  WK -->|"POST /api/cron/tick<br/>(x-worker-secret)"| WEB
+  WK -->|"POST /api/sync/file<br/>(x-worker-secret)"| WEB
+  WK -->|"POST /api/telegram/poll"| WEB
+  WK -->|"chokidar watch"| DISK[("Raiz de runtime<br/>~/.constella")]
+
+  WEB -->|drizzle / better-sqlite3| DB[("constella.db<br/>WAL")]
+  WEB -->|"fs-workspace safe()"| DISK
+  WEB -->|spawn claude / codex| CLI["CLIs de agente<br/>cwd = workspace da org (jaula FS)"]
+  CLI -->|edita arquivos| DISK
+
+  classDef store fill:#1a1a2e,stroke:#e0a44e,color:#fff
+  class DB,DISK store
+```
+
+---
+
+## 🌠 Fluxo principal — do boot ao regime estável
+
+A sequência de boot do launcher (`bin/constella.mjs`), em ordem:
+
+1. **Resolver o destino de instalação** — uma flag de execução explícita (`--start|--vps|--portable`) vence, depois o legado `--bind`. Um `constella` sem flag imprime o uso e sai. A autenticação (e-mail + senha) é exigida em todo destino. Veja [START_MODE](./START_MODE.md), [VPS_MODE](./VPS_MODE.md), [PORTABLE_MODE](./PORTABLE_MODE.md).
+2. **Resolver a raiz de runtime** — `CONSTELLA_HOME` / `--path` vence; caso contrário `~/.constella`. O modo portátil sem path enumera drives USB removíveis e pergunta. `mkdir -p <HOME>/organizations`.
+3. **Fixar caminhos** — `DATABASE_URL=file:<HOME>/constella.db`, `CONSTELLA_PKG_ROOT=<dir de instalação>`. `PKG_ROOT` é onde vivem o `.next` pré-compilado, as migrações `drizzle/` e os configs (não o diretório de lançamento).
+4. **Persistir segredos** — ler/gerar `BETTER_AUTH_SECRET`, `CONSTELLA_VAULT_KEY`, `CONSTELLA_WORKER_SECRET` e gravá-los em `<HOME>/.env` com modo `0o600`. Gerados uma vez; reutilizados entre reinícios para que as sessões + o vault criptografado sobrevivam.
+5. **Verificação de disco no portátil** — recusa `< 32 GB` livres (fatal); `≥ 32 GB` está ok.
+6. **Aplicar migrações** — `drizzle-kit migrate --config drizzle.config.mjs` a partir de `PKG_ROOT`. Idempotente. Um banco *novo* que falha ao migrar aborta o boot (sem tabelas → toda requisição dá 500).
+7. **Build no primeiro run (apenas fallback)** — o pacote publicado já traz um `.next` pré-compilado, então isso é pulado. A partir de uma árvore de código-fonte sem build, ele roda `next build`; recusa cair silenciosamente para `next dev` em um run público a menos que `CONSTELLA_DEV=1`.
+8. **Supervisionar web + worker** — sobe o servidor web e, ~1,5 s depois, o worker (para o Next ganhar vantagem). Cada filho é envolto em `supervise()`; em uma saída inesperada ele auto-reinicia (limitado: `MAX_RESTARTS = 5` dentro de `WINDOW_MS = 60_000`), senão o supervisor desiste e sai.
+
+Já em regime, o **worker** espera o servidor responder (`waitForServer`, até ~90 s) e então:
+
+- Dispara o **cron tick** imediatamente e a cada `INTERVAL` (`CONSTELLA_WORKER_INTERVAL_MS`, padrão `60_000` ms).
+- Inicia o **watcher chokidar** sobre `<HOME>/organizations`.
+- Roda o loop de **long-poll do Telegram** (`getUpdates` aguarda ~25 s no lado do servidor; intervalo de ~1 s entre polls).
+
+---
+
+## 🪐 Conceitos-chave
+
+### Raiz de runtime + isolamento por organização
+
+```
+~/.constella/                         ← raiz de runtime (CONSTELLA_HOME ou --path)
+├─ .env                               ← segredos persistidos (modo 0600)
+├─ constella.db                       ← SQLite (WAL) — o índice
+├─ cache/                             ← cache do models.dev, etc.
+├─ backups/                           ← backups de .env + db no update
+└─ organizations/
+   └─ <orgId>/
+      └─ workspace/                   ← a árvore isolada e sandboxed da org
+         ├─ .claude/                  ← agents/, skills/, BRIEF.md (config DENTRO do workspace)
+         ├─ DOCS/  PO/  Reports/
+         ├─ specs/ issues/ mock/
+         ├─ uploads/                  ← anexos do operador, mídia do Telegram
+         └─ <o produto que os agentes constroem>
+```
+
+O diretório de workspace é indexado pelo **`organization.id` estável** (nunca pelo slug renomeável). Uma migração única de boot renomeia um diretório legado `constella/` para `workspace/` para que as organizações existentes mantenham seus dados (caindo para uma cópia em uma movimentação entre dispositivos, nunca apagando o diretório legado).
+
+### A jaula de filesystem — `safe()`
+
+Toda leitura/escrita de workspace passa por `safe(root, rel)` em `src/lib/fs-workspace.ts`. É o único ponto de estrangulamento que mantém um agente sob prompt-injection (ou um caminho com bug) dentro da sua própria org:
+
+1. **Verificação léxica** — `normalize(join(root, rel))` deve ser igual a `root` ou começar com `root + sep`. Como `join` re-enraiza caminhos absolutos, com letra de drive e UNC sob `root`, isso bloqueia `../`, escapes absolutos e truques de drive do Windows.
+2. **Verificação de symlink** — resolve o caminho real do ancestral existente mais próximo (`realAncestor`) e re-verifica que ele ainda está sob o `root` real. Isso derrota um symlink *plantado dentro* do workspace que de outra forma tunelaria para outra org ou para o filesystem mais amplo.
+
+`orgRoot()` adicionalmente valida o id da org (`/^[A-Za-z0-9_-]{6,64}$/`) antes mesmo de tocar em um caminho, então um id malformado não consegue atravessar. Diretórios pesados de build/dependência (`node_modules`, `.git`, `.next`, `dist`, `.testdev`, …) são pulados por `listFiles()` via `HEAVY_DIRS`.
+
+### O diretório é a verdade, o banco é o índice
+
+O filesystem é canônico; o banco **espelha** ele. Os indexadores em `src/server/sync.ts` são upserts idempotentes e **o disco sempre vence no conflito**. O mesmo arquivo escrito por um agente e depois re-indexado pelo watcher atualiza *uma* linha (indexada pelo título H1 ou pelo caminho relativo), nunca duplica.
+
+### SQLite + Drizzle
+
+`src/db/index.ts` abre o `better-sqlite3` contra o `DATABASE_URL` resolvido, define `journal_mode = WAL` e `foreign_keys = ON`, e o envolve com `drizzle-orm`. Também exporta o handle bruto `sqlite` para **DDL de boot sem migração** (`CREATE TABLE IF NOT EXISTS` + `ALTER ADD COLUMN` protegido) — usado para adicionar tabelas/colunas a bancos existentes *sem* `drizzle-kit push`, que faria o histórico de migrações deste projeto derivar. Veja [SECURITY](./SECURITY.md) e [TROUBLESHOOTING](./TROUBLESHOOTING.md) para a ressalva do `db:push`.
+
+### Fronteira de confiança worker ↔ web
+
+O worker detém o privilegiado `CONSTELLA_WORKER_SECRET` e o anexa como `x-worker-secret` em toda chamada. Duas proteções importam:
+
+- **Fail closed no servidor**: `/api/cron/tick` e `/api/sync/file` retornam `401` a menos que o header seja igual ao segredo configurado. Um segredo não definido **não** os deixa abertos — eles rejeitam todo mundo.
+- **Guarda SSRF / exfiltração no worker**: o worker se recusa a enviar o segredo para um host não-loopback. O launcher sempre define `CONSTELLA_BASE_URL=http://127.0.0.1:<port>` (loopback mesmo quando a web faz bind em `0.0.0.0` para vps/portable). Um worker remoto genuíno precisa optar explicitamente com `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1`, e sobre `http://` puro ele avisa que o segredo viaja em texto-claro.
+
+---
+
+## 🗃️ Tabelas
+
+### Ambiente de processo / runtime
+
+| Variável de ambiente | Definida por | Significado |
+| --- | --- | --- |
+| `CONSTELLA_HOME` | launcher (`--path` / padrão `~/.constella`) | Raiz de runtime. Valores relativos são ancorados ao diretório de lançamento (`INIT_CWD`). |
+| `DATABASE_URL` | launcher | `file:<HOME>/constella.db` (absoluto, para que app + `drizzle-kit migrate` abram o mesmo banco). |
+| `CONSTELLA_PKG_ROOT` | launcher | Raiz do pacote instalado (`.next` pré-compilado, `drizzle/`, `skills/` empacotado). |
+| `CONSTELLA_RUN_MODE` | launcher | `start \| vps \| portable`. A autenticação (e-mail + senha) é exigida em todos eles. |
+| `CONSTELLA_PUBLIC` | launcher (`=1`) | Um lançamento por CLI é o runtime público → o seletor de destino da UI fica oculto. |
+| `CONSTELLA_VERSION` | launcher | Versão instalada, para a verificação de Update na app. |
+| `BETTER_AUTH_SECRET` | `<HOME>/.env` | Chave de assinatura de sessão (real, nunca o padrão público). |
+| `CONSTELLA_VAULT_KEY` | `<HOME>/.env` | Chave AES-256-GCM para a tabela `vault`. |
+| `CONSTELLA_WORKER_SECRET` | `<HOME>/.env` | Segredo compartilhado para a auth worker → web (`x-worker-secret`). |
+| `CONSTELLA_BASE_URL` | launcher → worker | `http://127.0.0.1:<port>` — alvo loopback para chamadas do worker. |
+| `CONSTELLA_WORKER_INTERVAL_MS` | opcional | Intervalo do cron tick (padrão `60_000`). |
+| `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL` | opcional (`=1`) | Permite o worker chamar um host não-loopback. |
+| `CONSTELLA_WEB_HEAP_MB` | opcional | `--max-old-space-size` para o filho web. |
+| `CONSTELLA_DEV` | opcional (`=1`) | Permite um fallback `next dev` a partir de uma árvore de fonte sem build. |
+
+### Tabelas de tenancy + estruturais centrais (`src/db/schema.ts`)
+
+| Tabela | Colunas-chave | Propósito |
+| --- | --- | --- |
+| `organization` | `id`, `ownerId`, `runMode` (`start\|vps\|portable`), `archived` | Tenant. `runMode` é o destino de instalação persistido. |
+| `member` | `orgId`, `userId`, `role` (`owner\|admin\|member`) | Pertencimento à org + papéis. |
+| `workspace` | `id`, `orgId`, `slug` (único), `stack` (JSON), `runMode`, `bootstrap`, `settings` (JSON) | Um workspace por org; `settings` guarda config de Telegram/GitHub/source/agents. |
+| `agent` | `handle`, `role`, `adapter`, `model`, `status`, `health`, `reportsTo`, `dailyCapUsd` | A constelação de 10 agentes. |
+| `skill` / `agentSkill` | `name`, `native`, `indexed`; junção `auto` | Procedimentos em Markdown + habilitação por agente. |
+| `goal` / `spec` / `issue` / `task` / `plan` | ciclo de vida `status`/`col`, `approved`, `auto247` | O pipeline de trabalho ([GOALS_SPECS_ISSUES](./GOALS_SPECS_ISSUES.md)). |
+| `message` / `chatSession` / `event` / `decision` | `channel`, `runId`, `seq` | Sala do Time, sessões de DM, eventos de run ao vivo, log de decisões. |
+| `ragChunk` / `kbEntry` / `syncedBlock` / `docIndex` | embeddings + camada KB | Nebulosa de memória ([KB_RAG](./KB_RAG.md), [MEMORY_RAG](./MEMORY_RAG.md)). |
+| `file` | `path`, `gitStatus` (`""\|M\|A\|U\|D`) | Espelho do editor + status porcelain do git. |
+| `vault` | `ref`, `ciphertext`, `iv` | Segredos AES-GCM indexados por provider. |
+| `fileLock` | `workspaceId+path` (PK), `taskId`, `heartbeatAt` | Lock por arquivo para que agentes em paralelo nunca editem o mesmo arquivo ([SECURITY](./SECURITY.md)). |
+
+> O schema define ~60 tabelas. A lista acima cobre as que são estruturais para *arquitetura*; as tabelas de trabalho, KB e modelos são documentadas em suas próprias páginas.
+
+### Motor de sincronização — prefixos indexados
+
+`bin/worker.mjs` só encaminha arquivos que casam com o regex `INDEXED`; `src/server/sync.ts` então roteia cada caminho para um indexador por tipo:
+
+| Padrão de caminho | Indexador | Alvo no banco |
+| --- | --- | --- |
+| `.claude/skills/<name>.md` | `indexSkillFile` | `skill` |
+| `.claude/agents/<handle>/(Agent\|skills).md` | `indexAgentFile` | `agent` (+ `agentSkill`) |
+| `Reports/**.md` | `indexReportFile` | `report` |
+| `DOCS/**.md` | `indexDocFile` (kind `docs`) | `docIndex` |
+| `PO/**.md` | `indexDocFile` (kind `po`) | `docIndex` |
+
+Qualquer mudança em um arquivo RAG também agenda um re-embed incremental com debounce via `scheduleRagReindex`; uma deleção descarta seus chunks via `deindexRagFile`.
+
+---
+
+## 🌌 Mermaid — o motor de sincronização (disco → banco)
+
+```mermaid
+sequenceDiagram
+    participant FS as Arquivos do workspace
+    participant W as worker (chokidar)
+    participant API as POST /api/sync/file
+    participant SYNC as src/server/sync.ts
+    participant DB as SQLite
+
+    FS->>W: add / change / unlink
+    Note over W: parse() → {orgId, rel}<br/>gate do regex INDEXED<br/>debounce 400ms por chave
+    W->>API: POST {orgId, rel, event}<br/>x-worker-secret
+    API->>API: 401 a menos que o segredo case
+    alt event = unlink
+        API->>SYNC: deindexFile(orgId, rel)
+        SYNC->>DB: deleta linha + descarta chunks RAG
+    else add / change
+        API->>SYNC: indexFile(orgId, rel)
+        SYNC->>SYNC: scheduleRagReindex(orgId, rel)
+        SYNC->>DB: upsert (disco vence) + revalidatePath
+    end
+```
+
+---
+
+## 🛰️ Mermaid — o fluxo de prompt (tick → agente → disco → índice)
+
+Este é o loop completo que transforma um tick autônomo em trabalho real no disco e de volta para a UI.
+
+```mermaid
+flowchart LR
+  T["tick do worker<br/>a cada 60s"] -->|"POST /api/cron/tick"| API["/api/cron/tick<br/>(401 sem x-worker-secret)"]
+  API --> RUN["tickAll({ execute:true, auto:true })"]
+  RUN -->|"por workspace ativo"| TW["tickWorkspace()"]
+  TW --> SPAWN["spawn claude / codex<br/>--output-format json<br/>cwd = workspace da org"]
+  SPAWN -->|"jaula FS safe()"| EDIT["agente edita arquivos"]
+  EDIT --> DISK[("workspace/ no disco")]
+  DISK -->|"chokidar"| WATCH["watcher do worker"]
+  WATCH -->|"POST /api/sync/file"| SYNC["indexFile()"]
+  SYNC --> DB[("índice SQLite")]
+  DB -->|"revalidatePath"| UI["UI Next.js atualiza"]
+  EDIT -.->|"linhas de event (runId, seq)"| DB
+
+  classDef store fill:#1a1a2e,stroke:#e0a44e,color:#fff
+  class DISK,DB store
+```
+
+O run do agente em si (modelo, modo de permissão, pesquisa web, timeouts) é detalhado em [AGENTS](./AGENTS.md) e [AI_ARCHITECTURE](./AI_ARCHITECTURE.md). Arquiteturalmente, o ponto-chave é o **loop fechado**: tick → spawn (CLI enjaulada) → disco → watcher → sync → banco → UI.
+
+---
+
+## 🚀 Passo a passo — rastreando uma única edição de ponta a ponta
+
+1. O cron tick (ou um DM) avança um workspace; o runner faz spawn de um agente CLI com `cwd` = o workspace da org (a jaula FS).
+2. O agente escreve um arquivo (ex.: `Reports/sprint-3.md`). Todas as escritas do código de servidor passam por `writeWorkspaceFile` → `safe()`; a própria CLI é confinada pelo `cwd` + os hooks de guarda/lock.
+3. O chokidar (`awaitWriteFinish`, estabilidade de 300 ms) dispara `add`/`change`.
+4. `parse(abs)` deriva `{orgId, rel}` de `<orgId>/workspace/<rel>` e testa o regex `INDEXED`. Arquivos não indexados são ignorados.
+5. Um debounce de 400 ms por chave coalesce salvamentos rápidos, então `POST /api/sync/file` com `x-worker-secret`.
+6. A rota autentica e chama `indexFile(orgId, rel)` → `indexReportFile` → upsert em `report`, mais `scheduleRagReindex`.
+7. `revalidatePath("/reports")` (e `/code`) atualizam a UI na próxima navegação.
+
+---
+
+## 🌠 Exemplos
+
+**Boot via npm (modo start):**
+```bash
+npx constellai                 # padrão = modo start, 127.0.0.1:3000
+# Constella runtime root : C:\Users\voce\.constella
+# Mode                   : start  ·  127.0.0.1:3000
+# • Starting: next start -H 127.0.0.1 -p 3000  +  worker
+# watching C:\Users\voce\.constella\organizations
+```
+
+**Apontar a raiz de runtime para uma pasta de projeto (dev):**
+```bash
+CONSTELLA_HOME=./.constella npx constellai --start --port 4000
+```
+
+**Rodar web + worker juntos em desenvolvimento (sem instalação global):**
+```bash
+pnpm dev:all       # scripts/dev-all.mjs → next dev + worker (poll do Telegram funciona em dev)
+pnpm start         # scripts/start-all.mjs → next start + worker (build de produção)
+```
+
+**Inspecionar o índice diretamente:**
+```bash
+sqlite3 ~/.constella/constella.db ".tables"
+sqlite3 ~/.constella/constella.db "SELECT handle,status,health FROM agent;"
+```
+
+---
+
+## 🕳️ Estados possíveis
+
+| Superfície | Estados |
+| --- | --- |
+| Filho supervisionado | rodando · auto-reiniciando (`n/5 em 60s`) · desistiu (supervisor sai) |
+| `organization.runMode` | `start` · `vps` · `portable` |
+| `workspace.runMode` | `off` · `start` · `vps` · `portable` (`off` é excluído de `tickAll`) |
+| `workspace.bootstrap` | `pending` · `template-only` · `enriching` · `done` |
+| `agent.status` | `idle` · `working` · `review` · `blocked` |
+| `agent.health` | `alive` · `stale` · `down` |
+| `file.gitStatus` | `""` · `M` · `A` · `U` · `D` |
+| Guarda de base URL do worker | loopback (permitido) · não-loopback + `ALLOW_REMOTE` · recusado (exit 1) |
+
+---
+
+## 🛰️ Integrações relacionadas
+
+- **Endpoints do worker**: `/api/cron/tick`, `/api/sync/file`, `/api/telegram/poll` — todos atrás de `x-worker-secret`.
+- **Telegram** long-poll roda dentro do worker → [TELEGRAM](./TELEGRAM.md).
+- **GitHub** status do git flui para `file.gitStatus` → [GITHUB](./GITHUB.md).
+- **RAG/KB** re-embedding é disparado pelo motor de sincronização → [KB_RAG](./KB_RAG.md), [MEMORY_RAG](./MEMORY_RAG.md).
+- **Public API / MCP** são superfícies de entrada separadas (não usam o worker-secret) → [PUBLIC_API](./PUBLIC_API.md), [MCP](./MCP.md).
+
+---
+
+## 🕳️ Segurança
+
+- **Jaula FS** `safe()` — verificações léxica + de symlink; a raiz do workspace nunca é deletável através dela. O id da org é validado antes de qualquer caminho ser montado.
+- **O segredo do worker falha fechado** — `/api/cron/tick` e `/api/sync/file` rejeitam toda requisição quando nenhum segredo está configurado (um segredo não definido *não* é uma porta aberta).
+- **Guarda SSRF** — o worker só envia seu segredo para loopback a menos que sobrescrito explicitamente; uso remoto em texto-claro é avisado.
+- **Vault** — os segredos vivem só na tabela `vault` (AES-256-GCM via `CONSTELLA_VAULT_KEY`), nunca nas linhas de provider; o `.env` é gravado `0o600`.
+- **Escritor único** — o worker não tem handle de banco; todas as escritas passam pelo processo web, então há uma única autoridade para consistência.
+- Detalhe completo em [SECURITY](./SECURITY.md).
+
+---
+
+## 🌌 Solução de problemas
+
+| Sintoma | Causa provável | Onde olhar |
+| --- | --- | --- |
+| Arquivo editado mas UI desatualizada | watcher não rodando, ou caminho fora de `INDEXED` | logs do worker (`watching …`); regex `INDEXED` em `bin/worker.mjs` |
+| `401 unauthorized` no tick/sync | `CONSTELLA_WORKER_SECRET` divergente entre web + worker | `<HOME>/.env`; ambos os filhos o herdam do launcher |
+| Worker sai no início | `CONSTELLA_BASE_URL` é não-loopback sem override | defina loopback ou `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1` |
+| Dois bancos separados aparecem | servidor standalone faz chdir sem `INIT_CWD` | use `pnpm start` / a CLI (eles definem `INIT_CWD`); veja o aviso em `src/lib/runtime-root.ts` |
+| Banco novo sem tabelas | `drizzle-kit migrate` falhou no primeiro boot | reinstale o pacote; verifique se `drizzle/` é empacotado; o boot aborta numa falha de migrate em banco novo por design |
+| Crash-loop "giving up" | um filho caiu 5× em 60s | veja a dica de OOM; suba `CONSTELLA_WEB_HEAP_MB` se for um OOM de heap JS |
+
+Mais em [TROUBLESHOOTING](./TROUBLESHOOTING.md) e [FAQ](./FAQ.md).
+
+---
+
+## ✦ Links relacionados
+
+- [AI_ARCHITECTURE](./AI_ARCHITECTURE.md) — a camada cognitiva (agentes, RAG, contexto).
+- [AGENTS](./AGENTS.md) — a constelação de 10 agentes e como os runs são iniciados.
+- [CONFIGURATION](./CONFIGURATION.md) — variáveis de ambiente e configurações em profundidade.
+- [INSTALLATION](./INSTALLATION.md) · [START_MODE](./START_MODE.md) · [VPS_MODE](./VPS_MODE.md) · [PORTABLE_MODE](./PORTABLE_MODE.md)
+- [KB_RAG](./KB_RAG.md) · [MEMORY_RAG](./MEMORY_RAG.md) · [SYNCED_BLOCKS](./SYNCED_BLOCKS.md)
+- [SECURITY](./SECURITY.md) · [TROUBLESHOOTING](./TROUBLESHOOTING.md) · [FAQ](./FAQ.md)
+- [TELEGRAM](./TELEGRAM.md) · [GITHUB](./GITHUB.md) · [PUBLIC_API](./PUBLIC_API.md) · [MCP](./MCP.md)

package/docs/pt/CHAT_COMMANDS.md

@@ -0,0 +1,307 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/CHAT_COMMANDS.md) · [✦ Constella](../../README.pt-BR.md)
+
+# 🛰️ Comandos de Chat
+
+![](../assets/divider-orbit.svg)
+
+> Os comandos de barra (slash) são o painel de controle da nave central. Digite um `/comando` na Team Room ou em qualquer DM e o servidor executa uma ação real do lado do servidor, depois publica o resultado de volta no mesmo thread — sem precisar de uma ida e volta com um agente.
+
+---
+
+## 2. Descrição curta
+
+Os comandos de chat são reconhecidos a partir de uma `/` no início da mensagem no caminho de envio. Eles são interceptados **antes** do caminho conversacional normal (o token `[[CREATE_WORK]]` e o roteamento por `@mention`) e executados por `runSlashCommand` em `src/server/commands.ts`. Cada comando publica seu resultado diretamente no canal ativo; alguns também passam a vez para um agente que responde em seguida.
+
+---
+
+## 3. Quando usar
+
+Use comandos de barra quando você quiser uma **ação determinística e imediata** em vez de uma conversa:
+
+- Conduzir o ciclo de trabalho sem prosa: `/approve`, `/run-247`, `/pause`, `/reject`, `/cancel`, `/archive`.
+- Consultar o estado da constelação rapidamente: `/status`, `/agents`, `/agent`, `/locks`, `/models`, `/skills`, `/telegram`.
+- Acessar a nebulosa de memória: `/kb`, `/search`, `/graph`, `/reindex`, `/curate`.
+- Disparar gates e pipelines: `/test-dev`, `/review`, `/github`, `/prepare-deploy`, `/export-source`.
+- Semear novo trabalho ou itens do board: `/new-goal`, `/new-issue`, `/new-spec`, `/generate-plan`, `/assign`, `/close-sprint`.
+
+Para pedidos livres ("construa uma página de cobrança"), basta falar com **@ada** na Team Room ou usar `/new-goal` — veja [DM.md](./DM.md) e [WORKFLOW.md](./WORKFLOW.md).
+
+---
+
+## 4. Como funciona 🌌
+
+O caminho de envio vive em `src/server/chat.ts`. Depois de resolver a organização, o workspace e o roster de agentes, ele inspeciona o texto da mensagem (já com trim):
+
+```ts
+// src/server/chat.ts — slash commands (room + DM, not Telegram)
+const trimmed = (text ?? "").trim();
+if (trimmed.startsWith("/") && channel !== "telegram") {
+  const { runSlashCommand } = await import("@/server/commands");
+  const r = await runSlashCommand(org.id, workspace.id, agents, channel, trimmed);
+  if (r.handled) { revalidatePath("/", "layout"); return { responders: r.responders }; }
+}
+```
+
+Fatos-chave fundamentados no código:
+
+- **Canais**: os comandos de barra são reconhecidos na **Team Room** (`room`) e em **DMs** (`dm:<handle>`). Eles **não** são reconhecidos no canal `telegram` — o Telegram tem seu próprio handler de comando de controle remoto (`handleCommand` em `src/server/telegram.ts`). Veja [TELEGRAM.md](./TELEGRAM.md).
+- **Parsing**: `runSlashCommand` divide no primeiro espaço. O token antes do espaço vira `cmd` em minúsculas; tudo depois vira `rest` (o argumento), com trim.
+- **Eco + resposta**: a maioria dos comandos primeiro ecoa sua entrada bruta com `postOp(...)` (como operador), depois publica um resultado com `post(...)`. O autor do resultado normalmente é `system`, mas vários comandos publicam **como um agente específico** (ex.: Vannevar, Edsger, Werner, Donald, Ada).
+- **Responders**: `runSlashCommand` retorna `{ handled, responders }`. Um array `responders` não vazio significa que o(s) agente(s) nomeado(s) deve(m) responder em seguida — usado por `/new-goal`, `/review`.
+- **Wake**: todo comando tratado chama `wake(wsId)` (via o helper interno `done()`) para acordar o worker/bus.
+- **Sessões**: `ensureActiveSession(wsId, channel)` anexa o resultado à `chatSession` ativa do canal.
+
+### Auto-roteamento da Room
+
+Na Team Room, um texto puro que **não** é um `/comando` e **não** é uma `@mention` recebe automaticamente o prefixo `/kb` antes de ser enviado (veja `welcome-chat.tsx` e `home-command-bar.tsx`). Então digitar `como funciona o auth?` na room equivale a `/kb como funciona o auth?`. Em uma DM, o texto é enviado como está para aquele agente.
+
+### Barra de comando da Home
+
+A barra de comando da Welcome Home (`src/components/modules/home-command-bar.tsx`) reaproveita o mesmo dispatch e mostra um menu de autocomplete para um subconjunto selecionado: `/kb`, `/status`, `/new-goal`, `/agents`, `/reindex`, `/curate`, `/help`. O conjunto completo de comandos abaixo funciona em qualquer input de room/DM, independentemente do menu.
+
+---
+
+## 5. Fluxo principal
+
+```mermaid
+flowchart TD
+  A["Operador digita uma mensagem"] --> B{"começa com '/'\ne channel != telegram?"}
+  B -- "não" --> C["Caminho normal:\nroteamento @mention / auto-rota KB"]
+  B -- "sim" --> D["runSlashCommand(orgId, wsId, agents, channel, raw)"]
+  D --> E["ensureActiveSession + divide cmd / rest"]
+  E --> F{"switch (cmd)"}
+  F --> G["postOp: ecoa a entrada do operador"]
+  G --> H["Executa a ação\n(plan-ops / work-ops / kb / rag / github / …)"]
+  H --> I["publica resultado como system ou um agente nomeado"]
+  I --> J["done(): wake(wsId)\nretorna { handled:true, responders }"]
+  J --> K{"responders não vazio?"}
+  K -- "sim" --> L["Agente responde em seguida\n(ada / revisor)"]
+  K -- "não" --> M["Thread atualizado; sem turno de agente"]
+```
+
+---
+
+## 6. Conceitos-chave 🪐
+
+| Conceito | Significado |
+| --- | --- |
+| `cmd` | O token em minúsculas antes do primeiro espaço (ex.: `/approve`). |
+| `rest` | Texto com trim após o primeiro espaço — o argumento do comando. |
+| `responders` | Handles de agentes que devem responder após o comando (handoff). |
+| `postOp` | Insere sua entrada bruta como mensagem `fromKind: operator`. |
+| `post` | Insere o resultado como `fromKind: agent` com um `fromHandle` (em geral `system`). |
+| `kind` | Dica opcional de renderização: `kb-card`, `agent-card`, `cleared`. |
+| `sources` | Referências de citação anexadas às respostas da KB. |
+| `done()` | Helper interno: chama `wake(wsId)` e retorna `{ handled:true, responders }`. |
+
+---
+
+## 7. O catálogo de comandos (uma grande tabela) ✦
+
+Todo comando reconhecido por `runSlashCommand`, agrupado por categoria. "Responde como" é o `fromHandle` da mensagem de resultado; "Passa a vez" é o agente no array `responders` retornado (responde em seguida).
+
+### Ajuda & informação
+
+| Comando (aliases) | Args | O que faz | Responde como | Passa a vez |
+| --- | --- | --- | --- | --- |
+| `/help` | — | Publica a lista completa de comandos. | `system` | — |
+| `/status` | — | Conta goals ativos, issues abertas (col ≠ `done`) e tasks em andamento (col = `doing`). | `system` | — |
+| `/agents` | — | Lista o roster: `@handle — nome (role, status)`. | `system` | — |
+| `/agent <handle>` | `<handle>` (com ou sem `@`) | Inspeciona um agente: nome, role, status, health, runtime (adapter / model) + link para o Agent Studio. | o próprio handle do agente (card) | — |
+
+### Conhecimento & nebulosa de memória 🌠
+
+| Comando (aliases) | Args | O que faz | Responde como | Passa a vez |
+| --- | --- | --- | --- | --- |
+| `/kb` (`/ask-kb`) | `<pergunta>` | Pergunta à Knowledge Base via `kbAnswer`; responde com referências (`sources`). Respostas de visão geral renderizam como `kb-card`. Agenda um reindex do chat. | `vannevar` | — |
+| `/search <q>` | `<consulta>` | Mesmo motor de `/kb` (`kbAnswer`) — um alias com sabor de busca e seu próprio aviso de argumento vazio. | `vannevar` | — |
+| `/graph <key>` | chave de spec, chave de issue, ou substring do título do goal | Resolve a semente (spec → issue → goal) e mostra o conhecimento conectado via `relatedKnowledge`, agrupado por tipo. | `vannevar` | — |
+| `/reindex` | — | Reconstrói o índice RAG/KB agora (`indexRag`); reporta a contagem de chunks e se foi semântico ou fallback de palavra-chave. | `vannevar` | — |
+| `/curate` | — | Executa o passe de curadoria da KB do Vannevar (`runKbCuration`): dedup / aposentar / re-sumarizar / achar lacunas. Limitado por orçamento. Detalhes em `Reports/kb-health.md`. | `vannevar` | — |
+
+### Ciclo de trabalho 🚀
+
+| Comando (aliases) | Args | O que faz | Responde como | Passa a vez |
+| --- | --- | --- | --- | --- |
+| `/new-goal` (`/new-work`) | `<brief>` | Entrega o brief ao CEO via o pipeline normal de novo trabalho (reenvia como `@ada <brief>`). Agenda um reindex do chat. | (eco do operador) | `ada` |
+| `/generate-plan` | `<brief>` (opcional) | Chama `generatePlanFor` — rascunha specs → issues → TODOs no CEO Planner para aprovação. | `ada` | — |
+| `/approve` | — | Aprova o plano pendente (`approvePlanFor`) e enfileira tasks; reporta a contagem. | `system` | — |
+| `/reject` | `<motivo>` (opcional) | Devolve o plano ao CEO (`requestPlanChangesFor`); registra o motivo se informado. | `system` | — |
+| `/run-247` (`/resume`) | — | Liga a execução autônoma 24/7 (`setAuto247For(..., true)`). | `system` | — |
+| `/pause` | — | Desliga a execução autônoma 24/7 (`setAuto247For(..., false)`). | `system` | — |
+| `/cancel` | — | Cancela o goal **ativo** mais recente (`cancelGoalFor`); a execução para. | `system` | — |
+| `/archive` | — | Arquiva o goal **ativo** mais recente (`archiveGoalFor`); reporta o caminho do arquivo. | `system` | — |
+| `/close-sprint` | — | Fecha a sprint (`closeSprintFor`): conta entregue vs carregado, escreve um arquivo de retro. | `donald` | — |
+
+### Itens do board
+
+| Comando (aliases) | Args | O que faz | Responde como | Passa a vez |
+| --- | --- | --- | --- | --- |
+| `/new-issue <title>` | `<título>` | Cria uma única issue (`col: todo`, `prio: med`) com uma chave numérica auto-incrementada. | `system` | — |
+| `/new-spec <title>` | `<título>` | Cria uma única spec com a chave `SPEC-NN` (com zero à esquerda). | `system` | — |
+| `/assign <issue> <@agent>` | `<chave-da-issue> <@agente>` | Define `issue.assigneeId` para o agente nomeado. | `system` | — |
+
+### Gates, pipelines & integrações 🛰️
+
+| Comando (aliases) | Args | O que faz | Responde como | Passa a vez |
+| --- | --- | --- | --- | --- |
+| `/test-dev` | — | Executa o gate de validação Test Dev (`runTestDevAction`); reporta `PASS`/`FAIL`/`INCONCLUSIVE` + resumo. | `edsger` | — |
+| `/review` | `<nota>` (opcional) | Escolhe um revisor (role CyberSec/QA, senão `whitfield`) e pede que ele revise as mudanças recentes do board. | (eco do operador) | o revisor (ex.: `whitfield`) |
+| `/github` | — | Atualiza o status do repositório (`refreshGitStatus`); reporta a contagem de arquivos alterados. | `werner` | — |
+| `/prepare-deploy` | — | Executa o pipeline Prepare-Deploy (`runDeployPipeline`); reporta status + resumo. | `werner` | — |
+| `/export-source <repo>` | `<repo-do-github>` | Exporta a fonte limpa do produto para um repo separado (`exportCleanSource`); bloqueia se houver achados de segredos. | `werner` | — |
+| `/telegram` | — | Reporta o status da integração com o Telegram (`getTelegramConfig`). | `system` | — |
+| `/models` | — | Reporta o status dos modelos locais: llama.cpp (`llamaServerStatus`) + Ollama (`ollamaInfo`). | `system` | — |
+| `/skills` | — | Reporta o tamanho da biblioteca de skills + uma amostra de nomes (`allLibrarySkillNames`). | `system` | — |
+| `/locks` | — | Lista os file locks atualmente em uso (`activeLocks`): `path — @agente`. | `system` | — |
+
+### Manutenção
+
+| Comando (aliases) | Args | O que faz | Responde como | Passa a vez |
+| --- | --- | --- | --- | --- |
+| `/clear` | `confirm` \| `yes` \| `sim` | Apaga permanentemente TODA mensagem, o resumo compactado e os eventos de execução **deste canal**. Requer um token de confirmação; caso contrário publica um aviso. Board/goals/specs/KB NÃO são afetados. | `system` (kind `cleared`) | — |
+| _desconhecido_ | — | Qualquer outro `/token` ecoa e responde `Unknown command — Try /help`. | `system` | — |
+
+---
+
+## 8. Aliases em um relance
+
+| Canônico | Aliases |
+| --- | --- |
+| `/kb` | `/ask-kb` |
+| `/new-goal` | `/new-work` |
+| `/run-247` | `/resume` |
+
+> Nota: `/cancel` e `/archive` compartilham um mesmo bloco `case`, mas são comandos **distintos** (efeitos diferentes), não aliases um do outro.
+
+---
+
+## 9. Passo a passo
+
+### Aprovar um plano e iniciar o time
+
+1. Na Team Room, digite `/approve`.
+2. O servidor executa `approvePlanFor` e publica `✅ Plan approved — N task(s) queued.` como `system`.
+3. Digite `/run-247` para ligar a execução autônoma 24/7.
+4. Acompanhe o progresso com `/status` e `/locks`.
+
+### Perguntar à nebulosa de memória
+
+1. Digite `/kb como funciona o motor de cálculo?` (ou apenas a pergunta pura na room).
+2. O Vannevar responde com `sources`; uma resposta de visão geral renderiza como `kb-card`.
+3. Se o conhecimento parecer desatualizado, rode `/reindex`, depois `/curate`.
+
+### Inspecionar uma constelação em trabalho
+
+1. `/agents` para ver o roster.
+2. `/agent margaret` para detalhes de runtime + um link para o Agent Studio.
+3. `/locks` para ver quais arquivos os agentes estão segurando.
+
+---
+
+## 10. Exemplos
+
+```text
+/help
+/status
+/agents
+/agent ada
+/kb how does auth work?
+/ask-kb where are sessions stored?
+/search rate limiting
+/graph SPEC-01
+/reindex
+/curate
+/new-goal a billing page with Stripe checkout
+/new-work add 2FA to the login screen
+/generate-plan migrate the database to Postgres
+/approve
+/reject the spec is missing the refund flow
+/run-247
+/resume
+/pause
+/cancel
+/archive
+/new-issue add a logout button
+/new-spec billing architecture
+/assign 3 @margaret
+/test-dev
+/review focus on the new payment endpoint
+/github
+/prepare-deploy
+/export-source myorg/constella-public
+/telegram
+/models
+/skills
+/locks
+/close-sprint
+/clear
+/clear confirm
+```
+
+> Os nomes de comandos, flags e argumentos de exemplo são mantidos em inglês porque são identificadores reais do código.
+
+---
+
+## 11. Estados possíveis 🕳️
+
+| Situação | O que você vê |
+| --- | --- |
+| Argumento vazio em um comando que exige um | Uma dica de uso (ex.: `Ask a question, e.g. /kb …`). |
+| `/agent <handle>` fora do roster | `No agent @handle on the roster. Use /agents …`. |
+| `/cancel` / `/archive` sem goal ativo | `No active goal to cancel/archive.`. |
+| `/assign` malformado | `Usage: /assign <issue-key> <@agent> …`. |
+| `/assign` issue / agente desconhecido | `No issue #key …` / `No agent @handle …`. |
+| `/graph` sem correspondência | `No goal / spec / issue matches …`. |
+| `/graph` com correspondência mas sem conexões ainda | `No connected knowledge for … yet`. |
+| `/reindex` com embed server fora | `… (keyword fallback — embed server down).`. |
+| `/curate` nada a fazer / sem orçamento | `Nothing to curate right now …`. |
+| `/export-source` bloqueado por segredos | `🛑 Export blocked — N secret finding(s).`. |
+| `/clear` sem confirmar | Um aviso `⚠️`; nada apagado. |
+| Comando desconhecido | `Unknown command — Try /help`. |
+
+---
+
+## 12. Integrações relacionadas
+
+- **Plan / work ops** — `/approve`, `/reject`, `/run-247`, `/pause` chamam os cores compartilhados em `src/server/plan-ops.ts` e `src/server/work-ops.ts`, os mesmos usados pela [API Pública](./PUBLIC_API.md) e pelo [Telegram](./TELEGRAM.md).
+- **Knowledge Base / RAG** — `/kb`, `/search`, `/graph`, `/reindex`, `/curate` direcionam para [KB_AGENT.md](./KB_AGENT.md), [KB_RAG.md](./KB_RAG.md) e [MEMORY_RAG.md](./MEMORY_RAG.md).
+- **Pipelines** — `/test-dev` → [TEST_DEV.md](./TEST_DEV.md); `/prepare-deploy` + `/export-source` → [PREPARE_DEPLOY.md](./PREPARE_DEPLOY.md) e [DEPLOY.md](./DEPLOY.md); `/github` → [GITHUB.md](./GITHUB.md).
+- **Modelos & skills** — `/models` → [MODELS.md](./MODELS.md); `/skills` → [SKILLS.md](./SKILLS.md).
+
+---
+
+## 13. Segurança 🔒
+
+- Os comandos de barra rodam **do lado do servidor** sob a sessão do operador — o caminho de envio resolve org/workspace antes do dispatch.
+- `/clear` é o único comando destrutivo sobre os dados da conversa e é **duplamente protegido** (requer `confirm`/`yes`/`sim`). Nunca toca no trabalho do board, goals, specs ou na KB.
+- `/export-source` é **protegido por secret-scan** — recusa o push se houver achados (veja [SECURITY.md](./SECURITY.md)).
+- O Telegram **não** compartilha este parser; seus comandos remotos passam por um handler separado com allowlist — veja [TELEGRAM.md](./TELEGRAM.md).
+- O texto do resultado é truncado em 4000 caracteres na inserção (`text.slice(0, 4000)`).
+
+---
+
+## 14. Solução de problemas
+
+| Sintoma | Causa provável / correção |
+| --- | --- |
+| `/comando` foi tratado como texto puro | Você digitou no canal **Telegram** (usa outro handler) ou com um espaço inicial. A barra precisa ser o primeiro caractere. |
+| Texto puro na room "virou" uma consulta `/kb` | Esperado: a room auto-roteia texto que não é comando nem menção para `/kb`. Prefixe com `@handle` para falar com um agente. |
+| `/reindex` diz "keyword fallback" | O embed server está fora — inicie-o (veja [MEMORY_RAG.md](./MEMORY_RAG.md)). A KB ainda funciona por busca de palavra-chave. |
+| `/approve` / `/cancel` diz "No workspace/active goal" | Ainda não há plano pendente ou goal ativo — crie trabalho com `/new-goal` primeiro. |
+| `/curate` não faz nada | Precisa de algumas entradas na KB **e** orçamento disponível. |
+| Comando desconhecido | Confira a grafia e os aliases acima, ou rode `/help`. |
+
+---
+
+## 15. Links relacionados
+
+- [DM.md](./DM.md) — mensagens diretas com um único agente
+- [TEAM_ROOM.md](./TEAM_ROOM.md) — a room compartilhada e o roteamento por @mention
+- [WORKFLOW.md](./WORKFLOW.md) — o ciclo Goal → Spec → Issue → Plan → Execution
+- [GOALS_SPECS_ISSUES.md](./GOALS_SPECS_ISSUES.md) — itens do board criados por `/new-issue` / `/new-spec`
+- [AGENTS.md](./AGENTS.md) — o roster por trás de `/agents` e `/agent`
+- [KB_AGENT.md](./KB_AGENT.md) · [KB_RAG.md](./KB_RAG.md) · [MEMORY_RAG.md](./MEMORY_RAG.md) — a nebulosa de memória por trás de `/kb`, `/search`, `/graph`, `/reindex`, `/curate`
+- [TEST_DEV.md](./TEST_DEV.md) · [PREPARE_DEPLOY.md](./PREPARE_DEPLOY.md) · [GITHUB.md](./GITHUB.md) — os gates por trás de `/test-dev`, `/prepare-deploy`, `/github`
+- [TELEGRAM.md](./TELEGRAM.md) — o conjunto separado de comandos de controle remoto
+- [PUBLIC_API.md](./PUBLIC_API.md) — as mesmas operações de plan/work via HTTP