constella 0.1.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 modo de execução** — a flag explícita (`--start|--auth|--vps|--portable`) vence, depois o legado `--bind`, padrão `start`. Veja [START_MODE](./START_MODE.md), [AUTH_MODE](./AUTH_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 \| auth \| vps \| portable`. |
+| `CONSTELLA_PUBLIC` | launcher (`=1`) | Um lançamento por CLI é o runtime público → o seletor de modo 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\|auth\|vps\|portable`), `archived` | Tenant. `runMode` é o modo 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 constella                 # 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 constella --auth --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` · `auth` · `vps` · `portable` |
+| `workspace.runMode` | `off` · `start` · `auth` · `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) · [AUTH_MODE](./AUTH_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/AUTH_MODE.md

@@ -0,0 +1,247 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/AUTH_MODE.md) · [✦ Constella](../../README.pt-BR.md)
+
+# Modo Auth 🛰️
+
+![](../assets/divider-orbit.svg)
+
+> Barreira real de e-mail + senha na frente da nave central — para quando mais de um humano compartilha a mesma máquina, mas você ainda quer um plano de controle privado, restrito ao loopback.
+
+O modo Auth é o run mode em que toda sessão precisa passar por uma barreira de credencial. Diferente do modo `start` (que cria e autentica automaticamente um operador local), o modo `auth` exibe a tela de login real, assina as sessões com um `BETTER_AUTH_SECRET` obrigatório e suporta 2FA por TOTP e passkeys WebAuthn. Ele continua escutando em `127.0.0.1`, então a superfície é a mesma órbita local do `start` — apenas a porta da frente fica trancada.
+
+---
+
+## ✦ Quando usar
+
+Use o modo `auth` quando:
+
+- Uma **estação compartilhada** hospeda o Constella e você não quer que qualquer pessoa com acesso físico entre direto no app.
+- Você quer uma **conta real** (e-mail + senha, opcionalmente 2FA / passkey) em vez da conta auto-provisionada `operator@constella.dev`.
+- Você quer assinatura de sessão com um **segredo persistido**, mas ainda quer manter o listener no loopback (sem exposição de rede).
+
+Escolha outro modo quando:
+
+| Você quer… | Use |
+|---|---|
+| Local sem fricção, usuário único, sem login | [START_MODE](./START_MODE.md) |
+| Acesso remoto por uma tailnet privada, em Docker | [VPS_MODE](./VPS_MODE.md) |
+| Todo o runtime carregado em um pen-drive USB | [PORTABLE_MODE](./PORTABLE_MODE.md) |
+
+---
+
+## 🌌 Como funciona
+
+`auth` é um dos quatro valores de `RunMode` definidos em `src/lib/run-mode.ts`:
+
+```ts
+export type RunMode = "start" | "auth" | "vps" | "portable";
+
+export const RUN_MODES: Record<RunMode, { label: string; requiresLogin: boolean; note: string }> = {
+  start:    { label: "Start",    requiresLogin: false, note: "Local auto-created account · always signed in." },
+  auth:     { label: "Auth",     requiresLogin: true,  note: "Email + password required each session." },
+  vps:      { label: "VPS",      requiresLogin: true,  note: "Access over your Tailscale tailnet; runs in Docker." },
+  portable: { label: "Portable", requiresLogin: true,  note: "USB drive mounted as root across machines." },
+};
+```
+
+O modo é selecionado pela flag de launch em `bin/constella.mjs` e exportado para o ambiente como `CONSTELLA_RUN_MODE`. O servidor o lê de volta com `getRunMode()`; `requiresLogin()` retorna `true` para `auth`.
+
+Três pilares definem o modo:
+
+1. **`requiresLogin: true`** — `requireWorkspace()` (em `src/lib/workspace.ts`) envia uma requisição não autenticada para `/login`, não para `/api/dev-login`. Não há login automático.
+2. **`BETTER_AUTH_SECRET` obrigatório** — todo modo com capacidade de rede (`auth`, `vps`, `portable`) precisa subir com um segredo de assinatura real ou se recusa a servir (veja [Segurança](#-segurança)).
+3. **Bind em `127.0.0.1`** — `auth` mantém o mesmo host de loopback do `start`; apenas `vps` e `portable` fazem bind em `0.0.0.0`.
+
+### A superfície de login (`better-auth`)
+
+`src/lib/auth.ts` configura o `better-auth` com:
+
+- **E-mail + senha** sempre habilitados (`emailAndPassword: { enabled: true, autoSignIn: true, requireEmailVerification: false }`).
+- **2FA por TOTP** via plugin `twoFactor()` (Profile → Security).
+- **Passkeys WebAuthn** via rotas customizadas `/api/passkey/*` construídas sobre `@simplewebauthn` (o formulário de login oferece um botão de passkey).
+- **Provedores sociais** (GitHub / Google) apenas quando as credenciais de ambiente estão presentes — usados para vinculação de conta, não como caminho de auth primário.
+- **Sessões de 30 dias** (`expiresIn: 60 * 60 * 24 * 30`).
+- **Cookies Secure** sempre que a base URL for `https://` (`useSecureCookies: BASE_URL.startsWith("https://")`). No `auth` puro sobre http local, os cookies ficam relaxados; atrás de um reverse proxy https eles viram `Secure`.
+
+---
+
+## 🚀 Fluxo principal
+
+```mermaid
+flowchart TD
+  A["constella --auth"] --> B["bin/constella.mjs<br/>CONSTELLA_RUN_MODE=auth<br/>host = 127.0.0.1"]
+  B --> C["ensureSecret() persiste<br/>BETTER_AUTH_SECRET em ~/.constella/.env"]
+  C --> D["boot.ts → assertAuthSecret()"]
+  D -->|segredo presente| E["servidor serve"]
+  D -->|segredo ausente| X["process.exit(1)"]
+  E --> F["browser acessa qualquer página (app)"]
+  F --> G["requireWorkspace()"]
+  G -->|sem sessão| H["redirect /login"]
+  H --> I["LoginForm: e-mail + senha"]
+  I -->|2FA habilitado| J["código TOTP → verifyTotp"]
+  I -->|passkey| K["/api/passkey/authenticate"]
+  J --> L["cookie de sessão definido · redirect /"]
+  K --> L
+  I -->|senha ok, sem 2FA| L
+  G -->|sessão ok| M["workspace escopado retornado"]
+```
+
+---
+
+## 🪐 Conceitos-chave
+
+| Conceito | Onde | Significado |
+|---|---|---|
+| `RunMode` | `src/lib/run-mode.ts` | `"auth"` é um dos quatro modos; governa login + comportamento de bind. |
+| `requiresLogin()` | `src/lib/run-mode.ts` | Retorna `true` para `auth` — o app exige uma credencial. |
+| `assertAuthSecret()` | `src/lib/auth.ts` | Barreira rígida de boot: recusa rodar um modo de rede sem `BETTER_AUTH_SECRET`. |
+| `requireWorkspace()` | `src/lib/workspace.ts` | Guard por página; redireciona requisições `auth` não autenticadas para `/login`. |
+| `LoginForm` | `src/app/(auth)/login/login-form.tsx` | UI de e-mail/senha + 2FA + passkey. |
+| `auth` (better-auth) | `src/lib/auth.ts` | O servidor de auth configurado (e-mail/senha, 2FA, social, sessões). |
+| `createSessionCookie()` | `src/server/passkey-login.ts` | Emite uma sessão real do better-auth após uma asserção de passkey. |
+| `member.role` | `src/db/schema.ts` | `owner` \| `admin` \| `member` — papéis de membro da organização. |
+
+### `auth` vs `start` — o contraste
+
+`start` e `auth` compartilham o mesmo host de loopback e o mesmo runtime de processo duplo; eles diferem inteiramente na **porta da frente**.
+
+| Dimensão | `start` | `auth` |
+|---|---|---|
+| `requiresLogin` | `false` | `true` |
+| Tela de login | pulada | exibida (`/login`) |
+| Conta | auto-provisionada `operator@constella.dev` / `operator123` | uma conta real que você cria/acessa |
+| Login automático | sim — `/api/dev-login` | não |
+| `BETTER_AUTH_SECRET` | persistido, mas não estritamente exigido por `assertAuthSecret()` | **obrigatório** (boot recusa sem ele) |
+| Host de bind | `127.0.0.1` | `127.0.0.1` |
+| 2FA / passkeys | disponíveis mas inúteis (login automático) | o propósito do modo |
+| Seguro em máquina compartilhada? | não (quem tem a máquina, entra) | sim (barreira de credencial) |
+| `ensureLocalOperator()` | chamado | lança exceção — "start-mode only" |
+
+A credencial previsível `operator/operator123` é provisionada **apenas** no modo `start`. `ensureLocalOperator()` (em `src/server/dev-auth.ts`) lança explicitamente uma exceção se `getRunMode() !== "start"`, então um modo de rede nunca carrega um login remoto padrão.
+
+---
+
+## 🌠 Passo a passo
+
+### 1. Lance no modo auth
+
+```bash
+npx constella --auth
+```
+
+`bin/constella.mjs` define `CONSTELLA_RUN_MODE=auth`, escolhe `host = 127.0.0.1` (apenas `vps`/`portable` usam `0.0.0.0`), e `port` por padrão é `3000` (sobrescreva com `--port`).
+
+### 2. Segredos são persistidos
+
+A cada launch, `bin/constella.mjs` garante que três segredos existam sob o runtime root e os grava (modo `0o600`) em `~/.constella/.env`:
+
+| Segredo | Propósito |
+|---|---|
+| `BETTER_AUTH_SECRET` | Assina cookies de sessão (obrigatório em `auth`). |
+| `CONSTELLA_VAULT_KEY` | Chave AES-256-GCM para o cofre de segredos de provedores. |
+| `CONSTELLA_WORKER_SECRET` | Segredo compartilhado que o worker apresenta ao web (`x-worker-secret`). |
+
+`ensureSecret()` reutiliza um valor persistido existente, prefere um override de ambiente e, caso contrário, gera um uma única vez. Persistir (não regerar) significa que suas sessões de login e o cofre criptografado sobrevivem a um restart.
+
+### 3. A barreira de boot dispara
+
+Na primeira requisição, `reconcileOnBoot()` (em `src/server/boot.ts`) chama `assertAuthSecret()` **antes de qualquer outra coisa**. No `auth` sem um segredo real, o processo registra `[boot] FATAL:` e chama `process.exit(1)` — o servidor nunca serve um cookie forjável.
+
+### 4. Faça login
+
+O browser acessa qualquer página `(app)` → `requireWorkspace()` não encontra sessão → redireciona para `/login`. O `LoginForm`:
+
+- Pré-preenche `operator@constella.dev`, mas aceita qualquer e-mail.
+- Chama `signIn.email({ email, password })`. Se o e-mail for desconhecido, recai em `signUp.email(...)` (criação no primeiro login).
+- O botão de submit fica desabilitado até a senha ter pelo menos 8 caracteres.
+
+### 5. Segundo fator opcional
+
+- **2FA por TOTP:** se habilitado, `signIn.email` retorna `twoFactorRedirect`; o formulário troca para um campo de código de 6 dígitos e chama `authClient.twoFactor.verifyTotp({ code })`.
+- **Passkey:** o botão de "passkey" faz POST para `/api/passkey/authenticate/options`, executa `startAuthentication(...)` no browser, e então faz POST da asserção para `/api/passkey/authenticate/verify`. Em caso de sucesso, o servidor emite um cookie de sessão real via `createSessionCookie()`.
+
+### 6. Gerenciar segundos fatores (Profile → Security)
+
+- **Habilitar 2FA:** `authClient.twoFactor.enable({ password })` → escaneie a URI TOTP → `verifyTotp({ code })`. Desabilite com `authClient.twoFactor.disable({ password })`.
+- **Passkeys:** registradas via rotas `/api/passkey/register/*`; gerenciadas (renomear / remover) por `removePasskey` / ações de renomear em `src/server/actions/profile-actions.ts`.
+
+---
+
+## 🕳️ Exemplos
+
+```bash
+# Launch padrão do modo auth na porta padrão
+npx constella --auth
+
+# Modo auth em uma porta customizada
+npx constella --auth --port 4000
+
+# Modo auth com o runtime root em outro lugar
+npx constella --auth --path /srv/constella-home
+
+# Forçar o assistente de onboarding de primeira execução, ainda sob a barreira auth
+npx constella --auth --onboarding
+```
+
+> O **seletor** de run mode na tela de login aparece apenas no modo desenvolvedor (`isDevMode()` em `src/lib/build-mode.ts`). Um launch público pelo CLI define `CONSTELLA_PUBLIC=1`, então o modo é fixado pela flag de launch e o seletor fica oculto.
+
+---
+
+## ✦ Estados possíveis
+
+| Estado | Causa | Sintoma |
+|---|---|---|
+| **Login obrigatório** | Modo `auth`, sem sessão | Browser redirecionado para `/login`. |
+| **Senha rejeitada** | Senha errada para uma conta existente | Mensagem `login.failed`; sem fallback para signup (e-mail existe). |
+| **Nova conta criada** | E-mail desconhecido + senha válida | `signUp.email` tem sucesso, redirect para `/`. |
+| **Desafio 2FA** | Conta com TOTP habilitado | Campo de código exibido; precisa de um TOTP de 6 dígitos. |
+| **Login por passkey** | Usuário clica no botão de passkey | Prompt WebAuthn do browser; sessão emitida no servidor. |
+| **Boot recusado** | Modo de rede, `BETTER_AUTH_SECRET` ausente | `[boot] FATAL` + `process.exit(1)`; servidor nunca inicia. |
+| **Login automático tentado** | `ensureLocalOperator` alcançado em `auth` | Lança `"ensureLocalOperator is start-mode only"` (defesa em profundidade). |
+
+---
+
+## 🛰️ Integrações relacionadas
+
+- **Isolamento de organização** — após o login, `requireWorkspace()` resolve a org ativa por meio de um join em `member`, então uma sessão nunca aponta para a org de outro tenant (`getActiveOrg` em `src/lib/workspace.ts`). Papéis são `owner` / `admin` / `member`.
+- **Cofre (Vault)** — segredos de provedores são criptografados com `CONSTELLA_VAULT_KEY`, persistidos junto de `BETTER_AUTH_SECRET` em `~/.constella/.env`. Veja [SECURITY](./SECURITY.md).
+- **Worker** — o worker 24/7 se autentica ao web com `x-worker-secret` (`CONSTELLA_WORKER_SECRET`) sobre loopback, independente do login humano. Veja [ARCHITECTURE](./ARCHITECTURE.md).
+- **API Pública / PAT** — acesso programático usa PATs `Bearer cn_<token>`, um caminho separado da sessão do browser. Veja [PUBLIC_API](./PUBLIC_API.md).
+
+---
+
+## 🕳️ Segurança
+
+- **Segredo de assinatura obrigatório.** `auth` (assim como `vps`/`portable`) **precisa** subir com um `BETTER_AUTH_SECRET` real. Sem ele, as sessões seriam assinadas com a chave padrão pública do better-auth (cookies forjáveis), porque o better-auth só lança exceção na chave padrão sob `NODE_ENV=production`. `assertAuthSecret()` fecha essa brecha encerrando o processo. `start` é isento por ser local-only com login automático.
+- **Bind no loopback.** `auth` faz bind em `127.0.0.1`; o listener não é alcançável pela rede. Se você colocar um reverse proxy https na frente, defina `BETTER_AUTH_URL` para a origem pública `https://` para que os cookies de sessão sejam marcados como `Secure`.
+- **Sem credencial remota padrão.** A conta `operator/operator123` é exclusiva do modo start e nunca é provisionada em `auth`.
+- **2FA / passkeys reais.** Segredos TOTP vivem na tabela `two_factor`; credenciais WebAuthn na tabela `passkey` (chave pública COSE, counter, transports). Desafios de passkey são guardados em cookies httpOnly de vida curta (`maxAge: 300`) entre os round-trips de options e verify (`src/lib/passkey.ts`).
+- **Sessões de 30 dias.** Sessões expiram após 30 dias; o caminho de exclusão de `account` faz cascade para sessões, contas, passkeys e tokens.
+- **Segurança entre tenants.** `activeOrgId` é tratado como controlável por atacante e sempre revalidado por meio de um join de membership.
+
+---
+
+## 🌌 Solução de problemas
+
+| Sintoma | Causa provável | Correção |
+|---|---|---|
+| Servidor encerra imediatamente com `[boot] FATAL: BETTER_AUTH_SECRET is required` | Modo de rede subiu sem segredo | Deixe o CLI persistir um (padrão), ou defina `BETTER_AUTH_SECRET` no ambiente / `~/.constella/.env`. |
+| Tela de login nunca aparece (já autenticado) | Você na verdade lançou `start`, não `auth` | Confira a linha de boot `Mode : auth · 127.0.0.1:3000`; relance com `--auth`. |
+| "ensureLocalOperator is start-mode only" nos logs | Caminho de login automático alcançado sob `auth` | Guard esperado — não há login automático em `auth`; faça login manualmente. |
+| Botão de passkey falha | Host de `BETTER_AUTH_URL` divergente (RP id) | Defina `BETTER_AUTH_URL` para a origem exata pela qual você navega; `rpID()` é o hostname dela. |
+| Cookies não `Secure` atrás de https | `BASE_URL` ainda é `http://localhost:3000` | Defina `BETTER_AUTH_URL` para a origem `https://` para que `useSecureCookies` ative. |
+| Esqueceu a senha do operador (migração start→auth) | A credencial padrão só existe em `start` | Em `auth`, crie/acesse uma conta real; não dependa de `operator123`. |
+| Não consegue alcançar o app de outra máquina | `auth` faz bind no loopback por design | Use [VPS_MODE](./VPS_MODE.md) para acesso remoto. |
+
+---
+
+## ✦ Links relacionados
+
+- [START_MODE](./START_MODE.md) — o modo local de login automático com que o `auth` contrasta.
+- [VPS_MODE](./VPS_MODE.md) — modo exposto à rede sobre uma tailnet, em Docker.
+- [PORTABLE_MODE](./PORTABLE_MODE.md) — o run mode de pen-drive USB.
+- [CONFIGURATION](./CONFIGURATION.md) — variáveis de ambiente, segredos e o runtime root.
+- [INSTALLATION](./INSTALLATION.md) — instalação e primeiro launch.
+- [SECURITY](./SECURITY.md) — cofre, scrubbing, jail de FS, modelo de sessão.
+- [ARCHITECTURE](./ARCHITECTURE.md) — processo duplo web + worker, reconcile de boot.
+- [PUBLIC_API](./PUBLIC_API.md) — acesso programático baseado em PAT.
+- [TROUBLESHOOTING](./TROUBLESHOOTING.md) — catálogo de falhas mais amplo.