constella 0.1.0

package/docs/pt/UPDATE.md

@@ -0,0 +1,301 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/UPDATE.md) · [✦ Constella](../../README.pt-BR.md)
+
+# 🚀 Atualização — relançando a nave central
+
+![](../assets/divider-orbit.svg)
+
+O Constella consulta o npm em busca de uma versão mais recente, mostra o changelog e aplica a atualização **da maneira que se encaixa em como este processo está rodando** — instalação global, npx, código-fonte (dev), VPS via Docker ou um pen drive portátil. Ele sempre faz backup do seu `.env` e do banco de dados antes, e nunca inventa um "sucesso" que não conquistou.
+
+---
+
+## ✦ Quando usar
+
+- Uma nova versão do Constella foi publicada e você quer baixá-la.
+- Você quer ler o changelog antes de atualizar (o painel "Novidades").
+- Você quer confirmar que já está na versão mais recente (`constella update --check`).
+- Você precisa do **comando exato** para o seu ambiente (dev / npx / VPS / portátil), porque alguns contextos não podem ser atualizados de dentro do servidor web em execução.
+
+---
+
+## 🌌 Como funciona
+
+Duas metades cooperam:
+
+| Metade | Arquivo | Responsabilidade |
+| --- | --- | --- |
+| **Verificação** | `src/server/update-check.ts` | Perguntar ao registro npm o `latest`, comparar versões, buscar o changelog. Cacheado, falha em silêncio. |
+| **Aplicação** | `src/server/update-run.ts` | Detectar o contexto de execução, fazer backup da config local e, então, executar automaticamente (global) ou devolver o comando exato. |
+| **Contexto** | `src/lib/run-context.ts` | `detectRunContext()` → `dev \| global \| npx \| vps \| portable`. |
+| **UI** | `src/components/modules/update-screen.tsx` | Versões, dica de contexto, "Atualizar agora", changelog, poll ao vivo do atualizador em segundo plano. |
+| **Actions** | `src/server/actions/update-actions.ts` | Server actions que a UI chama: `getUpdateStatus`, `getUpdateContext`, `runUpdate`, `pollUpdateResult`. |
+| **CLI** | `bin/constella.mjs` (subcomando `update`) | Verificação/aplicação autônoma que roda **fora** do servidor web. |
+
+A regra central (do comentário no código em `update-run.ts`): *somente a instalação npm `global` roda automaticamente* — todo outro contexto retorna o comando preciso para você executar, porque executá-los a partir do servidor web depende do ambiente.
+
+---
+
+## 🛰️ Fluxo principal
+
+```mermaid
+flowchart TD
+  A["Abrir /update ou rodar `constella update`"] --> B["checkForUpdate()"]
+  B --> C{"registro npm acessível?"}
+  C -- "não" --> D["latest = null · sem atualização · falha em silêncio"]
+  C -- "sim" --> E["comparar latest vs current (isNewer)"]
+  E -- "não é mais novo" --> F["Já está atualizado"]
+  E -- "mais novo" --> G["buscar CHANGELOG · sliceChangelog(latest)"]
+  G --> H["startUpdate() → detectRunContext()"]
+  H --> I["backupBeforeUpdate() — copiar .env + db"]
+  I --> J{"contexto?"}
+  J -- "global" --> K["spawn destacado npm i -g · gravar last-update.json"]
+  J -- "dev / npx / vps / portable" --> L["retornar comando exato (sem execução automática)"]
+  K --> M["UI consulta getUpdateResult() a cada 3s"]
+  M --> N["running → done / error · pedir reinício"]
+```
+
+---
+
+## 🪐 Conceitos-chave
+
+### Verificação de versão (`checkForUpdate`)
+
+- Lê a versão **instalada** via `currentVersion()` (`src/lib/version.ts`): env `CONSTELLA_VERSION` (definida pela CLI) → `package.json` do diretório de lançamento → `"0.0.0"`.
+- Busca `https://registry.npmjs.org/constella/latest` pela `version` publicada.
+- `isNewer(latest, current)` faz uma comparação semver numérica de 3 partes (sufixos de pré-lançamento removidos). `bumpType` classifica o salto como `major | minor | patch`.
+- Retorna um `UpdateInfo`: `{ current, latest, updateAvailable, type, command, changelog }`. O `command` padrão é `npm install -g constella@latest`.
+- **Cache em memória de 6 horas** (`TTL = 6 * 60 * 60 * 1000`) para que o polling do cliente nunca martele o registro. `checkForUpdate(true)` força uma atualização.
+- **Falha fechada/silenciosa**: qualquer caminho offline / não publicado / timeout (`AbortController` de 3 s) resulta em `latest: null`, `updateAvailable: false`. Nunca lança erro e nunca inventa "atualizado".
+
+### Busca do changelog
+
+- Buscado apenas quando `updateAvailable` é verdadeiro.
+- Puxa `https://raw.githubusercontent.com/gabriel7silva/constella/main/CHANGELOG.md`.
+- `sliceChangelog(md, version)` extrai a seção `## [x.y.z] …` até o próximo cabeçalho `##`; se o cabeçalho da versão exata não for encontrado, recai para a primeira seção do arquivo.
+- Renderizado no card "Novidades na v{version}" da UI via `react-markdown` + `remark-gfm`.
+
+### Detecção do contexto de execução (`detectRunContext`)
+
+A ordem importa — o primeiro match vence:
+
+| Ordem | Teste | Contexto |
+| --- | --- | --- |
+| 1 | `isDevMode()` (rodando do código-fonte) | `dev` |
+| 2 | `getRunMode() === "vps"` **ou** `/.dockerenv` existe | `vps` |
+| 3 | `getRunMode() === "portable"` | `portable` |
+| 4 | caminho de `launchDir()` contém `/_npx/` (cache do npx) | `npx` |
+| 5 | (fallback) | `global` |
+
+`isDevMode()` (`src/lib/build-mode.ts`): `CONSTELLA_PUBLIC=1` → `false`; senão `CONSTELLA_DEV=1` → `true`; senão `NODE_ENV !== "production"`. Um lançamento via CLI define `CONSTELLA_PUBLIC=1`, então execuções instaladas nunca são confundidas com dev.
+
+### Backup antes da atualização (`backupBeforeUpdate`)
+
+- Esforço-melhor (best-effort), roda antes de qualquer atualização em `startUpdate()`.
+- Cria `<HOME>/backups/<timestamp>/` (timestamp = ISO com `:`/`.` substituídos por `-`).
+- Copia, se presentes: `.env`, `constella.db`, `constella.db-wal`, `constella.db-shm`.
+- Retorna o caminho do diretório de backup (exibido na UI como "Backup salvo: …"). Qualquer falha de cópia é ignorada em silêncio — o backup nunca bloqueia a atualização.
+- `<HOME>` resolve via `constellaHome()`: `CONSTELLA_HOME` (resolvido contra o diretório de lançamento) ou `~/.constella`.
+
+### Aplicação ciente de contexto (`startUpdate`)
+
+| Contexto | `ok` | Roda automático? | Comando retornado | `needsRestart` |
+| --- | --- | --- | --- | --- |
+| `global` | `true` | ✅ `npm install -g constella@latest` destacado | `npm install -g constella@latest` | ✅ |
+| `dev` | `false` | ❌ | `git pull && pnpm install && pnpm build` | — |
+| `npx` | `false` | ❌ | `npx constella@latest` | — |
+| `vps` | `false` | ❌ | `docker compose pull && docker compose up -d` | ✅ |
+| `portable` | `false` | ❌ | `npm install -g constella@latest` (após verificação de espaço/backup) | ✅ |
+
+> Se `updateAvailable` for falso, `startUpdate()` faz curto-circuito com `ok: true, message: "Already up to date."` — sem backup, sem comando.
+
+### O atualizador global destacado + polling de resultado
+
+Como uma atualização npm global não consegue terminar de forma confiável antes de o servidor web ser substituído, `startUpdate()` para `global`:
+
+1. Grava `<HOME>/backups/last-update.json` com `{ status: "running", to, at }`.
+2. Faz spawn de um one-liner `node -e` **destacado** (sem arquivo de script separado — funciona mesmo a partir de uma instalação global) que roda `npm install -g constella@latest` e reescreve o arquivo de resultado com `status: "done" | "error"`, o `code` de saída do npm e `at`.
+3. Faz `child.unref()` para que o atualizador sobreviva à requisição.
+4. Retorna `{ ok: true, started: true, needsRestart: true, … }`.
+
+A UI (`update-screen.tsx`) então consulta `pollUpdateResult()` → `getUpdateResult()` a cada **3 segundos**, lendo `last-update.json`. Status: `idle` (sem arquivo), `running`, `done`, `error`. Em `done`/`error` ela para de consultar e pede um reinício (ou mostra a dica de rollback).
+
+---
+
+## 🌠 Tabelas
+
+### `UpdateInfo` (retornado por `checkForUpdate`)
+
+| Campo | Tipo | Significado |
+| --- | --- | --- |
+| `current` | `string` | Versão instalada. |
+| `latest` | `string \| null` | `latest` do npm, ou `null` quando o registro está inacessível. |
+| `updateAvailable` | `boolean` | `latest` existe e é mais novo. |
+| `type` | `"major" \| "minor" \| "patch" \| null` | Tamanho do salto de versão. |
+| `command` | `string` | Comando de atualização padrão. |
+| `changelog` | `string \| null` | Seção do changelog fatiada para `latest`. |
+
+### `UpdateResult` (retornado por `startUpdate` / `runUpdate`)
+
+| Campo | Tipo | Significado |
+| --- | --- | --- |
+| `ok` | `boolean` | Operação bem-sucedida (global iniciada, ou já atual). |
+| `started` | `boolean?` | O atualizador global destacado foi lançado → UI deve consultar. |
+| `context` | `string` | Contexto de execução detectado. |
+| `command` | `string` | O comando para este contexto. |
+| `message` | `string` | Status / instrução legível por humanos. |
+| `backupDir` | `string?` | Onde `.env`/db foram copiados. |
+| `needsRestart` | `boolean?` | Reiniciar o Constella para carregar a nova versão. |
+
+### `last-update.json` (estado do atualizador em segundo plano)
+
+| Campo | Tipo | Significado |
+| --- | --- | --- |
+| `status` | `"idle" \| "running" \| "done" \| "error"` | Estado do atualizador (`idle` = arquivo ausente). |
+| `to` | `string` | Versão-alvo. |
+| `code` | `number` | Código de saída do npm (na conclusão). |
+| `at` | `string` | Timestamp ISO. |
+
+---
+
+## 🕳️ Fluxo de atualização por contexto
+
+```mermaid
+flowchart LR
+  X["detectRunContext()"] --> G["global"]
+  X --> D["dev"]
+  X --> N["npx"]
+  X --> V["vps"]
+  X --> P["portable"]
+
+  G --> G1["npm i -g constella@latest destacado"] --> G2["consultar last-update.json → reiniciar"]
+  D --> D1["git pull && pnpm install && pnpm build"]
+  N --> N1["npx constella@latest"]
+  V --> V1["docker compose pull && docker compose up -d"]
+  P --> P1["verificar espaço livre + backup do drive, depois npm i -g constella@latest"]
+```
+
+---
+
+## ✦ Passo a passo
+
+### No aplicativo
+
+1. Abra o módulo **Atualizar** (`/update`). A página chama `getUpdateStatus()` e `getUpdateContext()`.
+2. Leia as versões **Instalada → Mais recente** e a pílula de salto (`major`/`minor`/`patch`).
+3. A linha de contexto informa como este processo roda (ex.: "Instalação npm global — pode atualizar no lugar.").
+4. Se houver uma atualização disponível, revise **"Novidades na v…"**.
+5. Clique em **Atualizar agora** → `runUpdate()` (protegido por auth via `requireWorkspace()`).
+   - **global** → o atualizador em segundo plano inicia; acompanhe o poll ao vivo (`running → instalada`), depois reinicie o Constella.
+   - **dev / npx / vps / portable** → copie o comando exato exibido e rode no seu terminal.
+6. A linha **Backup salvo** mostra onde seu `.env`/db foram copiados.
+
+### Pela CLI
+
+```bash
+# Apenas verificar (sem aplicar) — imprime "Constella x.y.z · latest a.b.c"
+constella update --check
+
+# Verificar + aplicar (caminho de instalação global)
+constella update
+```
+
+O subcomando `update` da CLI (`bin/constella.mjs`):
+- Lê a versão local do próprio `package.json` do pacote, busca `latest` no npm (timeout de 4 s).
+- `--check` → imprime e sai.
+- Se o registro estiver inacessível, ou `latest === current`, ele informa e sai com 0.
+- Se detectar **código-fonte** (`.git` + `src/` no CWD), ele orienta a `git pull && pnpm install && pnpm build` e sai.
+- Caso contrário, roda `npm install -g constella@latest` (usa `npm.cmd` no Windows, sem shell) com stdio herdado, e então pede para reiniciar.
+
+---
+
+## 🛰️ Exemplos
+
+**Já atual (à prova de offline):**
+```text
+Constella 0.1.0 · (npm registry unavailable)
+Couldn't reach the npm registry — try again later.
+```
+
+**Atualização global pela UI** — `runUpdate()` retorna:
+```json
+{
+  "ok": true,
+  "started": true,
+  "needsRestart": true,
+  "context": "global",
+  "command": "npm install -g constella@latest",
+  "backupDir": "/home/voce/.constella/backups/2026-06-22T10-15-03-000Z",
+  "message": "Updating to 0.2.0 in the background — restart Constella when it completes."
+}
+```
+…e o poll lê `<HOME>/backups/last-update.json`:
+```json
+{ "status": "done", "to": "0.2.0", "code": 0, "at": "2026-06-22T10:15:41.220Z" }
+```
+
+**VPS** — sem execução automática; você recebe:
+```json
+{ "ok": false, "context": "vps", "command": "docker compose pull && docker compose up -d", "needsRestart": true,
+  "message": "On a VPS, update with Docker: docker compose pull && docker compose up -d" }
+```
+
+---
+
+## 🌌 Estados possíveis
+
+| Estado | Como aparece | Origem |
+| --- | --- | --- |
+| Atualizado | "Você está na versão mais recente." | `updateAvailable === false` |
+| Atualização disponível | Pílula de versão + "Atualizar agora" | `updateAvailable === true` |
+| Registro inacessível | `latest = —`, sem botão | `latest === null` |
+| Atualizando (global) | "Atualizando…" + spinner | `started === true`, `busy` |
+| Poll: running | "Atualizador: executando…" | `last-update.json.status === "running"` |
+| Poll: done | "✓ instalada — reinicie o Constella para carregá-la." | `status === "done"` |
+| Poll: error | "✖ falhou — veja o rollback abaixo." + dica de rollback | `status === "error"` |
+| Comando manual | Comando exibido em um `<pre>`; sem execução automática | `dev / npx / vps / portable` |
+
+---
+
+## 🪐 Integrações relacionadas
+
+- **[VPS_MODE](./VPS_MODE.md)** — o caminho Docker `docker compose pull && up -d`.
+- **[PORTABLE_MODE](./PORTABLE_MODE.md)** — pen drive, verificações de espaço livre antes de atualizar.
+- **[INSTALLATION](./INSTALLATION.md)** / **[PUBLISHING](./PUBLISHING.md)** — como as versões chegam ao npm.
+- **[START_MODE](./START_MODE.md)** / **[AUTH_MODE](./AUTH_MODE.md)** — modos de execução que alimentam `detectRunContext()`.
+- **[CONFIGURATION](./CONFIGURATION.md)** — variáveis de ambiente (`CONSTELLA_HOME`, `CONSTELLA_VERSION`, `CONSTELLA_PUBLIC`).
+
+---
+
+## 🕳️ Segurança
+
+- **Aplicação protegida por auth.** `runUpdate()` chama `requireWorkspace()` antes de fazer qualquer coisa.
+- **Backup primeiro, sempre.** `.env` + o banco SQLite (e WAL/SHM) são copiados para `<HOME>/backups/<timestamp>/` antes de qualquer caminho de atualização.
+- **Sem injeção de shell na CLI.** A instalação global faz spawn de `npm`/`npm.cmd` diretamente com um array argv — sem interpolação de string em shell.
+- **Verificações fail-closed.** As buscas de registro/changelog usam um timeout `AbortController` de 3–4 s e engolem erros, então uma rede hostil ou morta não pode travar nem derrubar a tela de atualização — apenas reporta "sem atualização".
+- **Resultados honestos.** O atualizador destacado grava um código de saída real do npm em `last-update.json`; a UI reflete `done`/`error` com fidelidade e nunca afirma sucesso em caso de falha.
+
+---
+
+## 🌠 Solução de problemas
+
+| Sintoma | Causa provável | Solução |
+| --- | --- | --- |
+| "registry unavailable" | Offline / npm fora do ar / firewall | Tente mais tarde; verifique a conectividade com `registry.npmjs.org`. |
+| Mais recente exibido mas desatualizado | Cache de 6 h | Force uma verificação nova: `checkForUpdate(true)` (re-fetch da UI) ou `constella update --check`. |
+| Contexto detectado errado | Env inconsistente | Verifique `CONSTELLA_PUBLIC`/`CONSTELLA_DEV`, `CONSTELLA_RUN_MODE` e a presença de `/.dockerenv`. |
+| Poll global travado em "running" | `npm` destacado ainda instalando ou bloqueado | Aguarde; se nunca resolver, rode `npm install -g constella@latest` manualmente. |
+| Poll: error | npm saiu com código não-zero (permissões?) | Reexecute com permissões elevadas; rollback: `npm i -g constella@<atual>`, depois restaure o backup. |
+| Versão ainda antiga após reiniciar | Processo antigo ainda rodando | Pare totalmente e relance o Constella para que `CONSTELLA_VERSION` seja relido. |
+| Instalação dev não atualiza sozinha | Intencional | Rode `git pull && pnpm install && pnpm build` (ou `next build`). |
+
+---
+
+## ✦ Links relacionados
+
+- [INSTALLATION](./INSTALLATION.md)
+- [CONFIGURATION](./CONFIGURATION.md)
+- [VPS_MODE](./VPS_MODE.md)
+- [PORTABLE_MODE](./PORTABLE_MODE.md)
+- [START_MODE](./START_MODE.md)
+- [PUBLISHING](./PUBLISHING.md)
+- [ARCHITECTURE](./ARCHITECTURE.md)
+- [TROUBLESHOOTING](./TROUBLESHOOTING.md)

package/docs/pt/VPS_MODE.md

@@ -0,0 +1,334 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/VPS_MODE.md) · [✦ Constella](../../README.pt-BR.md)
+
+# Modo VPS 🛰️
+
+![](../assets/divider-orbit.svg)
+
+Rode a nave-mãe em um servidor remoto. O **modo VPS** inicia o Constella dentro do Docker em uma VPS, vincula o servidor web a `0.0.0.0` e o expõe **apenas** pela sua tailnet do Tailscale — uma órbita privada acessível de qualquer dispositivo que você autorizar, e de nenhum outro lugar.
+
+---
+
+## Quando usar 🌌
+
+Escolha o modo VPS quando quiser um **plano de controle 24/7** que continue planejando, construindo, revisando e enviando enquanto seu notebook está fechado — sem colocar o painel na internet aberta.
+
+| Você quer… | O modo VPS entrega |
+| --- | --- |
+| A constelação de agentes sempre ativa | Um processo de servidor de longa duração (web + worker), supervisionado e reiniciado automaticamente |
+| Acesso remoto privado | Vinculado a `0.0.0.0`, mas acessível **apenas na sua tailnet do Tailscale** |
+| Autenticação real | E-mail + senha exigidos a cada sessão (`requiresLogin: true`) |
+| Uma instalação reproduzível | Um `Dockerfile` + `docker-compose.yml` + um bootstrap `vps-install.sh` de um passo |
+| Execução endurecida por padrão | Jaula do contêiner + CLI do agente em modo `acceptEdits` (apenas edições) |
+
+Se você só quer uma instância local sempre ativa na sua própria máquina, use [START_MODE](./START_MODE.md) ou [AUTH_MODE](./AUTH_MODE.md). Para uma instância que você carrega num drive, veja [PORTABLE_MODE](./PORTABLE_MODE.md).
+
+---
+
+## Como funciona 🪐
+
+VPS é um dos quatro **modos de execução** declarados em `src/lib/run-mode.ts`:
+
+```ts
+export type RunMode = "start" | "auth" | "vps" | "portable";
+
+export const RUN_MODES = {
+  // …
+  vps: { label: "VPS", requiresLogin: true,
+         note: "Access over your Tailscale tailnet; runs in Docker." },
+};
+```
+
+O modo é escolhido **no lançamento**, nunca na UI (um lançamento via CLI define `CONSTELLA_PUBLIC=1`, o que esconde o seletor de modo no app). Ele é resolvido em `bin/constella.mjs` a partir da flag `--vps` (com o legado `--bind tailnet` mapeando para o mesmo modo), depois exportado como `CONSTELLA_RUN_MODE=vps` e persistido na linha da organização (`organization.run_mode`) no onboarding via `getRunMode()`.
+
+Três coisas tornam o VPS distinto dos outros modos:
+
+1. **Endereço de bind `0.0.0.0`.** Em `bin/constella.mjs`, `host = --host || (vps|portable ? "0.0.0.0" : "127.0.0.1")`. O servidor escuta em todas as interfaces para que a camada do Tailscale consiga alcançá-lo.
+2. **Login é obrigatório.** `requiresLogin()` retorna `true`, e `src/proxy.ts` redireciona toda requisição não autenticada para `/login` (apenas o modo `start` pula isso).
+3. **Contexto de execução = `vps`.** `detectRunContext()` em `src/lib/run-context.ts` retorna `"vps"` quando `getRunMode() === "vps"` **ou** quando `/.dockerenv` existe — assim o fluxo de Update no app sabe usar `docker compose` em vez de `npm`/`git`. Veja [UPDATE](./UPDATE.md).
+
+> 🛰️ **O Tailscale é assumido como configurado externamente.** O Constella não gerencia sua tailnet, ACLs ou auth keys. O script de bootstrap e o arquivo compose *entram* numa tailnet para você, mas a tailnet em si (dispositivos, MagicDNS, ACLs) é sua para administrar em <https://login.tailscale.com>. O Constella apenas vincula `0.0.0.0`; é a tailnet que mantém esse bind privado.
+
+---
+
+## Fluxo principal 🌠
+
+```mermaid
+flowchart TD
+  A["operador: bash scripts/vps-install.sh"] --> B["instala Docker"]
+  B --> C["instala Tailscale + tailscale up"]
+  C --> D["TS_AUTHKEY gravado em .env"]
+  D --> E["docker compose up -d --build"]
+  E --> F["sidecar tailscale entra na tailnet"]
+  E --> G["contêiner constella compila + inicia"]
+  G --> H["bin/constella.mjs --vps --host 0.0.0.0 --port 3000"]
+  H --> I["gera/persiste segredos em /data/.env (chmod 600)"]
+  H --> J["drizzle migrate contra /data/constella.db"]
+  H --> K["supervisiona: next start + worker"]
+  F & K --> L["acessível em http://<tailscale-ip>:3000"]
+```
+
+---
+
+## Conceitos-chave ✦
+
+### Os dois contêineres
+
+O `docker-compose.yml` roda **dois serviços que compartilham um único namespace de rede**:
+
+- **`tailscale`** — a imagem oficial `tailscale/tailscale`, atuando como sidecar. Ela controla `/dev/net/tun`, possui as capabilities `net_admin` + `sys_module`, entra na tailnet de forma headless com `TS_AUTHKEY` e persiste o estado do nó no volume `tailscale-state`.
+- **`constella`** — construída a partir do `Dockerfile`, ligada à rede do sidecar com `network_mode: service:tailscale`. Como compartilham o namespace, o Constella fica acessível **apenas no IP do Tailscale** na porta 3000 — nunca nas interfaces públicas do host.
+
+### Raiz de runtime em um volume
+
+Dentro do contêiner, `CONSTELLA_HOME=/data` (um volume Docker nomeado, `constella-data`). Todo o estado de runtime vive ali:
+
+- `/data/constella.db` — o banco SQLite (`DATABASE_URL=file:/data/constella.db`).
+- `/data/.env` — segredos gerados (`chmod 600`), sobrevivem a reinícios porque o volume é estável.
+- `/data/organizations/<orgId>/workspace/` — a árvore do workspace dos agentes (a jaula de FS). Veja [ARCHITECTURE](./ARCHITECTURE.md).
+
+### Worker pelo loopback (mesmo em `0.0.0.0`)
+
+O modelo de processo duplo (web + worker) é preservado no modo VPS. O launcher dispara `bin/worker.mjs` com `CONSTELLA_BASE_URL=http://127.0.0.1:<port>` — **loopback**, mesmo que o servidor web vincule `0.0.0.0`. Isso é uma **proteção deliberada contra SSRF / exfiltração de segredo**: o worker anexa o cabeçalho privilegiado `x-worker-secret` a cada chamada, então recusa qualquer base URL não-loopback:
+
+```js
+const isLoopback = ["localhost", "127.0.0.1", "::1", "[::1]"].includes(baseHost);
+if (!isLoopback && !ALLOW_REMOTE) {
+  console.error(`✖ Refusing to send the worker secret to a non-loopback host (${baseHost}). …`);
+  process.exit(1);
+}
+```
+
+Um worker genuinamente remoto precisa optar explicitamente com `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1` (e é avisado se a URL for `http://` puro). Veja [ARCHITECTURE](./ARCHITECTURE.md).
+
+### Segredos são obrigatórios
+
+O `bin/constella.mjs` gera e persiste **três** segredos em `/data/.env` no primeiro boot (e os reutiliza depois):
+
+- `BETTER_AUTH_SECRET` — `next start` roda sob `NODE_ENV=production`, onde o better-auth **lança erro** com sua chave padrão; um modo de rede precisa de uma real.
+- `CONSTELLA_VAULT_KEY` — chave AES-256-GCM para o cofre de credenciais/provedores. Veja [SECURITY](./SECURITY.md).
+- `CONSTELLA_WORKER_SECRET` — o worker falha **fechado** sem ele (`x-worker-secret`).
+
+O launcher imprime apenas `• Secrets ready (stored in <HOME>/.env, never printed).` — os valores nunca são logados.
+
+---
+
+## Tabelas 🗃️
+
+### Comparação dos modos de execução
+
+| Propriedade | `start` | `auth` | `vps` | `portable` |
+| --- | --- | --- | --- | --- |
+| `requiresLogin` | `false` | `true` | `true` | `true` |
+| Host de bind padrão | `127.0.0.1` | `127.0.0.1` | **`0.0.0.0`** | `0.0.0.0` |
+| Exposição de rede | localhost | localhost | **tailnet do Tailscale** | LAN (host USB) |
+| Runtime típico | local | local | **Docker** | drive USB |
+| Permissão do CLI do agente | `bypassPermissions` (total) | `acceptEdits` (jaulado) | **`acceptEdits` (jaulado)** | `acceptEdits` (jaulado) |
+| `detectRunContext()` | `dev`/`global`/`npx` | `dev`/`global`/`npx` | **`vps`** | `portable` |
+
+### Variáveis de ambiente do VPS
+
+| Variável | Definida por | Valor | Propósito |
+| --- | --- | --- | --- |
+| `CONSTELLA_RUN_MODE` | launcher / Dockerfile / compose | `vps` | Seleciona o comportamento VPS, login obrigatório |
+| `CONSTELLA_PUBLIC` | launcher / Dockerfile / compose | `1` | Marca um runtime público; esconde o seletor de modo da UI |
+| `CONSTELLA_HOME` | Dockerfile / compose | `/data` | Raiz de runtime (um volume Docker) |
+| `DATABASE_URL` | launcher | `file:/data/constella.db` | Caminho do SQLite sob o volume |
+| `BETTER_AUTH_SECRET` | launcher (gerado) | base64url aleatório | Chave de assinatura de sessão |
+| `CONSTELLA_VAULT_KEY` | launcher (gerado) | base64 aleatório | Chave de criptografia do cofre |
+| `CONSTELLA_WORKER_SECRET` | launcher (gerado) | base64url aleatório | `x-worker-secret` do worker |
+| `CONSTELLA_BASE_URL` | launcher (processo worker) | `http://127.0.0.1:3000` | Apenas loopback |
+| `NODE_ENV` | Dockerfile | `production` | Boot de produção |
+| `TS_AUTHKEY` | `.env` / compose | `tskey-auth-…` | Chave de entrada do sidecar Tailscale |
+| `CONSTELLA_AGENT_FULL_ACCESS` | operador (opcional) | `1` / `0` | Sobrescreve exec jaulado/total do agente |
+| `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL` | operador (opcional) | `1` | Permite um worker não-loopback |
+| `CONSTELLA_WEB_HEAP_MB` | operador (opcional) | inteiro | Aumenta o limite de heap V8 do web |
+
+### Serviços do docker compose
+
+| Serviço | Imagem / build | Rede | Volumes | Capabilities notáveis |
+| --- | --- | --- | --- | --- |
+| `tailscale` | `tailscale/tailscale:latest` | namespace próprio | `tailscale-state:/var/lib/tailscale` | `net_admin`, `sys_module`, `/dev/net/tun` |
+| `constella` | `build: .` (Dockerfile) | `service:tailscale` | `constella-data:/data` | roda como `node` sem privilégios (uid 1000) |
+
+---
+
+## Diagrama de topologia 🌌
+
+```mermaid
+flowchart LR
+  subgraph TN["Sua tailnet do Tailscale (órbita privada)"]
+    direction LR
+    L["Notebook"]
+    P["Celular"]
+    subgraph VPS["Host VPS"]
+      subgraph NS["namespace de rede compartilhado"]
+        TS["sidecar tailscale\n(net_admin, /dev/net/tun)"]
+        C["contêiner constella\n0.0.0.0:3000\nuid 1000 'node'"]
+      end
+      V1[("volume /data\nconstella.db + .env")]
+      V2[("volume\ntailscale-state")]
+    end
+  end
+  NET(["internet pública"]) -. bloqueado .-> VPS
+  L -->|"tailnet https"| TS
+  P -->|"tailnet https"| TS
+  TS --> C
+  C --- V1
+  TS --- V2
+
+  subgraph IN["dentro do contêiner constella"]
+    W["next start (web)\n0.0.0.0:3000"]
+    K["worker.mjs\n→ 127.0.0.1:3000\nx-worker-secret"]
+    K -->|apenas loopback| W
+  end
+```
+
+---
+
+## Passo a passo 🚀
+
+### 1. Provisione uma VPS
+
+Um Ubuntu Server novo é o alvo assumido (o bootstrap instala o Docker via `get.docker.com` e o Tailscale via `tailscale.com/install.sh`).
+
+### 2. Rode o bootstrap
+
+```bash
+bash scripts/vps-install.sh
+```
+
+O `scripts/vps-install.sh` faz, em ordem:
+
+1. **Instala o Docker** se `docker` não estiver no `PATH` (`curl -fsSL https://get.docker.com | sh`).
+2. **Instala o Tailscale** se ausente (`curl -fsSL https://tailscale.com/install.sh | sh`).
+3. **Entra na tailnet** com `sudo tailscale up` (imprime uma URL de auth no navegador se necessário).
+4. **Pede um `TS_AUTHKEY`** (para que o sidecar do *contêiner* entre de forma headless) e o anexa ao `.env`.
+5. **Constrói + inicia** a stack: `sudo docker compose up -d --build`.
+6. **Imprime a URL de acesso**: `http://<tailscale-ip>:3000`.
+
+### 3. Crie a auth key do Tailscale
+
+Quando solicitado, crie uma chave em <https://login.tailscale.com/admin/settings/keys> e cole o valor `tskey-auth-…`. Ele é gravado no `.env` como `TS_AUTHKEY=…`, que o arquivo compose passa ao sidecar `tailscale`.
+
+### 4. Acesse o painel
+
+De **qualquer dispositivo na mesma tailnet**, abra:
+
+```
+http://<ip-tailscale-deste-nó>:3000
+```
+
+Encontre o IP com `tailscale ip -4` na VPS. O primeiro carregamento cai em `/login` (login é obrigatório); após entrar, complete o [ONBOARDING](./ONBOARDING.md) se for o primeiro boot.
+
+### 5. Caminho manual com compose (sem o bootstrap)
+
+```bash
+echo "TS_AUTHKEY=tskey-auth-..." > .env
+docker compose up -d --build
+# depois: http://<tailscale-ip>:3000
+```
+
+---
+
+## Exemplos 🪐
+
+**Iniciar o modo VPS diretamente (sem Docker), vinculando todas as interfaces:**
+
+```bash
+node bin/constella.mjs --vps --host 0.0.0.0 --port 3000
+```
+
+**O comando exato do contêiner (do `Dockerfile`):**
+
+```dockerfile
+CMD ["node", "bin/constella.mjs", "--vps", "--host", "0.0.0.0", "--port", "3000"]
+```
+
+**Confirmar o contexto de execução que o app enxerga:**
+
+```bash
+# dentro do contêiner — /.dockerenv existe, então detectRunContext() → "vps"
+ls /.dockerenv && echo "context: vps"
+```
+
+**Permitir exec de shell total aos agentes na VPS (sobrescrever a jaula — use com cuidado):**
+
+```bash
+# defina no bloco `environment:` do compose para o serviço constella
+CONSTELLA_AGENT_FULL_ACCESS=1
+```
+
+---
+
+## Estados possíveis ✦
+
+| Estado | O que você vê | Significado |
+| --- | --- | --- |
+| Iniciando | `Mode : vps · 0.0.0.0:3000` nos logs | Launcher resolveu VPS, vinculando todas as interfaces |
+| Segredos prontos | `• Secrets ready (stored in /data/.env, never printed).` | Três segredos gerados/reutilizados |
+| Migrando | saída do drizzle migrate | Schema aplicado a `/data/constella.db` |
+| Web no ar | `next start` escutando em `0.0.0.0:3000` | Painel acessível na tailnet |
+| Worker no ar | `Constella worker → tick … every 60000ms` | Tick 24/7 + watcher + poll do Telegram rodando |
+| Worker recusado | `✖ Refusing to send the worker secret to a non-loopback host` | `CONSTELLA_BASE_URL` não é loopback e sem override |
+| Crash de filho | `• [web] exited (…) — auto-restarting in 2s` | Supervisor reiniciando (máx 5 / 60s) |
+| Crash-loop | `✖ [web] … crashed 5x … giving up.` | Falha repetida; supervisor desiste |
+| Barreira de login | redirecionado para `/login` | `requiresLogin` imposto por `src/proxy.ts` |
+
+---
+
+## Integrações relacionadas 🛰️
+
+- **Worker / cron** — o worker ainda dirige o tick de 60s (`POST /api/cron/tick`), o watcher do chokidar (`/api/sync/file`) e o long-poll do Telegram, tudo pelo loopback. Veja [ARCHITECTURE](./ARCHITECTURE.md).
+- **Telegram** — controle remoto da empresa pelo celular enquanto a VPS roda headless. Veja [TELEGRAM](./TELEGRAM.md).
+- **API Pública / MCP** — um host de IA remoto pode dirigir a VPS pela tailnet via a API REST v1 ou o servidor MCP. Veja [PUBLIC_API](./PUBLIC_API.md) e [MCP](./MCP.md).
+- **Update** — no contexto `vps`, o Update no app roda `docker compose pull && up -d`. Veja [UPDATE](./UPDATE.md).
+- **Execução de agentes** — modo jaulado `acceptEdits` sobre a jaula do contêiner. Veja [AGENTS](./AGENTS.md) e [AI_ARCHITECTURE](./AI_ARCHITECTURE.md).
+
+---
+
+## Segurança 🕳️
+
+| Camada | Mecanismo |
+| --- | --- |
+| Privacidade de rede | O app vincula `0.0.0.0`, mas só o sidecar Tailscale o alcança (`network_mode: service:tailscale`) — nunca a internet pública |
+| Autenticação | Login obrigatório a cada sessão (`requiresLogin: true`, `src/proxy.ts` → `/login`); better-auth e-mail+senha, 2FA/passkeys opcionais |
+| Endurecimento do contêiner | Roda como `node` sem privilégios (uid 1000), não root, então um RCE no nível do app não age como root sobre `/data` |
+| Assinatura de segredo | `BETTER_AUTH_SECRET` real gerado (sem chave padrão em produção) |
+| Cofre | Segredos de provedor/credenciais criptografados com `CONSTELLA_VAULT_KEY` (AES-256-GCM) |
+| Isolamento do worker | O worker fala **apenas loopback**; recusa não-loopback salvo `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1` |
+| Permissões do `.env` | `/data/.env` gravado `chmod 600` |
+| Jaula do agente | O CLI roda `acceptEdits` (apenas edições, sem exec arbitrário) + jaula de FS; o contêiner é a jaula externa rígida |
+
+> 🕳️ **O bind sozinho não é a fronteira.** Vincular `0.0.0.0` é seguro *apenas porque* o contêiner compartilha o namespace do sidecar Tailscale e o host não publica a porta 3000 na internet pública. Se você remover o sidecar e expor a 3000 diretamente, perde a órbita privada — coloque-a atrás da tailnet ou de uma VPN/proxy reverso com autenticação.
+
+> ⚠️ **Os CLIs dos agentes não são incluídos.** O `Dockerfile` observa que os CLIs `claude` / `codex` **não** estão na imagem. Para agentes numa VPS, ou adicione um passo `RUN` para instalar um CLI, ou configure provedores de API na nuvem no módulo [MODELS](./MODELS.md).
+
+---
+
+## Solução de problemas 🌠
+
+| Sintoma | Causa provável | Correção |
+| --- | --- | --- |
+| Não acessa `http://<ip>:3000` | Fora da tailnet, ou IP errado | Confirme `tailscale status`; pegue o IP com `tailscale ip -4` na VPS |
+| Sidecar não entra | `TS_AUTHKEY` ausente/expirado | Recrie a chave, atualize o `.env`, `docker compose up -d` |
+| Redirecionado para `/login` e não avança | Primeiro boot, sem conta ainda | Cadastre-se / complete o [ONBOARDING](./ONBOARDING.md); login é obrigatório no VPS |
+| `✖ Refusing to send the worker secret to a non-loopback host` | `CONSTELLA_BASE_URL` não é loopback | Deixe-a sem definir (padrão loopback) ou defina `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1` deliberadamente |
+| `better-auth` lança erro no boot | `BETTER_AUTH_SECRET` ausente | Garanta que o volume `/data` seja gravável para o launcher persistir o `.env` |
+| Agentes não fazem nada | Sem CLI na imagem / sem provedor | Instale um CLI na imagem ou configure um provedor de nuvem ([MODELS](./MODELS.md)) |
+| Web reinicia sem parar | OOM no nível do SO (RAM dos agentes) ou crash nativo | Limite agentes concorrentes, ou aumente `CONSTELLA_WEB_HEAP_MB` para um OOM de heap JS |
+| `✖ … crashed 5x … giving up` | Crash-loop genuíno | Inspecione `docker compose logs constella`; corrija a causa antes de reiniciar |
+| Migração de schema falha em DB novo | Permissão de volume / corrupção | Garanta que `/data` seja de `node:node` e gravável; o launcher aborta se a migração de um DB novo falhar |
+
+---
+
+## Links relacionados ✦
+
+- [INSTALLATION](./INSTALLATION.md) — obter o pacote + pré-requisitos
+- [START_MODE](./START_MODE.md) · [AUTH_MODE](./AUTH_MODE.md) · [PORTABLE_MODE](./PORTABLE_MODE.md) — os outros modos de execução
+- [CONFIGURATION](./CONFIGURATION.md) — variáveis de ambiente e ajustes
+- [ARCHITECTURE](./ARCHITECTURE.md) — web + worker, jaula de FS, motor de sync
+- [UPDATE](./UPDATE.md) — atualizações cientes do contexto (`docker compose` no `vps`)
+- [TELEGRAM](./TELEGRAM.md) — controle remoto da empresa headless
+- [PUBLIC_API](./PUBLIC_API.md) · [MCP](./MCP.md) — dirigir o Constella remotamente
+- [SECURITY](./SECURITY.md) — cofre, jaula de FS, limpeza de segredos
+- [TROUBLESHOOTING](./TROUBLESHOOTING.md) · [FAQ](./FAQ.md)