constella 0.1.0

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

package/docs/pt/CONFIGURATION.md

@@ -0,0 +1,340 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/CONFIGURATION.md) · [✦ Constella](../../README.pt-BR.md)
+
+# Configuração ✦ 🪐
+
+![](../assets/divider-orbit.svg)
+
+> Todos os controles que pilotam a nave central: variáveis de ambiente, o arquivo de segredos `<HOME>/.env`, o cofre criptografado para chaves de provedores, as portas dos modelos locais e o JSON `settings` que viaja na linha do workspace.
+
+A Constella é configurada em três altitudes, cada uma com seu próprio poço gravitacional:
+
+1. **Flags de inicialização** — escolhidas uma vez por `bin/constella.mjs` (modo de execução, host, porta, raiz de runtime).
+2. **Variáveis de ambiente** — lidas no boot pelo servidor e pelo worker; os segredos são persistidos em `<HOME>/.env`.
+3. **Settings do workspace** — chaves de runtime guardadas como JSON na coluna `workspace.settings`, editáveis pela UI de Config sem reiniciar.
+
+Nada aqui é fake: cada variável abaixo é lida por código real nos caminhos citados.
+
+---
+
+## 1. Quando usar 🛰️
+
+| Você quer… | Use |
+| --- | --- |
+| Trocar o modo de execução (start/auth/vps/portable) | Uma flag de inicialização (`--start`, `--auth`, `--vps`, `--portable`) → `CONSTELLA_RUN_MODE` |
+| Mover a raiz de runtime para fora de `~/.constella` | `CONSTELLA_HOME` ou `--path <dir>` |
+| Vincular a outro host/porta | `--host` / `--port` (ou `PORT`) |
+| Guardar uma chave de API / PAT do GitHub | O **cofre** criptografado (UI), nunca uma variável de ambiente |
+| Apontar para um servidor de modelo local | `LLAMACPP_URL`, `OLLAMA_URL`, `CONSTELLA_EMBED_URL` |
+| Afrouxar/apertar permissões dos agentes | `CONSTELLA_AGENT_FULL_ACCESS`, ou `settings.agents.*` |
+| Limitar execuções simultâneas de agentes | `CONSTELLA_MAX_CONCURRENT_AGENTS` ou `settings.agents.maxConcurrent` |
+
+---
+
+## 2. Como funciona 🌌
+
+O launcher resolve a raiz de runtime e então garante que três segredos de assinatura existam antes do servidor subir:
+
+```mermaid
+flowchart TD
+  A["npx constella [flags]"] --> B["resolve runMode<br/>(flag → compat --bind → start)"]
+  B --> C["resolve HOME<br/>(CONSTELLA_HOME / --path / ~/.constella;<br/>portable → escolher USB)"]
+  C --> D["exporta CONSTELLA_RUN_MODE / PUBLIC / VERSION<br/>DATABASE_URL=file:HOME/constella.db"]
+  D --> E["ensureSecret() ×3 → HOME/.env (chmod 600)"]
+  E --> F["drizzle-kit migrate"]
+  F --> G["sobe web (next start) + worker (bin/worker.mjs)"]
+  G --> H["servidor lê env + workspace.settings"]
+```
+
+**Fato chave (`bin/constella.mjs`):** todo modo persiste um `BETTER_AUTH_SECRET`, `CONSTELLA_VAULT_KEY` e `CONSTELLA_WORKER_SECRET` reais. O `next start` roda sob `NODE_ENV=production`, onde o better-auth lança erro com seu segredo padrão, o cofre se recusa a criptografar sem sua chave e o worker falha fechado sem seu segredo — então até o modo local `start` precisa dos três. Eles são persistidos (não efêmeros) para que sessões de login e o cofre criptografado sobrevivam a um restart.
+
+---
+
+## 3. Fluxo principal: persistência de segredos 🌠
+
+De `bin/constella.mjs` (`ensureSecret`):
+
+1. **env vence** — se a variável já está em `process.env`, usa e não escreve.
+2. **reusa persistido** — senão, se houver um valor não-placeholder em `<HOME>/.env`, hidrata `process.env` a partir dele.
+3. **gera uma vez** — senão, gera um valor novo, grava em `<HOME>/.env` e exporta.
+
+```
+BETTER_AUTH_SECRET      = randomBytes(32).toString("base64url")
+CONSTELLA_VAULT_KEY     = randomBytes(32).toString("base64")    # deve decodificar para 32 bytes
+CONSTELLA_WORKER_SECRET = randomBytes(24).toString("base64url")
+```
+
+O arquivo é escrito com modo `0o600` (e um `chmodSync` best-effort no Windows). O launcher imprime `• Secrets ready (stored in <HOME>/.env, never printed).` — os valores em si nunca são logados.
+
+---
+
+## 4. Conceitos centrais 🪐
+
+- **Raiz de runtime (`<HOME>`)** — padrão `~/.constella`; sobrescrevível com `CONSTELLA_HOME` ou `--path`. Guarda `constella.db`, `.env`, `cache/`, `backups/` e `organizations/<orgId>/workspace/`. No modo portable sem caminho explícito, o launcher detecta drives USB removíveis e usa `<drive>/.constella`.
+- **Raiz do pacote (`CONSTELLA_PKG_ROOT`)** — o diretório do próprio pacote instalado (o `.next` compilado, as migrações `drizzle/`, a biblioteca `skills/` embarcada). Exportada para o servidor achar os assets quando instalado globalmente em vez de a partir do CWD de inicialização.
+- **Cofre (vault)** — chaves de API de provedores e PATs do GitHub são criptografadas em repouso com AES-256-GCM na tabela `vault`, usando `CONSTELLA_VAULT_KEY`. O texto plano **nunca** toca linhas `provider` e **nunca** chega ao cliente (`src/lib/vault.ts`).
+- **Settings do workspace** — um blob JSON em `workspace.settings`; overrides de runtime para permissões de agentes, editor, integrações e metadados de importação.
+
+---
+
+## 5. A grande tabela de variáveis de ambiente 🌌
+
+### 5.1 Núcleo de boot / definido pelo launcher
+
+| Variável | Padrão | Definida por / Lida por | Significado |
+| --- | --- | --- | --- |
+| `CONSTELLA_HOME` | `~/.constella` | launcher / `src/lib/fs-workspace.ts`, `runtime-root.ts`, worker | Raiz de runtime com DB, `.env`, orgs. Valores relativos ancoram em `INIT_CWD`. |
+| `CONSTELLA_RUN_MODE` | `start` | launcher / `src/lib/run-mode.ts`, `cli.ts`, `proxy.ts` | `start \| auth \| vps \| portable`. Dirige login + bind + jaula do agente. |
+| `CONSTELLA_PUBLIC` | `1` (launch CLI) | launcher / `src/lib/build-mode.ts` | Um launch CLI é o runtime público → o seletor de modo na UI fica oculto. |
+| `CONSTELLA_VERSION` | versão do `package.json` local | launcher / `src/lib/version.ts` | Versão instalada confiável para a checagem de Update no app. |
+| `CONSTELLA_PKG_ROOT` | diretório do pacote | launcher / `skills-library.ts`, `cli.ts` | Onde vivem os assets embarcados (`skills/`, `.next`, `drizzle/`). |
+| `DATABASE_URL` | `file:<HOME>/constella.db` | launcher / `src/db/index.ts`, `drizzle.config.mjs` | Arquivo SQLite (absoluto sob a raiz de runtime). |
+| `PORT` | `3000` | env / launcher | Porta web se `--port` não for passado. |
+| `CONSTELLA_FORCE_ONBOARDING` | não definido | `--onboarding` / `src/lib/workspace.ts`, `onboarding.ts` | Força o assistente de primeira execução. |
+| `CONSTELLA_DEV` | não definido | árvore de dev / `build-mode.ts`, launcher | `1` permite fallback para dev-server quando não há build de produção (senão o launcher falha fechado). |
+| `CONSTELLA_WEB_HEAP_MB` | `0` (padrão do Node) | env / launcher | `--max-old-space-size` opcional para o filho web (alívio de OOM de heap JS). |
+
+### 5.2 Segredos (persistidos em `<HOME>/.env`, chmod 600)
+
+| Variável | Gerada como | Lida por | Significado |
+| --- | --- | --- | --- |
+| `BETTER_AUTH_SECRET` | `randomBytes(32).base64url` | `src/lib/auth.ts`, `boot.ts` | Chave de assinatura de sessão. O better-auth lança erro com seu padrão em produção. |
+| `CONSTELLA_VAULT_KEY` | `randomBytes(32).base64` | `src/lib/vault.ts` | Chave AES-256-GCM do cofre de segredos. Deve decodificar para exatamente 32 bytes. |
+| `CONSTELLA_WORKER_SECRET` | `randomBytes(24).base64url` | worker + `/api/cron/tick`, `/api/sync/file`, `/api/telegram/poll`, `/api/locks/acquire` | Segredo compartilhado dos endpoints privilegiados do worker; eles rejeitam toda requisição quando ele não está setado. |
+
+> Os segredos do cofre, auth e worker também estão listados em `src/lib/scrub.ts` para serem removidos da ingestão de KB, mensagens do Telegram e logs.
+
+### 5.3 Worker
+
+| Variável | Padrão | Lida por | Significado |
+| --- | --- | --- | --- |
+| `CONSTELLA_BASE_URL` | `http://localhost:3000` (launcher seta `http://127.0.0.1:<port>`) | `bin/worker.mjs`, `bin/lock-hook.mjs`, `cli.ts` | A URL do servidor local que o worker chama de volta. |
+| `CONSTELLA_WORKER_INTERVAL_MS` | `60000` | `bin/worker.mjs` | Intervalo do tick de cron (POST `/api/cron/tick`). |
+| `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL` | não definido | `bin/worker.mjs` | Override do guard de SSRF: o worker recusa enviar seu segredo a um host não-loopback a menos que isto seja `1`. |
+
+### 5.4 Execução de agentes (`src/server/adapters/cli.ts`, `runner.ts`)
+
+| Variável | Padrão | Significado |
+| --- | --- | --- |
+| `CONSTELLA_AGENT_FULL_ACCESS` | derivado (`start`→full, senão jaulado) | `1`/`0` sobrescreve o modo de permissão. Full → `bypassPermissions` (claude) / `danger-full-access` (codex); jaulado → `acceptEdits` / `workspace-write`. |
+| `CONSTELLA_WEB_RESEARCH` | ligado | `0` desliga o `--allowedTools WebSearch WebFetch` aditivo nas execuções de agente. Também `settings.agents.webResearch`. |
+| `CONSTELLA_AGENT_CMD_GUARD` | ligado | Guard de shell destrutivo (`bin/guard-hook.mjs`). `0` desliga. Também `settings.agents.cmdGuard`. |
+| `CONSTELLA_AGENT_LOCK_HOOK` | desligado | `1` habilita lock por arquivo via `bin/lock-hook.mjs` + um config dir de agente limpo. Também `settings.agents.fileLocks`. |
+| `CONSTELLA_MAX_CONCURRENT_AGENTS` | `1` | Execuções simultâneas de agentes **por workspace** (`runner.ts`). Também `settings.agents.maxConcurrent`. |
+| `CONSTELLA_AUTO_REVIEW` | ligado | `0` desliga o portão de review independente. Também `settings.agents.autoReview`. |
+
+O filho do lock-hook recebe a env de identidade: `CONSTELLA_ORG_ID`, `CONSTELLA_TASK_ID`, `CONSTELLA_AGENT_ID`, `CONSTELLA_AGENT_HANDLE`, mais `CLAUDE_CONFIG_DIR` apontando para o config dir de agente limpo. As execuções de CLI de agentes têm timeout de **180000 ms** por padrão.
+
+### 5.5 Modelos, RAG & KB
+
+| Variável | Padrão | Lida por | Significado |
+| --- | --- | --- | --- |
+| `LLAMACPP_URL` | `http://127.0.0.1:8082` | `local-models.ts`, `runtime.ts`, `kb.ts` | Servidor llama.cpp local de **chat** (compatível com OpenAI `/v1`). |
+| `CONSTELLA_EMBED_URL` | `http://127.0.0.1:8083` | `local-models.ts`, `rag.ts` | Servidor llama.cpp dedicado de **embeddings** para RAG (auto-iniciado no boot). |
+| `OLLAMA_URL` | `http://127.0.0.1:11434` | `local-models.ts`, `runtime.ts`, `rag.ts` | Provedor de fallback de embeddings/chat (Ollama). |
+| `CONSTELLA_EMBED_MODEL` | `nomic-embed-text` | `rag.ts`, `model-catalog.ts` | Nome do modelo de embedding; `nomic*` dispara os prefixos assimétricos `search_document:`/`search_query:`. |
+| `CONSTELLA_KB_CURATION` | ligado | `kb.ts` | `0` opta por sair do passe de curadoria de KB do Vannevar (gatilho por orçamento). |
+
+### 5.6 URLs do better-auth (dev `.env.example`)
+
+| Variável | Exemplo | Significado |
+| --- | --- | --- |
+| `BETTER_AUTH_URL` | `http://localhost:3000` | URL base de auth no servidor. |
+| `NEXT_PUBLIC_BETTER_AUTH_URL` | `http://localhost:3000` | URL base de auth no cliente. |
+
+### 5.7 Clientes fora do processo (baseados em PAT)
+
+| Variável | Padrão | Lida por | Significado |
+| --- | --- | --- | --- |
+| `CONSTELLA_PAT` | não definido | `scripts/mcp-server.mjs` | Personal Access Token `cn_…` para a ponte MCP / API Pública. |
+| `CONSTELLA_ORG` | não definido | `scripts/mcp-server.mjs` | Id de org opcional (mapeia para o header `X-Constella-Org`). |
+
+> `CONSTELLA_BASE_URL` também é lida pelo servidor MCP (padrão `http://localhost:3000`).
+
+---
+
+## 6. Portas 🛰️
+
+| Porta | Processo | Configurável via |
+| --- | --- | --- |
+| `3000` | Servidor web (`next start`) + alvo de callback do worker | `--port` / `PORT`; `CONSTELLA_BASE_URL` para o worker |
+| `8082` | Servidor llama.cpp local de **chat** (`LLAMACPP`) | `LLAMACPP_URL` |
+| `8083` | Servidor llama.cpp local de **embeddings** (RAG) | `CONSTELLA_EMBED_URL` |
+| `11434` | Ollama (embeddings/chat de fallback) | `OLLAMA_URL` |
+
+O harness de Test Dev sobe servidores de dev do projeto em uma porta livre na faixa **4173–4999** (evitando 3000) — veja [TEST_DEV](./TEST_DEV.md).
+
+---
+
+## 7. O arquivo `<HOME>/.env` 🌠
+
+Escrito e relido pelo launcher. Um arquivo gerado mínimo:
+
+```dotenv
+BETTER_AUTH_SECRET=…base64url…
+CONSTELLA_VAULT_KEY=…base64 (32 bytes)…
+CONSTELLA_WORKER_SECRET=…base64url…
+```
+
+O template da árvore de dev `.env.example` mostra a superfície completa usada ao rodar a partir do código-fonte:
+
+```dotenv
+DATABASE_URL=file:./.constella/constella.db
+BETTER_AUTH_SECRET=replace-with-a-long-random-string
+BETTER_AUTH_URL=http://localhost:3000
+NEXT_PUBLIC_BETTER_AUTH_URL=http://localhost:3000
+CONSTELLA_RUN_MODE=start
+CONSTELLA_HOME=./.constella
+CONSTELLA_VAULT_KEY=replace-with-32-byte-base64-key
+CONSTELLA_WORKER_SECRET=replace-with-a-random-string
+```
+
+**Precedência:** `process.env` (shell / Docker / systemd) sempre vence sobre `<HOME>/.env`. O arquivo só fornece valores que ainda não estão no ambiente, e só gera os três segredos de assinatura se nenhuma das fontes os tiver.
+
+---
+
+## 8. O cofre: chaves de provedores & PATs 🕳️
+
+Chaves de API de provedores e PATs do GitHub **nunca** são variáveis de ambiente e **nunca** são colunas em `provider`. Elas vivem criptografadas na tabela `vault`.
+
+```mermaid
+flowchart LR
+  UI["UI de Config: cola chave de API / PAT"] --> P["putSecret(workspaceId, ref, plaintext)"]
+  P --> E["AES-256-GCM<br/>chave = CONSTELLA_VAULT_KEY"]
+  E --> V["linha vault<br/>(ciphertext + iv, por workspace+ref)"]
+  V --> G["getSecret(workspaceId, ref)"]
+  G --> R["resolveRuntime / ghToken / telegram"]
+  V -.->|exibição na UI| M["maskSecret() → abc••••••wxyz"]
+```
+
+Detalhes do cofre (`src/lib/vault.ts`):
+
+- `putSecret` é **valor único por `(workspaceId, ref)`**: deleta a linha antiga antes de inserir, então um token re-registrado nunca serve um valor obsoleto.
+- Exemplos de `ref`: `openai_api_key`, `github_pat`, `telegram_bot_token`.
+- `getSecret` retorna texto plano só no servidor; a UI vê apenas `maskSecret(s)` (`abc••••••wxyz`).
+- `delSecret` sustenta o caminho de revogar token.
+- A tabela `vault` guarda `ciphertext`, `iv`, `ref`, `providerId` opcional, com escopo por `workspaceId` (deletada em cascata com o workspace).
+
+---
+
+## 9. Settings do workspace (JSON em `workspace.settings`) 🪐
+
+A coluna `settings` (`src/db/schema.ts`) é um blob JSON tipado. Editável pela UI de Config sem reiniciar; o runner empurra as flags de agente para o adapter de CLI antes de cada spawn.
+
+| Caminho | Tipo | Efeito |
+| --- | --- | --- |
+| `editor.tabSize` / `formatOnSave` / `wordWrap` / `minimap` | number / bool | Preferências do editor de código no app. |
+| `integrations` | `Record<string, boolean>` | Mapa de habilitação por integração. |
+| `lastSecurityRun` | number | Timestamp da última varredura de segurança. |
+| `telegram.offset` | number | Cursor do `getUpdates` do Telegram. |
+| `github.repo` / `login` / `defaultBranch` | string | Metadados do repositório GitHub conectado. |
+| `source.type` | `new \| github \| local \| mock` | Como o workspace foi importado. |
+| `source.repo` / `branch` / `localPath` / `importedAt` / `fileCount` / `analyzed` | misto | Proveniência da importação. |
+| `agents.maxConcurrent` | number | Concorrência de agentes por workspace (sobrescreve `CONSTELLA_MAX_CONCURRENT_AGENTS`). |
+| `agents.fileLocks` | bool | Lock por arquivo (sobrescreve `CONSTELLA_AGENT_LOCK_HOOK`). |
+| `agents.webResearch` | bool | Pesquisa web (sobrescreve `CONSTELLA_WEB_RESEARCH`). |
+| `agents.autoReview` | bool | Portão de review independente (sobrescreve `CONSTELLA_AUTO_REVIEW`). |
+| `agents.cmdGuard` | bool | Guard de shell destrutivo (sobrescreve `CONSTELLA_AGENT_CMD_GUARD`). |
+
+**Precedência de override para as chaves de agente:** o valor por workspace `settings.agents.*` (quando setado) é empurrado em runtime e vence; se não setado, vale o padrão da env `CONSTELLA_*` correspondente. Outros padrões de modelo/runtime vivem na `workspace.stack` (JSON `Record<string,string>`) e nas linhas `agent`, `provider` e `organization.runMode`.
+
+---
+
+## 10. Passo a passo
+
+1. **Primeiro boot** — rode `npx constella` (ou uma flag de modo). O launcher cria `<HOME>/organizations`, gera `<HOME>/.env`, migra o DB e sobe web + worker.
+2. **Escolha um modo** — passe `--start` / `--auth` / `--vps` / `--portable`. A flag seta `CONSTELLA_RUN_MODE`, que dirige login, host de bind e a jaula do agente. Veja [START_MODE](./START_MODE.md), [AUTH_MODE](./AUTH_MODE.md), [VPS_MODE](./VPS_MODE.md), [PORTABLE_MODE](./PORTABLE_MODE.md).
+3. **Mova a raiz de runtime** — `CONSTELLA_HOME=/data/constella npx constella` ou `--path /mnt/usb`.
+4. **Adicione uma chave de provedor** — na UI de Config, cole-a; ela é guardada no cofre, não escrita no `.env`.
+5. **Ajuste os agentes** — alterne `settings.agents.*` na UI, ou defina os padrões da env `CONSTELLA_*`.
+6. **Aponte para modelos locais** — suba seus servidores llama.cpp/Ollama e defina `LLAMACPP_URL` / `CONSTELLA_EMBED_URL` / `OLLAMA_URL` se não estiverem nos padrões.
+
+---
+
+## 11. Exemplos
+
+**Porta customizada + folga de heap:**
+
+```bash
+npx constella --auth --port 4000
+CONSTELLA_WEB_HEAP_MB=4096 npx constella --vps
+```
+
+**Realocar a raiz de runtime e o DB:**
+
+```bash
+CONSTELLA_HOME=/srv/constella npx constella --vps
+# DATABASE_URL resolve para file:/srv/constella/constella.db
+```
+
+**Permitir mais agentes simultâneos e desligar o portão de review (env):**
+
+```bash
+CONSTELLA_MAX_CONCURRENT_AGENTS=2 CONSTELLA_AUTO_REVIEW=0 npx constella
+```
+
+**Pilotar a Constella pela API Pública / MCP a partir de outro host:**
+
+```bash
+export CONSTELLA_PAT=cn_xxx
+export CONSTELLA_BASE_URL=http://localhost:3000
+export CONSTELLA_ORG=<orgId>
+node scripts/mcp-server.mjs
+```
+
+---
+
+## 12. Estados possíveis
+
+| Condição | Comportamento resultante |
+| --- | --- |
+| `CONSTELLA_VAULT_KEY` ausente | `vault.key()` lança `CONSTELLA_VAULT_KEY is not set`; segredos não podem ser lidos/escritos. |
+| `CONSTELLA_VAULT_KEY` não tem 32 bytes | Lança `CONSTELLA_VAULT_KEY must decode to 32 bytes`. |
+| `CONSTELLA_WORKER_SECRET` não setado | Endpoints do worker rejeitam toda requisição (falha fechado). |
+| `BETTER_AUTH_SECRET` padrão em produção | better-auth lança no boot — daí o launcher sempre gerar um. |
+| Sem build de produção, `CONSTELLA_DEV` ≠ `1` | Launcher recusa subir dev server em modo público/de rede e sai. |
+| Portable, `< 32 GB` livres | Fatal: launcher aborta abaixo de 32 GB; ≥ 32 GB dá boot. |
+| Worker com `CONSTELLA_BASE_URL` não-loopback, sem override | Worker sai em vez de vazar seu segredo. |
+
+---
+
+## 13. Integrações relacionadas
+
+- Chaves/modelos de provedores — [MODELS](./MODELS.md), [AI_ARCHITECTURE](./AI_ARCHITECTURE.md)
+- PAT/OAuth do GitHub — [GITHUB](./GITHUB.md)
+- Token do bot do Telegram — [TELEGRAM](./TELEGRAM.md)
+- Clientes PAT/MCP — [PUBLIC_API](./PUBLIC_API.md), [MCP](./MCP.md)
+- Embeddings de RAG — [KB_RAG](./KB_RAG.md), [MEMORY_RAG](./MEMORY_RAG.md)
+
+---
+
+## 14. Segurança 🕳️
+
+- O arquivo de segredos `<HOME>/.env` é escrito com `chmod 600`; valores nunca são impressos.
+- O cofre usa **AES-256-GCM** com `CONSTELLA_VAULT_KEY`; só ciphertext + IV, nunca texto plano ao cliente.
+- `src/lib/scrub.ts` remove `CONSTELLA_VAULT_KEY`, `BETTER_AUTH_SECRET` e `CONSTELLA_WORKER_SECRET` antes da ingestão de KB, do Telegram e dos logs.
+- O worker aplica um **guard de SSRF apenas-loopback** em `CONSTELLA_BASE_URL`.
+- `process.env` sempre sobrescreve o arquivo `.env` — operadores controlam a configuração via shell/Docker/systemd, não via um arquivo gravável por atacante.
+- As permissões dos agentes degradam com segurança: acesso total só no modo `start` (sua própria máquina); `vps/auth/portable` ficam jaulados (Docker + Tailscale como jaula dura). Veja [SECURITY](./SECURITY.md).
+
+---
+
+## 15. Solução de problemas
+
+| Sintoma | Causa provável | Correção |
+| --- | --- | --- |
+| `CONSTELLA_VAULT_KEY is not set` | `.env` deletado ou chave apagada | Restaure `<HOME>/.env` ou deixe o launcher regerar (atenção: uma chave nova não decripta linhas antigas do cofre). |
+| Worker loga `401` repetidamente | Telegram não configurado / segredo divergente | Configure o bot, confirme que `CONSTELLA_WORKER_SECRET` é compartilhado. |
+| Worker recusa subir (não-loopback) | `CONSTELLA_BASE_URL` é remoto | Use loopback, ou defina `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1` (prefira `https://`). |
+| RAG cai para busca por palavra-chave | Servidor de embed fora do ar na `:8083` | Suba-o / defina `CONSTELLA_EMBED_URL`, ou dependa do Ollama em `:11434`. |
+| App lê um DB diferente do que o worker observa | `CONSTELLA_HOME` relativo divergente | Use um `CONSTELLA_HOME` absoluto; caminhos relativos ancoram em `INIT_CWD`. |
+| Agentes falam na voz do plugin do operador | Hooks do `~/.claude` do operador vazando | Já mitigado pela overlay de settings `disableAllHooks`; verifique o config dir de lock/guard. |
+
+---
+
+## Links relacionados
+
+- [INSTALLATION](./INSTALLATION.md) · [ONBOARDING](./ONBOARDING.md) · [START_MODE](./START_MODE.md) · [AUTH_MODE](./AUTH_MODE.md) · [VPS_MODE](./VPS_MODE.md) · [PORTABLE_MODE](./PORTABLE_MODE.md)
+- [ARCHITECTURE](./ARCHITECTURE.md) · [AI_ARCHITECTURE](./AI_ARCHITECTURE.md) · [AGENTS](./AGENTS.md)
+- [MODELS](./MODELS.md) · [KB_RAG](./KB_RAG.md) · [MEMORY_RAG](./MEMORY_RAG.md)
+- [GITHUB](./GITHUB.md) · [TELEGRAM](./TELEGRAM.md) · [PUBLIC_API](./PUBLIC_API.md) · [MCP](./MCP.md)
+- [TEST_DEV](./TEST_DEV.md) · [SECURITY](./SECURITY.md) · [TROUBLESHOOTING](./TROUBLESHOOTING.md) · [FAQ](./FAQ.md)