constella 0.1.0

package/docs/pt/DEPLOY.md

@@ -0,0 +1,331 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/DEPLOY.md) · [✦ Constella](../../README.pt-BR.md)
+
+# Deploy (Produção) 🚀
+
+![](../assets/divider-orbit.svg)
+
+Como **lançar a própria nave central** — colocar o plano de controle Constella em uma órbita durável, de produção. Esta página trata do deploy do *Constella enquanto plataforma*: Docker em uma VPS, o bootstrap `vps-install.sh`, Tailscale, boot supervisionado de dois processos e instalações portátil/global.
+
+> **Não confundir com [PREPARE_DEPLOY](./PREPARE_DEPLOY.md) / [DEPLOY do seu projeto].** Aqueles fazem o deploy do **projeto do usuário** que os agentes constroem (exportação de árvore limpa para um repositório separado). *Esta* página faz o deploy do **próprio Constella** — a nave, não a carga.
+
+---
+
+## Quando usar 🌌
+
+| Você quer… | Use |
+| --- | --- |
+| Rodar o Constella 24/7 em um servidor remoto, privado para o seu tailnet | **VPS / Docker** (`Dockerfile` + `docker-compose.yml`) |
+| Provisionar uma VPS Ubuntu nova em um comando | **`scripts/vps-install.sh`** |
+| Carregar todo o plano de controle em um pen-drive | **Portátil** (`constella --portable`) |
+| Instalar uma vez na sua máquina sempre ligada | **npm global** (`npm i -g constella`) |
+| Uma execução efêmera rápida | **`npx constella`** |
+
+Se você só quer uma instância local no seu notebook, veja [START_MODE](./START_MODE.md) e [AUTH_MODE](./AUTH_MODE.md). Para os detalhes do tailnet, veja [VPS_MODE](./VPS_MODE.md); para o pen-drive, [PORTABLE_MODE](./PORTABLE_MODE.md).
+
+---
+
+## Como funciona 🪐
+
+Toda inicialização do Constella — local, VPS, portátil — passa pelo mesmo lançador, **`bin/constella.mjs`**. O lançador:
+
+1. Resolve o **modo de execução** (`start | auth | vps | portable`) a partir da flag de lançamento.
+2. Resolve a **raiz de runtime** `HOME` (`CONSTELLA_HOME` / `--path`, padrão `~/.constella`).
+3. Gera + persiste segredos em `<HOME>/.env` (`chmod 600`): `BETTER_AUTH_SECRET`, `CONSTELLA_VAULT_KEY`, `CONSTELLA_WORKER_SECRET`.
+4. Fixa `DATABASE_URL=file:<HOME>/constella.db` e aplica as migrações Drizzle empacotadas (`drizzle-kit migrate`).
+5. Inicia **dois processos supervisionados**: o servidor **web** (`next start`) e o **worker** (`bin/worker.mjs`).
+
+Um deploy é "o mesmo lançador, em um lugar mais durável" — dentro de um container, em um pen-drive ou sob uma instalação global. O modo define o host de bind e a postura de autenticação; o destino do deploy define a durabilidade.
+
+```mermaid
+flowchart TD
+  A["operador"] --> B["bin/constella.mjs (lançador)"]
+  B --> C{"modo de execução"}
+  C -->|"--vps"| D["Docker + Tailscale<br/>(0.0.0.0, só no tailnet)"]
+  C -->|"--portable"| E["raiz no pen-drive<br/>(0.0.0.0)"]
+  C -->|"--start / --auth"| F["host local<br/>(127.0.0.1)"]
+  B --> G["next start (web :3000)"]
+  B --> H["bin/worker.mjs (cron + watcher + Telegram)"]
+  G -. "supervisionado, auto-restart" .- B
+  H -. "supervisionado, auto-restart" .- B
+```
+
+---
+
+## Fluxo principal — VPS via Docker + Tailscale 🛰️
+
+O deploy recomendado para produção. O Constella roda em um container, faz bind em `0.0.0.0` e é alcançável **apenas** pelo seu tailnet Tailscale — nunca pela internet aberta.
+
+### A imagem — `Dockerfile`
+
+Um build multi-estágio sobre `node:22-bookworm-slim`:
+
+| Estágio | O que faz |
+| --- | --- |
+| `base` | `corepack enable`; instala `git ca-certificates` |
+| `deps` | `pnpm install --frozen-lockfile` |
+| `build` | `pnpm build` (com `NEXT_TELEMETRY_DISABLED=1`) |
+| `runtime` | define `NODE_ENV=production`, `CONSTELLA_RUN_MODE=vps`, `CONSTELLA_PUBLIC=1`, `CONSTELLA_HOME=/data`; roda como o usuário não-privilegiado `node`; `VOLUME ["/data"]`; `EXPOSE 3000` |
+
+Entrypoint:
+
+```dockerfile
+CMD ["node", "bin/constella.mjs", "--vps", "--host", "0.0.0.0", "--port", "3000"]
+```
+
+> **As CLIs dos agentes NÃO vêm na imagem.** A nota do Dockerfile é explícita: para agentes em uma VPS, ou adicione um passo `RUN` que instale uma CLI (`claude` / `codex`), ou use **provedores de API na nuvem** configurados no módulo [MODELS](./MODELS.md). Veja [Segurança](#segurança-).
+
+### O stack — `docker-compose.yml`
+
+Dois serviços compartilham um único namespace de rede, então o Constella nunca ganha sua própria porta pública:
+
+| Serviço | Imagem / build | Papel |
+| --- | --- | --- |
+| `tailscale` | `tailscale/tailscale:latest` | Sidecar; entra no seu tailnet de forma headless via `TS_AUTHKEY`; `hostname: constella`; persiste estado no volume `tailscale-state` |
+| `constella` | `build: .` | A aplicação; `network_mode: service:tailscale` (compartilha a rede do sidecar); persiste `/data` no volume `constella-data` |
+
+`network_mode: service:tailscale` é o pivô de segurança: o Constella fica alcançável **no IP do Tailscale na porta 3000** e em nenhum outro lugar. Ambos os serviços usam `restart: unless-stopped`.
+
+```mermaid
+flowchart LR
+  subgraph host["host VPS"]
+    subgraph ns["namespace de rede compartilhado"]
+      TS["sidecar tailscale<br/>(entra no tailnet)"]
+      CN["app constella<br/>:3000, 0.0.0.0"]
+    end
+    V1[("constella-data<br/>volume /data")]
+    V2[("tailscale-state")]
+  end
+  CN --- V1
+  TS --- V2
+  Dev["seu dispositivo<br/>(mesmo tailnet)"] -. "http://<ts-ip>:3000" .-> TS
+```
+
+### Bootstrap em um comando — `scripts/vps-install.sh`
+
+Para um Ubuntu Server novo. O script (`set -euo pipefail`) faz, em ordem:
+
+1. **Docker** — `curl -fsSL https://get.docker.com | sh` (só se `docker` estiver ausente).
+2. **Tailscale** — `curl -fsSL https://tailscale.com/install.sh | sh` (só se ausente).
+3. `sudo tailscale up` — entra no seu tailnet (imprime uma URL de auth no navegador se necessário).
+4. **Chave de auth** — se o `.env` não tiver `TS_AUTHKEY=`, ele pede para você colar uma chave `tskey-auth-…` (criada em `https://login.tailscale.com/admin/settings/keys`) e a anexa ao `.env`.
+5. **Up** — `sudo docker compose up -d --build`.
+6. Imprime a URL alcançável: `http://<tailscale-ip>:3000`.
+
+---
+
+## Passo a passo
+
+### A) Deploy VPS a partir de um clone
+
+```bash
+# na VPS, com o repositório clonado
+bash scripts/vps-install.sh
+# → instala Docker + Tailscale, pede o TS_AUTHKEY, sobe o stack
+```
+
+Ou faça manualmente (espelha o cabeçalho do compose):
+
+```bash
+# 1. Obtenha uma chave de auth do Tailscale:
+#    https://login.tailscale.com/admin/settings/keys
+echo "TS_AUTHKEY=tskey-auth-..." > .env
+# 2. Build + start
+docker compose up -d --build
+# 3. Alcance o Constella no IP Tailscale do node:
+#    http://<ip-tailscale-deste-node>:3000
+tailscale ip -4   # descubra o IP
+```
+
+No primeiro boot o lançador gera e persiste o `BETTER_AUTH_SECRET` (e os segredos de vault + worker) em `/data/.env`. Como `/data` é o volume nomeado `constella-data`, esses segredos — e as sessões de login e o vault criptografado — **sobrevivem a reinícios e rebuilds**.
+
+### B) Deploy portátil (USB)
+
+```bash
+npx constella --portable                 # detecta e escolhe um pen-drive
+npx constella --portable --path /Volumes/MYUSB   # ou nomeie o drive
+```
+
+O lançador valida o drive **antes** de iniciar: ele **recusa < 32 GB livres** (fatal); `≥ 32 GB` dá boot. Faz bind em `0.0.0.0`. Toda a raiz de runtime fica em `<drive>/.constella`. Veja [PORTABLE_MODE](./PORTABLE_MODE.md).
+
+### C) Instalação global (máquina própria sempre ligada)
+
+```bash
+npm i -g constella
+constella --auth        # email+senha, 127.0.0.1
+# ou --start para auto-login local, ou --vps em um servidor que você administra
+```
+
+### D) Efêmera
+
+```bash
+npx constella           # modo padrão = start
+```
+
+---
+
+## Boot supervisionado de dois processos 🌠
+
+Um plano de controle 24/7 precisa sobreviver a uma falha transitória. O `bin/constella.mjs` inicia **dois filhos** e supervisiona cada um:
+
+| Processo | Comando | Hospeda |
+| --- | --- | --- |
+| **web** | `next start -H <host> -p <port>` (a partir de `PKG_ROOT`) | o dashboard + todas as rotas de API |
+| **worker** | `node bin/worker.mjs` | cron tick (~60s → `POST /api/cron/tick`), file-watcher chokidar (debounce 400ms → `/api/sync/file`), long-poll do Telegram |
+
+Regras de supervisão (de `supervise()`):
+
+- Em uma saída inesperada de um filho, **auto-restart após 2s** — não um shutdown completo.
+- **Guarda anti-crash-loop:** no máximo **5 reinícios em 60s** por filho; além disso, desiste e desliga (para que uma falha real e repetida não seja mascarada para sempre).
+- Web e worker são **independentes**: uma falha do web reinicia só o web; o worker re-tenta seu tick sozinho até o servidor responder.
+- Aumento de heap opcional: `CONSTELLA_WEB_HEAP_MB` adiciona `--max-old-space-size` ao filho web (útil quando uma execução de agente causa OOM de heap JS).
+
+> **Não há unidade systemd empacotada no repositório** — *não encontrado no código atual*. O próprio supervisor do lançador + o `restart: unless-stopped` do Docker são a camada de durabilidade. Se você quiser supervisão no nível do SO, envelope `constella --vps` (ou `--auth`) na sua própria unidade; o processo é um comando de longa duração em foreground normal e trata `SIGINT`/`SIGTERM` de forma limpa (mata ambos os filhos, depois sai).
+
+O worker carrega o header privilegiado `x-worker-secret`, então tem uma **guarda SSRF**: ele se recusa a falar com qualquer `CONSTELLA_BASE_URL` que não seja loopback, a menos que `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1`. O lançador sempre o aponta para `http://127.0.0.1:<port>` (loopback mesmo em vps/portable), então isso é invisível em deploys normais.
+
+---
+
+## Modos de execução vs destinos de deploy
+
+O **modo** (de `src/lib/run-mode.ts`) define o host de bind e a postura de login; o **destino de deploy** define onde ele roda fisicamente. Eles se combinam:
+
+| Modo | `requiresLogin` | Host de bind | Destino de deploy típico | Permissão da CLI do agente |
+| --- | --- | --- | --- | --- |
+| `start` | false (auto-login `operator@constella.dev`) | `127.0.0.1` | máquina local / npx | `bypassPermissions` (total) |
+| `auth` | true (email+senha) | `127.0.0.1` | local sempre ligado / instalação global | `acceptEdits` (no jail) |
+| `vps` | true | `0.0.0.0` | **Docker + Tailscale** | `acceptEdits` (no jail) |
+| `portable` | true | `0.0.0.0` | **pen-drive USB** | `acceptEdits` (no jail) |
+
+O modo é persistido em `organization.runMode`. Em um build publicado `CONSTELLA_PUBLIC=1`, então a **UI nunca escolhe o modo** — a flag de lançamento escolhe.
+
+---
+
+## Conceitos-chave
+
+- **`CONSTELLA_HOME` / raiz de runtime** — o diretório durável único. No Docker é `/data` (um volume nomeado); no USB é `<drive>/.constella`; caso contrário `~/.constella`. Guarda `constella.db`, `.env`, `organizations/<orgId>/workspace/`, `backups/`, `cache/`.
+- **`PKG_ROOT`** — a raiz do *pacote instalado* (`.next` compilado, migrações `drizzle/`, configs). O lançador roda `next` e `drizzle-kit` a partir daqui, não do CWD de lançamento.
+- **Persistência de segredos** — todo modo persiste segredos reais em `<HOME>/.env` (`mode 0600`). O `next start` roda sob `NODE_ENV=production`, onde o better-auth **lança erro com um segredo padrão**, então um `BETTER_AUTH_SECRET` real é obrigatório mesmo localmente.
+- **Schema no primeiro boot** — `drizzle-kit migrate` é idempotente. Um **DB novo que falha na migração aborta** (sem tabelas = a app dá 500); um DB existente tolera uma reexecução no-op.
+- **Build no primeiro boot (só fallback)** — o pacote publicado já traz um `.next` pré-construído, então o build é pulado. A partir de uma árvore de código sem build ele constrói uma vez; se o build falhar ele **se recusa a cair para `next dev`** em um modo público/de rede, a menos que `CONSTELLA_DEV=1`.
+
+---
+
+## Ambiente do lançador
+
+O lançador exporta isto para ambos os filhos:
+
+| Variável | Valor |
+| --- | --- |
+| `CONSTELLA_RUN_MODE` | `start \| auth \| vps \| portable` |
+| `CONSTELLA_PUBLIC` | `1` (lançamento por CLI é o runtime público) |
+| `CONSTELLA_VERSION` | a versão do pacote instalado |
+| `CONSTELLA_HOME` | raiz de runtime resolvida |
+| `DATABASE_URL` | `file:<HOME>/constella.db` |
+| `CONSTELLA_PKG_ROOT` | a raiz do pacote instalado |
+| `PORT` / `--port` | `3000` (padrão) |
+| `--host` | `0.0.0.0` para vps/portable, senão `127.0.0.1` |
+
+Persistidos em `<HOME>/.env` (`chmod 600`): `BETTER_AUTH_SECRET`, `CONSTELLA_VAULT_KEY`, `CONSTELLA_WORKER_SECRET`. Só do compose: `TS_AUTHKEY` (chave de entrada do sidecar Tailscale) no `.env` da raiz do repositório.
+
+Ajustes opt-in:
+
+| Variável | Efeito |
+| --- | --- |
+| `CONSTELLA_WEB_HEAP_MB` | `--max-old-space-size` para o filho web (padrão: padrão do Node) |
+| `CONSTELLA_DEV=1` | permite o fallback `next dev` quando não há build de produção |
+| `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1` | deixa o worker falar com uma base URL não-loopback (desligado por padrão) |
+| `CONSTELLA_WORKER_INTERVAL_MS` | intervalo do cron tick (padrão `60000`) |
+
+---
+
+## Atualizando um deploy 🛰️
+
+`detectRunContext()` (`src/lib/run-context.ts`) classifica o processo em execução para que o **método de atualização combine com o deploy**:
+
+| Contexto | Detectado quando | Método de atualização |
+| --- | --- | --- |
+| `dev` | rodando do código (`isDevMode()`) | `git pull && pnpm install && pnpm build` |
+| `vps` | `getRunMode() === "vps"` **ou** `/.dockerenv` existe | `docker compose pull && docker compose up -d` |
+| `portable` | `getRunMode() === "portable"` | garantir espaço livre, fazer backup do drive, então `npm install -g constella@latest` |
+| `npx` | o diretório de lançamento é o cache `_npx` do npm | reexecutar `npx constella@latest` |
+| `global` | nenhum dos acima | `npm install -g constella@latest` (auto-executa, destacado) |
+
+`startUpdate()` (`src/server/update-run.ts`) **sempre faz backup primeiro** — copia `.env`, `constella.db`, `constella.db-wal`, `constella.db-shm` para `<HOME>/backups/<timestamp>/`. Apenas o caminho `global` auto-executa (um processo destacado escreve `<HOME>/backups/last-update.json` que a UI consulta); `vps` / `portable` / `dev` / `npx` retornam o **comando exato** a rodar, porque executá-los de dentro do servidor web é específico do ambiente. Veja [UPDATE](./UPDATE.md).
+
+```bash
+# em uma VPS:
+docker compose pull && docker compose up -d
+```
+
+Como `/data` (ou o `.constella` do USB) é um volume persistente, o DB e os segredos atravessam a atualização; o `drizzle-kit migrate` idempotente do lançador avança o schema no próximo boot.
+
+---
+
+## Estados possíveis
+
+| Sinal | Significado |
+| --- | --- |
+| `• Secrets ready (stored in <HOME>/.env, never printed).` | geração/reuso de segredos no primeiro boot OK |
+| `✖ Portable needs at least 32 GB free …` | drive portátil pequeno demais (fatal) |
+| `• N GB free on the drive — good …` | drive portátil com espaço suficiente, dá boot |
+| `✖ Database schema migration failed on a fresh database — aborting` | DB novo não conseguiu suas tabelas |
+| `• schema migrate skipped/failed on an existing DB — continuing` | reexecução benigna em um DB já construído |
+| `✖ No production build … Refusing to start a dev server in a public/network mode.` | sem `.next` e sem `CONSTELLA_DEV=1` |
+| `• [web] exited (…) — auto-restarting in 2s (n/5 …)` | reinício supervisionado dentro da janela |
+| `✖ [web] exited … crashed 5x within 60s — giving up.` | limite de crash-loop atingido; desligando |
+| `✓ Constella is starting. Reach it on your tailnet at: http://<ip>:3000` | `vps-install.sh` terminou |
+
+---
+
+## Integrações relacionadas 🪐
+
+- **Tailscale** — o plano de rede privada para o modo VPS (container sidecar + IP do tailnet). Veja [VPS_MODE](./VPS_MODE.md).
+- **Docker / docker compose** — o runtime + política de restart.
+- **better-auth** — email+senha (+ 2FA/passkeys) para todo modo de rede; respaldado por `BETTER_AUTH_SECRET`. Veja [AUTH_MODE](./AUTH_MODE.md).
+- **Vault** — chaves de provedores criptografadas com `CONSTELLA_VAULT_KEY`. Veja [SECURITY](./SECURITY.md).
+- **Worker** — cron + watcher + Telegram, supervisionado junto ao web. Veja [TELEGRAM](./TELEGRAM.md), [ARCHITECTURE](./ARCHITECTURE.md).
+- **Update** — auto-atualização ciente do contexto. Veja [UPDATE](./UPDATE.md).
+
+---
+
+## Segurança 🕳️
+
+- **Exposição só no tailnet.** Com o compose, o Constella compartilha o namespace de rede do sidecar Tailscale, então o dashboard é alcançável **apenas no IP Tailscale na :3000**, nunca na internet aberta. A porta do host nunca é publicada diretamente.
+- **Usuário de container não-privilegiado.** O estágio `runtime` roda como o usuário interno `node` (uid 1000), não root — um RCE no nível da app não pode agir como root sobre `/data`.
+- **Login obrigatório em todo modo de rede.** `vps`, `auth` e `portable` definem `requiresLogin: true` (better-auth email+senha, 2FA TOTP / passkeys WebAuthn opcionais, sessão de 30 dias).
+- **Agentes em jail fora do local.** Em `vps`/`auth`/`portable` a CLI do agente roda em `acceptEdits` (edições confinadas ao FS jail do workspace), não no `bypassPermissions` do modo local `start`.
+- **CLIs dos agentes não empacotadas.** A imagem omite `claude`/`codex` de propósito. Para rodar agentes em uma VPS, adicione uma CLI em um passo `RUN` ou use provedores de API na nuvem em [MODELS](./MODELS.md). Sem nenhum dos dois, planejamento/Team-Room funcionam, mas a execução de agentes não tem runtime.
+- **Segredos nunca impressos.** `<HOME>/.env` é `chmod 600`; o lançador só registra sua localização. O `scrubSecrets` remove segredos antes do ingest na KB / Telegram / logs.
+- **Guarda SSRF do worker.** O worker se recusa a enviar seu segredo privilegiado para qualquer base URL não-loopback, a menos que explicitamente habilitado.
+
+---
+
+## Solução de problemas 🛰️
+
+| Sintoma | Causa / correção |
+| --- | --- |
+| Não alcança `http://<ip>:3000` de outro dispositivo | o dispositivo não está no mesmo tailnet; rode `tailscale up` nele, confirme com `tailscale status` |
+| O sidecar não entra | `TS_AUTHKEY` inválida/expirada; gere uma nova chave e `docker compose up -d` |
+| A app reinicia em loop | verifique a RAM do host — uma execução de agente causando OOM no nível do SO mata o `next start`; aumente `CONSTELLA_WEB_HEAP_MB` para OOM de heap JS, ou limite os agentes concorrentes |
+| `✖ drizzle-kit not found …` | a instalação está incompleta; reinstale o pacote/reconstrua a imagem |
+| DB novo aborta na migração | migrações `drizzle/` empacotadas ausentes ou `/data` sem permissão de escrita; confirme que o volume é de dono `node:node` |
+| Agentes não executam na VPS | sem CLI de agente na imagem e sem provedor na nuvem configurado — adicione um passo `RUN` de CLI ou configure [MODELS](./MODELS.md) |
+| Sessões/vault perdidos após rebuild | `/data` (ou `.constella` do USB) não era um volume persistente; segredos regenerados. Mantenha o volume nomeado |
+| Portátil se recusa a dar boot | drive com menos de 32 GB livres — use um drive maior (`--path`) |
+| Update não fez nada em uma VPS | por design: rode `docker compose pull && docker compose up -d` você mesmo (a UI retorna o comando) |
+
+---
+
+## Links relacionados
+
+- [VPS_MODE](./VPS_MODE.md) — o modo de execução por tailnet em detalhe
+- [PORTABLE_MODE](./PORTABLE_MODE.md) — deploy por pen-drive USB
+- [START_MODE](./START_MODE.md) · [AUTH_MODE](./AUTH_MODE.md) — modos de execução locais
+- [INSTALLATION](./INSTALLATION.md) — primeira instalação
+- [CONFIGURATION](./CONFIGURATION.md) — variáveis de ambiente + raiz de runtime
+- [UPDATE](./UPDATE.md) — auto-atualização ciente do contexto
+- [PREPARE_DEPLOY](./PREPARE_DEPLOY.md) — deploy do **projeto do usuário** (exportação de árvore limpa), não do Constella
+- [ARCHITECTURE](./ARCHITECTURE.md) — web + worker, motor de sync
+- [SECURITY](./SECURITY.md) — FS jail, vault, scrubbing
+- [MODELS](./MODELS.md) — provedores na nuvem/locais para agentes em um servidor
+- [TROUBLESHOOTING](./TROUBLESHOOTING.md) · [FAQ](./FAQ.md)

package/docs/pt/DM.md

@@ -0,0 +1,297 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/DM.md) · [✦ Constella](../../README.pt-BR.md)
+
+# Mensagens Diretas — Órbitas Privadas 🛰️✦
+
+![](../assets/divider-orbit.svg)
+
+Uma **Mensagem Direta** (DM) é um canal privado 1:1 entre você (o operador) e um único agente — uma pequena órbita própria, separada da [Sala da Equipe](./TEAM_ROOM.md). DMs carregam sessões (contextos novos sob demanda), compactação por sessão, anexos, captura na Base de Conhecimento e — quando você fala com um **planejador** como a Ada — a capacidade de transformar um pedido em trabalho real, com aprovação obrigatória.
+
+## Quando usar
+
+- Você quer uma conversa **1:1 focada** com um agente (a CEO, o CTO, a líder de QA, o redator de Docs) sem acionar a sala inteira.
+- Você quer **iniciar novo trabalho** simplesmente descrevendo-o para a **@ada** (ou outro planejador) — sem botão solto de "novo trabalho".
+- Você quer **múltiplos fios paralelos** com o mesmo agente, cada um com seu próprio contexto novo (as **sessões** de DM).
+- Você quer **anexar arquivos** (imagens / PDFs / documentos) para um agente ler em privado.
+- Você quer manter uma conversa **fora da cadeia autônoma de repasse** — DMs nunca repassam para colegas de equipe.
+
+> 🪐 Canais num relance: `room` (todos, exige @menção), `dm:<handle>` (1:1 privado, este documento), `telegram` (fio remoto isolado → Ada). Veja [Sala da Equipe](./TEAM_ROOM.md), [Comandos de Chat](./CHAT_COMMANDS.md) e [Telegram](./TELEGRAM.md).
+
+## Como funciona
+
+Toda conversa no Constella vive em um **canal** — uma string simples na tabela `message`. Um canal de DM é literalmente a string `dm:<handle>`, ex.: `dm:ada`, `dm:linus`, `dm:edsger`. O handle depois de `dm:` é o handle do agente no elenco (veja [Agentes](./AGENTS.md)).
+
+A maquinaria de DM vive em três arquivos:
+
+| Arquivo | Responsabilidade |
+| --- | --- |
+| `src/server/chat.ts` | Ações voltadas ao operador: `sendMessage`, `agentRespond`, ações de **sessão** de DM, limpar/prévias. |
+| `src/server/collab.ts` | O turno real do agente (`replyInChannel`): monta o prompt, roda a CLI, contabiliza custo, captura KB. |
+| `src/server/sessions.ts` | Ciclo de vida das sessões de DM: `ensureActiveSession`, `sessionsFor`, `newSession`, `activateSession`, `renameSessionRow`, `deleteSessionRow`. |
+| `src/server/compaction.ts` | `buildChannelContext` — dobra mensagens antigas em um resumo por sessão quando o canal excede a janela do modelo. |
+
+### Roteando uma mensagem até um respondente
+
+Quando você envia para um canal `dm:<handle>`, `sendMessage` decide quem responde (`src/server/chat.ts`):
+
+```ts
+if (channel.startsWith("dm:")) {
+  const h = channel.slice(3); if (handles.has(h)) responders = [h];
+}
+```
+
+Logo, uma DM resolve para **exatamente um respondente** — o agente nomeado pelo canal. Compare com:
+
+- **`room`** — a mensagem precisa `@mencionar` um colega real; até **3** respondentes (`mentions(...).slice(0, 3)`); uma mensagem na sala sem menção é descartada (nada de post sem saída).
+- **`telegram`** — sempre roteia para **ada** (a CEO), caindo para o primeiro agente se não houver handle `ada`.
+
+Após persistir sua mensagem, `sendMessage` ainda: acorda qualquer stream SSE aberto (`wake`), agenda uma reindexação RAG da conversa (`scheduleChatReindex`) e — **somente na `room`** para texto substantivo (≥15 chars) — registra uma decisão do operador. (DMs **não** registram decisões.)
+
+### A resposta real do agente
+
+`agentRespond(channel, handle)` muda o agente para `working`, depois chama `replyInChannel` em `collab.ts`, onde o trabalho real acontece:
+
+1. Monta uma instrução em **modo chat** (DMs são sempre `mode: "chat"` — conversacional, *sem edição de arquivos*; só a cadeia de repasse da sala usa `mode: "work"`).
+2. Anexa blocos de cláusulas: uma **cláusula de plano** (token de novo trabalho, abaixo), uma **cláusula de anexos** (ler arquivos enviados), uma **cláusula de idioma** (espelhar o idioma do operador só no chat — tudo escrito no workspace permanece em inglês), além das cláusulas de conhecimento **REMEMBER** / **CONSULT** / **KB** e uma **cláusula de segurança do Telegram** (canais de DM pulam essa — é exclusiva do `telegram`).
+3. Monta UM pacote de contexto ajustado ao modelo (`assembleAgentPrompt`) — missão, estado do projeto, decisões, conversa **desta sessão** (compactada), RAG, memória.
+4. Resolve o runtime (`resolveRuntime`) e roda a CLI / API HTTP (`runAgentRuntime`, timeout de 180 s), transmitindo eventos ao vivo para sua visão.
+5. Remove o token de novo trabalho, extrai aprendizados `[[REMEMBER …]]` para a KB, responde consultas `[[CONSULT: …]]` (devolvidas como **Vannevar**), roda ferramentas `[[KB: …]]`, **filtra segredos** e persiste a resposta na **sessão ativa**.
+6. Contabiliza custo real em `costEntry`.
+
+> 🕳️ Diferença crucial em relação à sala: ao final, a sala dispara a cadeia de repasse (`relayRoomMentions`), mas **DMs permanecem 1:1** — `if (!channel.startsWith("dm:")) await relayRoomMentions(...)`. Uma `@menção` dentro de uma resposta de DM **não** acorda outro agente.
+
+## Fluxo principal
+
+```mermaid
+sequenceDiagram
+  actor Op as Operador
+  participant Chat as chat.ts
+  participant Sess as sessions.ts
+  participant Collab as collab.ts (replyInChannel)
+  participant CLI as Runtime do agente (claude/codex)
+  participant DB as message / costEntry
+
+  Op->>Chat: sendMessage("dm:linus", text, attachments?)
+  Chat->>Chat: responder = "linus" (único)
+  Chat->>Sess: ensureActiveSession(ws, "dm:linus")
+  Chat->>DB: insere mensagem do operador (sessionId)
+  Chat-->>Op: { responders: ["linus"] }
+  Op->>Chat: agentRespond("dm:linus", "linus")
+  Chat->>Collab: replyInChannel(..., mode "chat")
+  Collab->>CLI: roda com pacote de contexto montado
+  CLI-->>Collab: texto da resposta (+ tokens REMEMBER/CONSULT/KB)
+  Collab->>DB: insere mensagem do agente (sessão ativa) + costEntry
+  Note over Collab: DM → SEM relayRoomMentions (permanece 1:1)
+  Collab-->>Op: resposta transmitida
+```
+
+## Conceitos-chave
+
+### Sessões de DM 🌠
+
+Um canal de DM pode conter **múltiplas sessões**. Uma sessão é uma linha em `chat_session` escopada a `(workspaceId, channel)`; exatamente **uma fica ativa** por canal. Iniciar uma nova sessão dá ao agente um **contexto novo** enquanto você mantém todas as mensagens passadas visíveis — você apenas troca qual fio está vendo.
+
+- `ensureActiveSession(ws, channel)` retorna o id da sessão ativa, criando preguiçosamente a **"Session 1"** na primeira vez que uma DM é tocada, e **adotando** quaisquer mensagens legadas sem sessão para ela. Retorna `null` para canais não-DM (a sala e o Telegram são de fio único e nunca recebem sessões).
+- `newSession` desativa as outras e cria `Session N` (ativa).
+- `activateSession` troca qual sessão está ativa.
+- `renameSessionRow` renomeia (≤60 chars).
+- `deleteSessionRow` apaga a sessão **e suas mensagens**; se ela era a ativa, ativa a sessão remanescente mais nova (ou nenhuma — `ensureActiveSession` recria a "Session 1" no próximo toque).
+
+`getMessages("dm:<handle>")` e `clearConversation` ambos escopam à **sessão ativa** para DMs, então uma nova sessão é uma página genuinamente em branco.
+
+### Compactação (por sessão) 🌌
+
+Quando uma conversa excede a janela de contexto do modelo ativo, `buildChannelContext` (`compaction.ts`) dobra as mensagens **mais antigas** em um resumo estruturado e mantém apenas as mais recentes na íntegra. Para DMs isso é **escopado à sessão ativa** (`sessionId`), então cada fio compacta de forma independente:
+
+```ts
+const msgConds = [eq(message.workspaceId, workspaceId), eq(message.channel, channel)];
+if (sessionId) msgConds.push(eq(message.sessionId, sessionId));
+```
+
+- O resumo é **ciente do modelo** — modelos menores recebem um resumo mais enxuto (~150 palavras), maiores mantêm mais detalhe (~350 palavras).
+- As seções são fixas: `## Decisions`, `## Requirements`, `## Open issues`, `## Files`, `## Pending by agent`, `## Next steps`.
+- A sumarização roda em um **modelo barato (`haiku`)** e contabiliza custo real.
+- Uma linha `message_summary` por `(workspace, channel, session)`; ela guarda `throughId` (última mensagem dobrada) para que uma janela inalterada seja reaproveitada, não re-resumida.
+- O bloco compactado também é vinculado em `.claude/memory.md` (uma seção por canal), best-effort.
+
+### Novo trabalho a partir de uma DM 🚀
+
+Este é o recurso assinatura das DMs. **Novo trabalho nasce da conversa com a CEO — não de um botão solto.** Em **modo chat**, o prompt de qualquer agente inclui uma **cláusula de plano**: se o operador estiver pedindo para **CONSTRUIR / IMPLEMENTAR / ADICIONAR / CORRIGIR / MUDAR** algo (uma nova unidade de trabalho), o agente confirma em 1–2 frases e emite, numa linha final separada, o token de máquina:
+
+```
+[[CREATE_WORK]]
+```
+
+`collab.ts` define isso como `const CREATE_WORK = "[[CREATE_WORK]]"`. `replyInChannel` o detecta (`planRequested`) e **o remove** antes de a resposta ser armazenada ou mostrada. De volta em `chat.ts`, `agentRespond` reage:
+
+```ts
+if (planRequested) {
+  const r = await planFromConversation(channel);
+  // posta uma breve confirmação "registrando isto como novo trabalho…" de volta na DM
+}
+```
+
+`planFromConversation(channel)` (em `src/server/planner.ts`) pega as **últimas 30 mensagens** do canal e roda o **mesmo ritual de planejamento do primeiro plano** — a Ada (a CEO) rascunha um Goal → specs → issues → TODOs, anexados ao **CEO Planner** para sua aprovação. (Para o remoto do Telegram, o gêmeo off-session é `planFromConversationFor` em `planner-core.ts`.)
+
+> 🌠 Planejador vs não-planejador. A cláusula de plano é oferecida a **todos** os agentes, mas a redação difere:
+> - **Planejadores** (`isPlanner`: a CEO **ada**, o Product Owner **donald**, o CTO **linus** — ou qualquer papel que case com *product owner* / *CTO* / *chief tech*) recebem uma instrução direta "transforme isto em um spec + issues".
+> - **Não-planejadores** recebem uma garantia extra: isso *"runs through the CEO's planning ritual and waits for the operator's approval, so you're not committing anyone to build immediately."*
+>
+> De qualquer modo o pedido é **roteado pelo planner da CEO e travado pela sua aprovação** — nada de código construído diretamente de uma DM. Veja [Metas, Specs e Issues](./GOALS_SPECS_ISSUES.md) e [Fluxo de Trabalho](./WORKFLOW.md).
+
+### Captura de conhecimento numa DM 🌌
+
+Mesmo numa DM privada o agente pode fazer crescer o cérebro compartilhado (veja [Agente de KB](./KB_AGENT.md) e [KB & RAG](./KB_RAG.md)):
+
+| Token (linha própria) | Efeito |
+| --- | --- |
+| `[[REMEMBER type=<decision\|architecture\|business-rule\|integration\|fix\|note>: <fato>]]` | Salvo automaticamente na KB (deduplicado), token removido da resposta exibida. |
+| `[[CONSULT: <pergunta>]]` | Respondido pela KB ciente de estado; a resposta é postada de volta na DM **como Vannevar**. |
+| `[[KB: reindex \| index-chat \| health]]` | Manutenção do agente de KB (só o papel de Conhecimento recebe essa cláusula); resultado reportado de volta no fio. |
+
+Você também pode promover uma única linha de chat para a KB com `sendMessageToKb(messageId)` (capturada como `note`), ou puxar contexto da KB para o compositor com `pullKbForComposer(query)` (apenas rascunho — nunca envia).
+
+## Tabelas
+
+### `chat_session` (`src/db/schema.ts`)
+
+| Coluna | Tipo | Notas |
+| --- | --- | --- |
+| `id` | text PK | |
+| `workspaceId` | text | FK → `workspace`, delete em cascata. |
+| `channel` | text | Sempre `dm:<handle>` (apenas DM). |
+| `title` | text | Padrão `Session N`; renomeia ≤60 chars. |
+| `active` | boolean | Exatamente uma ativa por `(workspace, channel)`. |
+| `createdAt` | timestamp | Ordenação mais-nova-primeiro na lista de sessões. |
+
+### `message` (colunas relevantes a DM)
+
+| Coluna | Notas |
+| --- | --- |
+| `channel` | `room` \| `dm:<handle>` \| `telegram`. |
+| `fromKind` | `operator` \| `agent`. |
+| `fromHandle` | O handle do agente (null para operador). |
+| `text` | Corpo da mensagem (respostas do agente armazenadas ≤4000 chars). |
+| `sessionId` | A `chat_session` a que esta mensagem pertence. **NULL** para room/Telegram e mensagens de DM legadas (retroalimentadas para a "Session 1"). |
+| `sources` | Chips de fonte RAG para a resposta de um agente. |
+| `attachments` | Uploads do operador (≤10/mensagem): `{ name, type, size, path }`. |
+| `taskId` / `kind` / `blocks` | Chip de rastreabilidade / dica de render / slugs de synced-block. |
+
+### `message_summary`
+
+| Coluna | Notas |
+| --- | --- |
+| `channel` | A conversa sumarizada. |
+| `sessionId` | Sessão de DM que este resumo cobre; **NULL** para room/Telegram. |
+| `summary` | Contexto compactado estruturado. |
+| `throughId` | Última mensagem dobrada (guarda de reaproveitamento). |
+| `msgCount` | Número de mensagens dobradas. |
+
+## Diagrama de novo-trabalho-a-partir-de-DM
+
+```mermaid
+flowchart TD
+  A["Operador manda DM @ada:\n'construir um export CSV'"] --> B["sendMessage('dm:ada', …)\nresponder = ada"]
+  B --> C["agentRespond → replyInChannel\n(mode: chat, cláusula de plano ON)"]
+  C --> D{"Operador pedindo para\nCONSTRUIR / CORRIGIR / MUDAR?"}
+  D -- "Não" --> E["Resposta 1:1 normal\n(permanece na DM)"]
+  D -- "Sim" --> F["Resposta confirma + emite\n[[CREATE_WORK]] na última linha"]
+  F --> G["token removido\nplanRequested = true"]
+  G --> H["planFromConversation(channel)\núltimas 30 mensagens → brief"]
+  H --> I["Ritual de planejamento da CEO:\nGoal → specs → issues → TODOs"]
+  I --> J["Anexado ao CEO Planner\n(aguarda aprovação do operador)"]
+  J --> K["'Plan ready' volta\ntransmitido para a DM"]
+```
+
+## Passo a passo
+
+### Iniciar novo trabalho a partir de uma DM
+
+1. Abra a DM com a **@ada** (CEO) — ou outro planejador como **@linus** / **@donald**.
+2. Descreva o trabalho de forma simples: *"Construir uma página de configurações com um interruptor de modo escuro."*
+3. A Ada confirma ("registrando isto como novo trabalho…") e a rodada pesada de plano começa destacada.
+4. Uma mensagem **"Plan ready"** volta transmitida para a DM quando specs + issues são rascunhados.
+5. Aprove no **CEO Planner** (ou via `/approve` — veja [Comandos de Chat](./CHAT_COMMANDS.md)). A aprovação é o que autoriza a equipe a construir.
+
+### Gerenciar sessões de DM
+
+1. Numa DM, abra a lista de sessões (mais-nova-primeiro; uma ativa).
+2. **Nova sessão** → contexto novo do agente, fios antigos preservados (`createSession`).
+3. **Trocar** entre sessões (`switchSession`); **renomear** (`renameSession`); **apagar** (`deleteSession`, confirmado por um modal).
+4. **Limpar conversa** numa DM apaga só as mensagens da **sessão ativa** + seu resumo — outras sessões ficam intactas.
+
+### Anexar um arquivo a uma DM
+
+1. Adicione até 10 arquivos ao compositor; eles são salvos em `uploads/` no workspace.
+2. O prompt do agente ganha uma cláusula de anexos apontando para os **caminhos** em disco; ele os lê com suas ferramentas de arquivo (imagens/PDFs suportados).
+3. Nomes de arquivo são tratados como **dados, não instruções** (guarda contra prompt-injection).
+
+## Exemplos
+
+```text
+# DM com @ada — dispara novo trabalho
+Você → @ada: Precisamos de um export CSV na página de relatórios.
+Ada → Got it — I'll turn this into a spec + issues and register it for approval. [[CREATE_WORK]] (removido)
+Ada → Got it — registering this as new work. I'm drafting the plan now…
+
+# DM com @edsger (líder de QA) — uma pergunta, NÃO novo trabalho → resposta normal, sem token
+Você → @edsger: O que a última rodada de testes apontou em /login?
+Edsger → A última rodada apontou 1 erro de console em /login (uncaught TypeError)…
+
+# Não-planejador roteando um pedido de build ainda passa pelo planner da Ada
+Você → @grace: Adicionar um spinner de carregamento ao dashboard.
+Grace → I'll register this as new work — it runs through the CEO's planning ritual and waits for your approval. [[CREATE_WORK]] (removido)
+```
+
+## Estados possíveis
+
+| Estado | Significado |
+| --- | --- |
+| Respondente resolvido | Canal de DM `dm:<h>` → respondente único `h` se o handle existir; senão `responders: []`. |
+| `mode: "chat"` | Respostas de DM são conversacionais — **sem edição de arquivos**, sem cadeia de repasse. |
+| `planRequested = true` | O agente emitiu `[[CREATE_WORK]]`; `planFromConversation` roda o ritual. |
+| Sessão ativa | Uma `chat_session.active = true` por DM; dirige leituras, escritas, compactação, limpeza. |
+| Compactado | Mensagens antigas dobradas em `message_summary` para a sessão ativa. |
+| Agente `working` / `idle` | `agentRespond` define `working` durante o turno, de volta a `idle` depois. |
+
+## Integrações relacionadas
+
+- **[Sala da Equipe](./TEAM_ROOM.md)** — o canal compartilhado; a cadeia de repasse por `@menção` (que as DMs deliberadamente evitam).
+- **[Telegram](./TELEGRAM.md)** — o fio remoto isolado que sempre fala com a Ada; espelha de volta a partir da aba Telegram no app.
+- **[Comandos de Chat](./CHAT_COMMANDS.md)** — comandos slash funcionam em DMs também (interceptados antes do caminho de mensagem; não no Telegram).
+- **[Metas, Specs e Issues](./GOALS_SPECS_ISSUES.md)** / **[Fluxo de Trabalho](./WORKFLOW.md)** — onde o trabalho nascido em DM aterrissa e é aprovado.
+- **[KB & RAG](./KB_RAG.md)** / **[Memória & RAG](./MEMORY_RAG.md)** — captura REMEMBER/CONSULT e reindexação da conversa.
+- **[Inbox](./INBOX.md)** — pings ao operador levantados quando um agente o endereça (pulados no Telegram).
+
+## Segurança
+
+- **Filtragem de segredos** — toda resposta (room, DM, Telegram) passa por `scrubSecrets` antes de ser armazenada, mostrada ou notificada.
+- **Anexos são dados** — nomes/caminhos de arquivos enviados são envoltos como dados; o prompt diz ao modelo para ignorar qualquer diretiva embutida num nome de arquivo.
+- **Endurecimento contra prompt-injection** é mais forte no `telegram` (entrada remota não confiável); DMs são entrada local do operador mas ainda assim filtradas e presas por idioma/workspace.
+- **DMs não se ramificam** — uma `@menção` numa resposta de DM nunca acorda outro agente, então um fio privado não pode disparar uma cadeia autônoma.
+- **Sem build direto do chat** — uma DM só pode *registrar* trabalho; nada executa até você aprovar o plano. Veja [Segurança](./SECURITY.md) e [Arquitetura de IA](./AI_ARCHITECTURE.md) para a prisão de FS e os modos de permissão.
+
+## Solução de problemas
+
+| Sintoma | Causa provável / correção |
+| --- | --- |
+| O agente não respondeu na minha DM | O handle depois de `dm:` precisa existir no elenco; uma string de canal errada produz `responders: []`. Confira o handle em [Agentes](./AGENTS.md). |
+| Pedi um build mas nenhum plano apareceu | O modelo julgou que era uma pergunta, não novo trabalho, então não emitiu `[[CREATE_WORK]]`. Seja explícito: *"Construir/implementar/corrigir …"*. A DM deve então postar uma linha "registrando isto como novo trabalho…". |
+| Nova sessão ainda mostra mensagens antigas | Você está vendo uma sessão anterior — troque para a ativa. Leituras são escopadas à `chat_session` ativa. |
+| "Limpar conversa" não limpou tudo | Numa DM, limpar só apaga a **sessão ativa**; outras sessões persistem por design. |
+| Uma `@menção` na minha DM não fez nada | Correto — DMs são 1:1 e nunca repassam. Use a [Sala da Equipe](./TEAM_ROOM.md) para repasses. |
+| Contexto antigo continua voltando | É o resumo compactado por sessão (`message_summary`) sendo injetado. Inicie uma sessão nova para um contexto limpo. |
+| Resposta deu timeout | O limite do runtime é 180 s; turnos únicos muito pesados podem atingi-lo. |
+
+## Links relacionados
+
+- [Sala da Equipe](./TEAM_ROOM.md)
+- [Comandos de Chat](./CHAT_COMMANDS.md)
+- [Telegram](./TELEGRAM.md)
+- [Agentes](./AGENTS.md)
+- [Metas, Specs e Issues](./GOALS_SPECS_ISSUES.md)
+- [Fluxo de Trabalho](./WORKFLOW.md)
+- [KB & RAG](./KB_RAG.md)
+- [Memória & RAG](./MEMORY_RAG.md)
+- [Inbox](./INBOX.md)
+- [Arquitetura de IA](./AI_ARCHITECTURE.md)
+- [Segurança](./SECURITY.md)