constella 0.1.0

package/docs/pt/FAQ.md

@@ -0,0 +1,258 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/FAQ.md) · [✦ Constella](../../README.pt-BR.md)
+
+# FAQ — Sinais da Nave de Controle ✦🌌
+
+![](../assets/divider-orbit.svg)
+
+Respostas honestas para as perguntas que as pessoas realmente fazem antes (e depois) de lançar sua primeira empresa de agentes. Tudo aqui é fundamentado no código real — sem marketing, sem promessas vazias.
+
+---
+
+## Quando usar esta página
+
+- Você está avaliando o Constella e quer saber o que é **real** vs. aspiracional.
+- Você bateu numa decisão (qual run mode? modelos locais ou na nuvem? como limito gastos?) e quer a resposta curta e fundamentada.
+- Você quer um índice rápido para a documentação mais profunda — cada resposta aponta para a página canônica.
+
+---
+
+## Como funciona (o modelo em 30 segundos) 🛰️
+
+O Constella é uma **plataforma de controle local-first**. Ela roda uma pequena nave de serviços na sua máquina — um app web Next.js mais um worker em segundo plano — e a partir daí faz spawn de **agentes CLI reais** (`claude`, `codex` e outros) como subprocessos que leem, escrevem e entregam código dentro de um diretório de workspace isolado. O diretório em disco é a fonte da verdade; o banco SQLite é um índice sobre ele.
+
+```mermaid
+flowchart LR
+  OP["Operador"] -->|chat / aprovação| WEB["App web (Next.js)"]
+  WEB --> DB[("SQLite · constella.db")]
+  WEB --> FS[["Diretório do workspace (jail de FS)"]]
+  WK["Worker (cron · watcher · Telegram)"] --> WEB
+  WK -->|spawn| CLI["CLI claude / codex"]
+  CLI --> FS
+  EXT["Host de IA externo (MCP / API)"] -.->|PAT| WEB
+```
+
+---
+
+## 1. Isso é real? 🌠
+
+**Sim.** Os agentes não são mocks roteirizados. `src/server/adapters/cli.ts` faz spawn das CLIs `claude` (Claude Code) e `codex` instaladas localmente como subprocessos reais com `spawn(...)`, alimenta o prompt via stdin e extrai uso de tokens e custo **reais** da saída JSON delas:
+
+- `runClaude()` roda `claude -p --output-format json …` e lê `is_error`, `result`, `usage` e `total_cost_usd` direto da CLI.
+- Quando uma CLI não emite uso (ex.: modos headless de Hermes, Aider, Cursor) o custo é registrado como `0` — **zero honesto**, nunca um número inventado (`base()` e os comentários de cada runner deixam isso explícito).
+- O diretório de trabalho (`cwd`) do agente é o workspace real da organização, então as edições caem em arquivos reais; a Team Room renderiza **diffs reais** extraídos das chamadas de ferramenta `Edit`/`Write` da CLI (`mapTool` no mesmo arquivo).
+
+Não há chaves de API mantidas pelo Constella no caminho Claude/Codex — ele dirige seu **login/assinatura de CLI existente**.
+
+→ [AI_ARCHITECTURE](./AI_ARCHITECTURE.md) · [AGENTS](./AGENTS.md) · [ARCHITECTURE](./ARCHITECTURE.md)
+
+---
+
+## 2. Modelos locais ou na nuvem? 🪐
+
+Ambos, dependendo da tarefa:
+
+| Camada | Backend | Onde definido |
+| --- | --- | --- |
+| **Agentes de raciocínio / código** | CLIs na nuvem por padrão (`claude`, `codex`, mais Aider/OpenCode/Copilot/Cursor/Cline/Kilo) roteados pelos próprios logins | `src/server/adapters/cli.ts`, `CLI_MODELS` |
+| **Modelos de chat locais** | Servidor de chat `llama.cpp` em `LLAMACPP_URL` (padrão `http://127.0.0.1:8082`), GGUF do catálogo `lmstudio-community` | `src/server/local-models.ts`, `src/data/model-catalog.ts` |
+| **Embeddings de RAG** | Servidor de embeddings `llama.cpp` dedicado `CONSTELLA_EMBED_URL` (padrão `http://127.0.0.1:8083`), iniciado automaticamente no boot; com fallback para Ollama (`OLLAMA_URL`, `nomic-embed-text`) | `src/server/rag.ts` |
+
+O catálogo de modelos é puxado de `models.dev` (`https://models.dev/api.json`, cacheado por 24h em `~/.constella/cache/models-dev.json`) com uma tabela offline `FALLBACK_MODELS` embutida. Antes de baixar um GGUF local, `detectHardware()` sonda CPU/RAM/GPU/VRAM e recomenda uma quantização (`Q5_K_M`/`Q4_K_M`/`Q4_0`) e uma contagem máxima de parâmetros que realmente caiba.
+
+Então: **nuvem para o raciocínio pesado, local para embeddings/RAG (e chat local opcional).** Se nenhum backend de embedding estiver de pé, o RAG degrada para uma heurística por palavra-chave em vez de falhar.
+
+→ [MODELS](./MODELS.md) · [KB_RAG](./KB_RAG.md) · [MEMORY_RAG](./MEMORY_RAG.md)
+
+---
+
+## 3. Como controlo o custo? 🕳️
+
+Dois tetos rígidos, ambos **aplicados no servidor no momento do dispatch** em `src/server/budget.ts`:
+
+- **Teto diário por agente** — `agent.dailyCapUsd` (USD). Cada um dos 10 agentes semeados vem com um padrão sensato (ex.: Ada `15`, Linus `40`, Margaret `50`, Vannevar `10`). Altere com `setAgentDailyCap(agentId, usd)` na UI de Custos.
+- **Teto mensal do workspace** — `budget.monthlyCapUsd` (USD), definido com `setMonthlyCap(usd)`.
+
+O portão é `canDispatch(...)`:
+
+```ts
+return spentTodayUsd < a.dailyCapUsd && monthlySpentUsd < b.monthlyCapUsd;
+```
+
+Um agente só pode gastar se estiver **abaixo de ambos**: seu teto diário e o teto mensal do workspace. O teto também aparece no arquivo de persona de cada agente (`Stop at the daily budget cap ($<cap>).`), então o agente é avisado do seu próprio limite.
+
+Outras alavancas de custo:
+
+- Cada agente roda num tier que você escolhe (`opus`/`sonnet`/`haiku` para o Claude; modelos mais baratos reduzem o gasto).
+- A pesquisa web (`WebSearch`/`WebFetch`) vem ligada por padrão, mas pode ser desligada (`CONSTELLA_WEB_RESEARCH=0`).
+- As execuções têm timeout rígido (padrão `180s`) para que uma run travada não sangre o orçamento indefinidamente.
+
+→ [CONFIGURATION](./CONFIGURATION.md) · [AGENTS](./AGENTS.md)
+
+---
+
+## 4. Onde ficam meus dados? 🌌
+
+Tudo permanece sob uma única raiz de runtime na sua máquina — não existe nuvem do Constella:
+
+| Coisa | Localização |
+| --- | --- |
+| Raiz de runtime | `~/.constella` (sobrescreva com `CONSTELLA_HOME` ou `--path`) |
+| Banco de dados | `<HOME>/constella.db` (`DATABASE_URL=file:<HOME>/constella.db`) |
+| Workspace por organização | `~/.constella/organizations/<orgId>/workspace/` |
+| Segredos | `<HOME>/.env`, gravado com modo `0o600` (chmod 600): `BETTER_AUTH_SECRET`, `CONSTELLA_VAULT_KEY`, `CONSTELLA_WORKER_SECRET` |
+| Cache de modelos | `~/.constella/cache/models-dev.json` |
+| Backups de update | `<HOME>/backups/<timestamp>/` |
+
+O diretório do workspace é a **fonte da verdade** (`src/lib/fs-workspace.ts`); o SQLite o indexa. Cada organização é chaveada pelo seu `organization.id` estável, e todo acesso é isolado por `safe()` — sem traversal de caminho, sem vazamento entre organizações. Chaves de provedores e tokens são criptografados em repouso (AES-256-GCM) na tabela `vault`.
+
+→ [ARCHITECTURE](./ARCHITECTURE.md) · [SECURITY](./SECURITY.md) · [CONFIGURATION](./CONFIGURATION.md)
+
+---
+
+## 5. Posso rodar em várias máquinas? 🚀
+
+Sim — dois padrões suportados, mais uma ressalva:
+
+- **Modo portable** (`--portable`): a raiz de runtime fica num **pendrive USB** montado como raiz, carregado entre máquinas. Requer `>=32GB` livres (fatal abaixo disso); `>=32GB` está ok. Login (e-mail+senha) é obrigatório e ele faz bind em `0.0.0.0`.
+- **Modo VPS** (`--vps`): o Constella roda em Docker num servidor e você o acessa pela sua **tailnet Tailscale**. Bind em `0.0.0.0`, login obrigatório.
+
+Ressalva: as credenciais de assinatura da CLI (`~/.claude/.credentials.json`) ficam no host que roda os agentes. O Constella copia as credenciais Claude do operador para um diretório de config limpo por agente para que os agentes permaneçam logados (veja Q8), mas a **máquina host** ainda precisa de um login de CLI válido. O modo portable carrega os dados do Constella, não necessariamente a autenticação de cada CLI.
+
+**Não há sincronização multi-máquina embutida de um mesmo workspace** — escolha um único host (VPS) ou carregue o pendrive (portable).
+
+→ [PORTABLE_MODE](./PORTABLE_MODE.md) · [VPS_MODE](./VPS_MODE.md)
+
+---
+
+## 6. Qual run mode devo escolher? 🛰️
+
+São quatro (`src/lib/run-mode.ts`, `type RunMode = "start" | "auth" | "vps" | "portable"`):
+
+| Modo | Login | Bind | Melhor para |
+| --- | --- | --- | --- |
+| `start` (padrão) | nenhum — operador automático `operator@constella.dev` / `operator123` | `127.0.0.1` | Uso local solo na sua própria máquina; agentes têm **acesso total** (instalar deps, rodar testes) |
+| `auth` | e-mail + senha a cada sessão | `127.0.0.1` | Local, mas você quer um portão de login real |
+| `vps` | e-mail + senha | `0.0.0.0` | Um servidor compartilhado via Tailscale, roda em Docker; agentes **enjaulados** apenas a edições |
+| `portable` | e-mail + senha | `0.0.0.0` | Um USB que você carrega entre máquinas; agentes **enjaulados** |
+
+```mermaid
+flowchart TD
+  Q{"Onde vai rodar?"}
+  Q -->|Minha máquina, só eu| START["start (sem login, agente com acesso total)"]
+  Q -->|Minha máquina, quero login| AUTH["auth"]
+  Q -->|Um servidor que acesso remotamente| VPS["vps (Docker + Tailscale)"]
+  Q -->|Um USB que carrego| PORT["portable"]
+```
+
+O modo é armazenado em `organization.runMode`. No modo `start` os agentes rodam com `--permission-mode bypassPermissions` (total); em `vps`/`auth`/`portable` eles rodam `--permission-mode acceptEdits` (enjaulados). Sobrescreva com `CONSTELLA_AGENT_FULL_ACCESS=1|0`.
+
+→ [START_MODE](./START_MODE.md) · [AUTH_MODE](./AUTH_MODE.md) · [VPS_MODE](./VPS_MODE.md) · [PORTABLE_MODE](./PORTABLE_MODE.md)
+
+---
+
+## 7. IAs externas podem dirigir o Constella? (MCP / API) 🌠
+
+**Sim — saída (outbound), com um Personal Access Token.**
+
+- **API REST pública v1** (`src/app/api/v1/[[...path]]/route.ts`): autentique com `Authorization: Bearer cn_<token>` (um PAT, hasheado com SHA-256 na tabela `personalAccessToken`, com `scope` `read|write`). O cabeçalho opcional `X-Constella-Org` seleciona a organização. O rate limit é **120 req/min/token**. Leituras: `/me`, `/status`, `/review`, `/goals`, `/issues`, `/tasks`, `/specs`, `/kb?q=`. Escritas (escopo write): `/plan/approve`, `/plan/reject`, `/execution`, `/goals/:id/cancel`, `/goals/:id/archive`, `/work`, `/kb`.
+- **Servidor MCP** (`scripts/mcp-server.mjs`): um servidor JSON-RPC sobre stdio autocontido (sem dependências) que mapeia essas rotas REST para ferramentas MCP (`constella_status`, `constella_review`, `constella_approve_plan`, `constella_new_work`, …). Aponte o Claude Desktop / Cursor / qualquer host MCP para ele com `CONSTELLA_PAT`, `CONSTELLA_BASE_URL` (padrão `http://localhost:3000`) e o opcional `CONSTELLA_ORG`.
+
+Duas direções, não as confunda:
+
+| Direção | O que significa | Mecanismo |
+| --- | --- | --- |
+| **Outbound (IA → Constella)** | Um host externo dirige sua empresa | API v1 / `scripts/mcp-server.mjs` + PAT |
+| **Inbound (agente Constella → MCP externo)** | Os próprios agentes do Constella consomem um servidor MCP externo | A config `~/.claude` da própria CLI `claude` — **não** a tabela de plugins do app |
+
+→ [PUBLIC_API](./PUBLIC_API.md) · [MCP](./MCP.md) · [TELEGRAM](./TELEGRAM.md)
+
+---
+
+## 8. Como os agentes permanecem logados? 🛰️
+
+Os agentes herdam o **login de CLI do seu operador**, não um conjunto separado de chaves. No caminho Claude:
+
+- O Constella **não** redireciona `CLAUDE_CONFIG_DIR` (as credenciais de assinatura vivem ali — redirecioná-lo deslogaria o agente). Em vez disso, por padrão ele passa uma sobreposição de settings (`{ "disableAllHooks": true }`, gravada num arquivo temporário) para que o agente rode **vanilla** — independente dos seus hooks/plugins pessoais em `~/.claude` — mantendo a autenticação intacta (`vanillaSettingsArgs()`).
+- Quando o file-locking ou o guard de comandos estão ligados, o Constella monta um diretório de config limpo por agente (`<HOME>/.agent-claude`) e **copia seu `~/.claude/.credentials.json`** para dentro dele, mantendo o agente logado e carregando apenas os hooks do próprio Constella (`agentClaudeDir()`). Se o arquivo de credenciais estiver ausente, ele **cai de volta para o vanilla** — o file-locking degrada, a autenticação nunca quebra.
+
+CLIs roteadas por provedor (Aider, OpenCode, Copilot, Cursor, Cline, Kilo) autenticam pelo **próprio** login/config — o Constella as dirige, mas nunca guarda suas chaves. A UI mostra uma string de `LOGIN_HINTS` (ex.: `opencode auth login`) quando a autenticação não é detectada.
+
+→ [AGENTS](./AGENTS.md) · [MODELS](./MODELS.md) · [SECURITY](./SECURITY.md)
+
+---
+
+## 9. A UI do produto é multilíngue? 🌌
+
+**A UI do produto é apenas em inglês, por regra.** `src/lib/i18n.ts` mantém o dicionário inglês `en` como as strings **fonte**; o dicionário português `pt` é um espelho reservado para o futuro e validado por paridade de chaves (`scripts/i18n-parity.mjs`). O encanamento de tradução existe (`useT()`, `getServerLang()`, cookie `cn-lang`, `user.lang`), mas o inglês é o idioma da UI entregue. Todo o código, strings de UI e até diálogos de confirmação são em inglês.
+
+(Esta documentação é bilíngue — EN + PT-BR — mas isso é documentação, não o produto em execução.)
+
+→ [CONFIGURATION](./CONFIGURATION.md)
+
+---
+
+## 10. Passo a passo: da instalação à primeira mudança entregue
+
+1. **Instalar e iniciar** — `npx constella` (modo `start` padrão). → [INSTALLATION](./INSTALLATION.md)
+2. **Onboarding** — criar org + workspace, importar uma fonte (`new`/`github`/`local`/`mock`), montar `.claude/`, semear 10 agentes + skills + plugins. → [ONBOARDING](./ONBOARDING.md)
+3. **Definir orçamentos** — escolha um teto mensal de workspace e tetos diários por agente. → [CONFIGURATION](./CONFIGURATION.md)
+4. **Iniciar trabalho** — mande DM `@ada` "build X", ou `/new-work`. → [DM](./DM.md) · [WORKFLOW](./WORKFLOW.md)
+5. **Aprovar o plano** — revise o plano da CEO e `/approve`. → [GOALS_SPECS_ISSUES](./GOALS_SPECS_ISSUES.md)
+6. **Ver entregar** — os agentes executam, revisam, testam e (opcionalmente) dão push. → [TEAM_ROOM](./TEAM_ROOM.md)
+
+---
+
+## Estados possíveis (referência rápida)
+
+| Objeto | Estados |
+| --- | --- |
+| Status do agente | `idle` · `working` · `review` · `blocked` |
+| Saúde do agente | `alive` · `stale` · `down` |
+| Goal | `active` · `cancelled` · `archived` · `done` |
+| Coluna do issue | `todo` · `doing` · `blocked` · `review` · `done` |
+| Escopo do PAT | `read` · `write` |
+| Run mode | `start` · `auth` · `vps` · `portable` |
+| Backend de embedding | Ollama → servidor embed llama.cpp → fallback por palavra-chave |
+
+---
+
+## Integrações relacionadas
+
+- **Telegram** — controle remoto pelo celular via token de bot no vault; a Ada responde. → [TELEGRAM](./TELEGRAM.md)
+- **GitHub** — PAT no vault (ou OAuth), commit/push e export de fonte limpa. → [GITHUB](./GITHUB.md)
+- **MCP / API** — controle outbound a partir de hosts de IA externos. → [MCP](./MCP.md) · [PUBLIC_API](./PUBLIC_API.md)
+- **Modelos locais** — servidores de chat + embed llama.cpp, catálogo GGUF. → [MODELS](./MODELS.md)
+
+---
+
+## Segurança em um parágrafo 🕳️
+
+O workspace é um jail de FS (`safe()` — checagens léxicas + de symlink, sem traversal, raiz nunca deletada). Segredos são criptografados (AES-256-GCM, tabela `vault`) e higienizados (`scrubSecrets`) antes de qualquer ingestão na KB, envio ao Telegram ou log. Um guard de comandos destrutivos (`bin/guard-hook.mjs`, ligado por padrão) bloqueia shell catastrófico; um hook de file-lock opcional impede que agentes paralelos atropelem uns aos outros. A autenticação é better-auth com e-mail+senha, com 2FA TOTP e passkeys WebAuthn opcionais.
+
+→ [SECURITY](./SECURITY.md)
+
+---
+
+## Solução de problemas (FAQ-do-FAQ)
+
+| Sintoma | Causa provável | Correção |
+| --- | --- | --- |
+| Run do agente falha com "no JSON output" | CLI `claude` não instalada/deslogada | Faça login no Claude Code; verifique com `claude --version` |
+| Custos do agente aparecem como `0` | Aquela CLI não emite uso (headless Hermes/Aider/Cursor) | Esperado — é um zero honesto, não um bug |
+| Respostas de RAG fracas/só por palavra-chave | Nenhum backend de embedding rodando | Garanta que o servidor embed llama.cpp (`:8083`) ou o Ollama (`:11434`) esteja de pé |
+| API retorna `429` | Acima de `120 req/min` num token | Reduza a frequência; o limite reinicia a cada minuto |
+| API retorna `403` numa escrita | Token tem escopo `read` | Crie um PAT com escopo `write` |
+| Agente "fala como meu plugin" | Hooks `~/.claude` do operador vazaram | O `disableAllHooks` padrão deve evitar isso; confirme que não há override |
+| Boot portable aborta | Menos de `32GB` livres no drive | Use um drive com ≥ 32 GB livres |
+
+→ [TROUBLESHOOTING](./TROUBLESHOOTING.md)
+
+---
+
+## Links relacionados
+
+- [ARCHITECTURE](./ARCHITECTURE.md) · [AI_ARCHITECTURE](./AI_ARCHITECTURE.md) · [AGENTS](./AGENTS.md)
+- [START_MODE](./START_MODE.md) · [AUTH_MODE](./AUTH_MODE.md) · [VPS_MODE](./VPS_MODE.md) · [PORTABLE_MODE](./PORTABLE_MODE.md)
+- [CONFIGURATION](./CONFIGURATION.md) · [MODELS](./MODELS.md) · [KB_RAG](./KB_RAG.md) · [MEMORY_RAG](./MEMORY_RAG.md)
+- [PUBLIC_API](./PUBLIC_API.md) · [MCP](./MCP.md) · [TELEGRAM](./TELEGRAM.md) · [GITHUB](./GITHUB.md)
+- [SECURITY](./SECURITY.md) · [TROUBLESHOOTING](./TROUBLESHOOTING.md) · [INSTALLATION](./INSTALLATION.md)

package/docs/pt/GITHUB.md

@@ -0,0 +1,341 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/GITHUB.md) · [✦ Constella](../../README.pt-BR.md)
+
+# GitHub 🛰️
+
+![](../assets/divider-orbit.svg)
+
+A baía de lançamento que conecta o workspace de uma constelação a um remoto Git real. Daqui partem duas rotas de voo distintas: **Commit GitHub** (o workspace completo do plano de controle → o `origin` vinculado) e **Export Clean Source** (apenas o produto, sem a camada interna da Constella → um repositório separado). Ambas passam pela mesma comporta de varredura de segredos.
+
+> Fonte da verdade: [`src/server/github.ts`](../../src/server/github.ts), [`src/server/prepare-deploy.ts`](../../src/server/prepare-deploy.ts), [`src/server/git-scan.ts`](../../src/server/git-scan.ts).
+
+---
+
+## 1. Quando usar 🌠
+
+- Você conectou uma conta GitHub durante o onboarding (ou quer conectar/substituir uma agora).
+- Um agente (ou você) terminou um trabalho e quer **histórico git local real** mais um **push para o remoto**.
+- Você quer publicar **apenas o produto** — sem `.claude/`, docs de planejamento ou qualquer arquivo interno de controle — em um repositório público/separado.
+- Você precisa garantir que nenhum segredo vazou antes que algo deixe a nave.
+
+---
+
+## 2. Como funciona 🌌
+
+Todo workspace vive na raiz da organização em disco (`orgRoot(org.id)`). O módulo GitHub opera sobre esse diretório como um **repositório git normal**:
+
+- `ensureRepo(cwd)` executa `git init -b main` no primeiro uso e cria um `.gitignore` padrão para que `git add -A` nunca prepare `node_modules/`, `.next/`, `dist/`, saída de build, `.env*`, `uploads/` ou `.testdev/`.
+- A autenticação usa um **token do GitHub** resolvido por `ghToken(workspaceId, userId)`:
+  1. **PAT no cofre** (`getSecret(workspaceId, "github_pat")`) — preferido.
+  2. **Token de acesso OAuth** — o `account.accessToken` do GitHub do usuário (via better-auth), utilizável para git **somente** se o app OAuth recebeu o escopo `repo`.
+- O token é **redatado de toda string capturada** (`redact()` divide pela string do token e a substitui por `***`), de modo que nunca pode vazar para uma notificação, o Inbox ou a UI.
+- Todas as chamadas à API do GitHub passam por `ghApi(token, path)` contra `https://api.github.com` com timeout de 12s e `User-Agent: constella`.
+
+### As duas rotas de voo
+
+| Rota | Função | Diretório de origem | Alvo | Remove a camada interna? | Estilo de push |
+|------|--------|---------------------|------|--------------------------|----------------|
+| **Commit GitHub** | `commitPush()` em `github.ts` | o workspace ao vivo (`orgRoot`) | o repositório `origin` **vinculado** | Não — faz commit de todo o workspace (menos o `.gitignore`) | `git push HEAD:<branch>` |
+| **Export Clean Source** | `exportCleanSource()` em `prepare-deploy.ts` | uma árvore limpa em **temp** | um repositório **separado** (`owner/repo`) | Sim — só sobrevive o que passa por `isCleanProductPath` | `git push -f HEAD:<branch>` |
+
+---
+
+## 3. Fluxo principal 🚀
+
+### Conectar
+
+```
+connectGitHub(pat)
+  → trim + checagem de tamanho
+  → GET https://api.github.com/user  (verifica que o token de fato funciona; 401 → erro)
+  → apaga qualquer linha github_pat existente → putSecret(ws, "github_pat", token)
+  → vincula { login, repo: undefined, defaultBranch: undefined } em workspace.settings.github
+```
+
+O vínculo de repositório é **limpo ao (re)conectar**, para que uma conta diferente não consiga dar push no repositório da conta anterior.
+
+### Vincular um repositório
+
+```
+setRepo("owner/repo")
+  → normaliza (remove https://github.com/ e .git)
+  → ghToken() precisa alcançar GET /repos/owner/repo  (404 → "o token não consegue acessá-lo")
+  → ensureRepo(cwd) → git remote add|set-url origin https://github.com/owner/repo.git
+  → persiste settings.github = { repo, defaultBranch }
+```
+
+`createRepo({ name, private })` é um atalho: faz `POST` em `/user/repos` e então chama `setRepo` no novo nome completo.
+
+### Commit + push
+
+`commitPush({ repo, branch, message, delegated?, force? })` executa três portões de segurança **antes** de tocar no git, então faz o commit e (opcionalmente) push / abre um PR. Veja [§4](#4-conceitos-chave-) e o diagrama em [§8](#8-diagramas-mermaid-).
+
+### Exportar código limpo
+
+`exportCleanSource({ repo, token?, branch?, message? })` copia apenas o produto limpo para um diretório temporário, varre-o e faz force-push para um repositório **diferente**. Ele nunca toca no `origin` do próprio workspace.
+
+---
+
+## 4. Conceitos-chave 🪐
+
+### PAT vs token OAuth
+
+| | PAT no cofre (`github_pat`) | OAuth `account.accessToken` |
+|---|---|---|
+| Armazenado onde | tabela `vault`, AES-256-GCM (`CONSTELLA_VAULT_KEY`) | linha `account` do better-auth |
+| Definido por | `connectGitHub()` / onboarding | login OAuth do GitHub |
+| Usado para git push? | Sim | Somente se receber o escopo `repo` |
+| Precedência | **Primeiro** (preferido) | Fallback quando não há PAT |
+| Por empresa | Sim — no cofre por `workspaceId` | Por conta de usuário |
+
+`ghToken()` sempre retorna o PAT se presente, caso contrário o token OAuth, caso contrário `null` ("Connect GitHub first").
+
+### Vínculo do `setRepo` — o guarda por empresa
+
+O repositório escolhido é registrado em `workspace.settings.github.repo` (e `defaultBranch`). Esse vínculo é verificado depois, na hora do commit, para que um agente jamais consiga dar push em um repositório que o token desta empresa não deveria alcançar. O vínculo **falha** se o token vinculado não conseguir `GET /repos/owner/repo`.
+
+### `refreshGitStatus` — reconciliando a árvore de trabalho
+
+`file.gitStatus` nunca é preenchido pelo watcher; `refreshGitStatus()` executa o **real** `git status --porcelain -z --untracked-files=all` e reconcilia a tabela `file` para que os módulos GitHub + Code mostrem as mudanças reais.
+
+- `-z` → caminhos **crus** separados por NUL (renames/copies consomem um campo extra de caminho antigo; nomes não-ASCII permanecem intactos).
+- Cada entrada mapeia para um código de uma letra: `U` (não rastreado `?`), `D` (deletado), `A` (adicionado), senão `M` (modificado).
+- Caminhos `.git/` e `node_modules/` são ignorados.
+- Arquivos que não estão mais alterados têm seu `gitStatus` limpo de volta para `""`.
+- Um lock em memória por workspace (Set `refreshing`) evita que duas renderizações concorrentes disputem a reconciliação e insiram linhas duplicadas.
+
+### Commit GitHub vs Export Clean Source
+
+- **Commit GitHub** = histórico git local honesto do *workspace inteiro*, com push para o `origin` *vinculado*. A camada do plano de controle (`.claude/`, diretórios de planejamento) também entra no commit (faz parte do seu repositório privado).
+- **Export Clean Source** = uma *árvore limpa* — apenas arquivos que passam por `isCleanProductPath()` — com force-push para um repositório *separado*. Este é o caminho para publicar o produto entregável sem expor as entranhas da Constella.
+
+`isCleanProductPath(rel)` rejeita qualquer caminho cujo diretório de topo esteja em `DENY_TOP` (`.claude`, `DOCS`, `PO`, `Reports`, `specs`, `issues`, `mock`, `uploads`, `archives`, `.testdev`, `node_modules`, `.git`, `.next`, `dist`, `build`, `out`, `coverage`, `.cache`, `.turbo`, `vendor`), qualquer coisa sob `.constella`, e qualquer arquivo `SENSITIVE` (`.env*`, chaves privadas, `*.pem/.key/.p12/...`, JSON de credenciais, dumps/db/logs) — **exceto** templates de env inofensivos que casam com `ALLOW_ENV` (`.env.example|.sample|.template|.dist`).
+
+### Varredura de segredos — a comporta compartilhada
+
+Ambas as rotas chamam `scanForSecrets(cwd)` de `git-scan.ts`. Ela varre os arquivos que *seriam* commitados (o conjunto de mudanças da árvore de trabalho; arquivos no gitignore já estão excluídos pelo `git status`).
+
+- **Arquivos que nunca podem ser commitados** por nome: `.env*`, `id_rsa*`, `*.pem/.key/.p12/.pfx/.keystore/.jks/.ppk/.asc`, `credentials.json`, `service-account*.json`, `*.sql/.dump/.bak/.sqlite/.db`, `*.local`, `npm-debug.log` — exceto templates `ALLOW_FILE`.
+- **Padrões de conteúdo de alta confiança**: chave de acesso AWS, token do GitHub, chave OpenAI/Anthropic, chave de API Google, token Slack, bloco de chave privada, JWT, URL de DB com credenciais, token de bot do Telegram, e um padrão genérico de segredo hardcoded.
+- O padrão genérico é suprimido para **placeholders** óbvios (`your_`, `xxx`, `<...>`, `change_me`, `example`, `placeholder`, `***`, `dummy`, `todo`, `redacted`, `...`).
+- As ocorrências são **redatadas** no preview (`primeiros4•••últimos2`).
+- Arquivos acima de 2 MB e arquivos binários (contendo `\0`) são ignorados; a varredura limita-se a 3000 arquivos / 300 ocorrências.
+
+---
+
+## 5. Tabelas 🌌
+
+### `vault` (ref relevante)
+
+| Coluna | Valor para o GitHub |
+|--------|---------------------|
+| `ref` | `github_pat` |
+| `ciphertext` | texto cifrado AES-GCM do PAT |
+| `iv` | IV por segredo |
+
+### `workspace.settings.github` (JSON)
+
+| Campo | Significado |
+|-------|-------------|
+| `login` | nome de usuário GitHub da conta conectada |
+| `repo` | `owner/repo` vinculado (o vínculo por empresa) |
+| `defaultBranch` | branch padrão do repositório (vinda da API) |
+
+### `file.gitStatus`
+
+| Código | Significado |
+|--------|-------------|
+| `""` | sem mudança |
+| `M` | modificado |
+| `A` | adicionado / novo preparado |
+| `U` | não rastreado |
+| `D` | deletado |
+
+### `deploy_run.lastExport` (definido por `exportCleanSource`)
+
+| Campo | Significado |
+|-------|-------------|
+| `ok` | exportação bem-sucedida |
+| `sha` | SHA curto do commit da árvore limpa |
+| `copied` | número de arquivos limpos enviados |
+| `repo` / `branch` | alvo da exportação |
+| `at` | timestamp |
+
+### `PushResult` (retorno de `commitPush`)
+
+| Campo | Significado |
+|-------|-------------|
+| `ok` | um commit real aconteceu |
+| `committed` | commit local criado |
+| `sha` | sha curto do HEAD |
+| `pushed` | alcançou o remoto |
+| `prUrl` | URL do PR (somente na rota delegada) |
+| `nothing` | árvore de trabalho não tinha nada para commitar |
+| `blocked` | um portão de segurança parou o commit |
+| `secrets` | ocorrências da varredura de segredos quando bloqueado |
+
+---
+
+## 6. Passo a passo 🛰️
+
+### Commit do workspace para o repositório vinculado
+
+1. **Conecte** um PAT (`connectGitHub`) ou faça login com OAuth do GitHub (escopo `repo`).
+2. **Vincule** um repositório com `setRepo("owner/repo")` (ou `createRepo`).
+3. (Opcional) **Atualize** o status — `refreshGitStatus()` preenche a lista de mudanças; `draftCommitMessage()` propõe um assunto Conventional-Commit a partir das contagens de `A`/`M`/`D`.
+4. **Varra** sob demanda com `scanWorkspace()` (sem commit) para pré-visualizar ocorrências.
+5. **Commit + push** com `commitPush({ repo, branch, message })`. Passe `delegated: true` para também abrir um PR via `gh pr create --fill`. Passe `force: true` para contornar o portão de varredura de segredos *após revisão*.
+
+### Exportar apenas o produto
+
+1. Execute **Prepare Deploy** (ou `previewCleanExport()`) para ver a árvore limpa + uma varredura pré-exportação.
+2. Chame `exportCleanSource({ repo: "myorg/my-app-public" })` — ou `/export-source myorg/my-app-public` no chat.
+3. A árvore limpa é construída em um diretório temporário, varrida em busca de segredos, commitada e enviada com **force-push** para o repositório separado. `deploy_run.lastExport` registra o resultado.
+
+---
+
+## 7. Exemplos 🌠
+
+### Comandos de barra
+
+```
+/github                      # atualiza o status do git, reporta a contagem de arquivos alterados (Werner)
+/export-source myorg/app-pub # exporta o produto limpo para um repositório separado
+/prepare-deploy              # executa o pipeline completo de preparo para produção
+```
+
+`/github` (tratado em `src/server/commands.ts`) chama `refreshGitStatus()` e posta a contagem de arquivos alterados pelo Werner (DevOps).
+
+### Mensagens do portão de commit (strings reais)
+
+```
+Blocked: 2 potential secret(s)/sensitive file(s) in the change set. Resolve them or review before committing.
+Origin (acme/app) doesn't match this company's configured repo (acme/app-2). Re-select the repo before committing.
+committed locally — connect a GitHub PAT to push
+```
+
+### URL de push autenticada
+
+`commitPush` reescreve o origin HTTPS para injetar o PAT apenas no momento do push:
+
+```
+https://github.com/owner/repo.git
+→ https://x-access-token:<PAT>@github.com/owner/repo.git   (usada no `git push`, redatada em todo o resto)
+```
+
+---
+
+## 8. Diagramas Mermaid 🪐
+
+### Commit GitHub vs Export Clean Source
+
+```mermaid
+flowchart TD
+  subgraph WS["Workspace em disco (orgRoot)"]
+    A[".claude / DOCS / PO / specs / issues / mock"]
+    B["código do produto + README + .env.example"]
+  end
+
+  WS --> P{Qual rota?}
+
+  P -->|"Commit GitHub<br/>commitPush()"| G1["Portão 1: PAT para esta empresa?"]
+  G1 --> G2["Portão 2: origin == repo vinculado?"]
+  G2 --> G3["Portão 3: scanForSecrets()"]
+  G3 -->|"ocorrências"| BLK1["BLOQUEADO → Inbox + notifyOps"]
+  G3 -->|"limpo (ou force)"| C1["git add -A → commit → push HEAD:branch"]
+  C1 --> C2["delegated? gh pr create --fill"]
+  C1 --> ORIGIN["repo origin vinculado<br/>(workspace inteiro)"]
+
+  P -->|"Export Clean Source<br/>exportCleanSource()"| E1["buildCleanTree → dir temp<br/>(filtro isCleanProductPath)"]
+  E1 --> E2["git init + add -A"]
+  E2 --> E3["scanForSecrets() — portão final"]
+  E3 -->|"ocorrências"| BLK2["BLOQUEADO → Inbox + notifyOps"]
+  E3 -->|"limpo"| E4["commit → push -f HEAD:branch"]
+  E4 --> SEP["repositório separado<br/>(somente produto)"]
+```
+
+### Resolução de token
+
+```mermaid
+flowchart LR
+  T["ghToken(ws, user)"] --> V{"vault github_pat?"}
+  V -->|sim| PAT["usa o PAT do cofre"]
+  V -->|não| OA{"conta OAuth do GitHub?"}
+  OA -->|sim| TOK["usa account.accessToken<br/>(precisa do escopo 'repo' para push)"]
+  OA -->|não| NULL["null → 'Connect GitHub first'"]
+```
+
+---
+
+## 9. Estados possíveis 🕳️
+
+### Portões de commit (em ordem)
+
+| Portão | Gatilho | Resultado |
+|--------|---------|-----------|
+| **1. PAT configurado** | sem `github_pat` para este workspace | `blocked` — "GitHub isn't configured for this company" |
+| **2. Repo vinculado + origin casa** | sem `settings.github.repo` / sem origin, ou divergência | `blocked` — re-selecione o repositório |
+| **3. Varredura de segredos** | qualquer ocorrência (e `force` não definido) | `blocked`, `secrets[]`, card no Inbox + notificação aos operadores |
+
+Após os portões passarem: `committed` → opcional `pushed` → opcional `prUrl`. Uma árvore de trabalho sem nada a commitar retorna `nothing: true`.
+
+### Rejeição de push
+
+Um push rejeitado / non-fast-forward (`rejected | non-fast-forward | fetch first | merge conflict | failed to push`) **não** é descartado silenciosamente — ele gera um card `block` no Inbox ("Push rejected — \<repo\>") para que o operador faça pull + resolva.
+
+### Estados da exportação
+
+| Estado | Causa |
+|--------|-------|
+| `ok: false, error: "Use the form owner/repo."` | alvo malformado |
+| `ok: false, error: "...token can't access it."` | `GET /repos/...` retornou 404 |
+| `blocked: true, secrets[]` | a varredura final encontrou um segredo |
+| `ok: true, pushed: true, sha, copied` | force-push limpo concluído |
+| `error: "Nothing to export yet..."` | `buildCleanTree` copiou 0 arquivos |
+
+---
+
+## 10. Integrações relacionadas 🌌
+
+- **Vault** — armazena `github_pat` criptografado; veja [SECURITY](./SECURITY.md).
+- **Inbox** — recebe cards `block` para ocorrências de segredos + rejeições de push; veja [INBOX](./INBOX.md).
+- **Prepare Deploy** — o pipeline que faz build, valida e gate da exportação limpa; veja [PREPARE_DEPLOY](./PREPARE_DEPLOY.md) e [DEPLOY](./DEPLOY.md).
+- **Agentes** — Werner (DevOps) é o agente padrão de deploy/commit; veja [AGENTS](./AGENTS.md).
+- **Comandos de chat** — `/github`, `/export-source`, `/prepare-deploy`; veja [CHAT_COMMANDS](./CHAT_COMMANDS.md).
+- **Onboarding** — import/conexão inicial do GitHub; veja [ONBOARDING](./ONBOARDING.md).
+
+---
+
+## 11. Segurança 🕳️
+
+- **Token nunca registrado.** `redact()` remove o PAT de cada stdout/stderr capturado antes que chegue à UI, ao Inbox ou às notificações. A URL de push autenticada (`x-access-token:<PAT>@...`) só é construída em memória para a chamada do `git push`.
+- **Isolamento por empresa.** O PAT fica no cofre por `workspaceId`; o vínculo é verificado contra o token; o Portão 2 do commit garante que `origin` seja igual ao repositório vinculado — você não consegue dar push no repositório de outra organização.
+- **Varredura de segredos obrigatória.** O Portão 3 do commit e o portão final da exportação ambos executam `scanForSecrets`. A flag `force` só contorna a varredura do *commit* e destina-se a uso *pós-revisão*.
+- **A exportação limpa remove as entranhas.** `isCleanProductPath` remove toda a camada de controle da Constella e todos os arquivos sensíveis antes que algo seja enviado a um repositório separado.
+- **`.gitignore` seguro.** `ensureRepo` garante que deps/build/segredos nunca sejam preparados por `git add -A`.
+
+Veja [SECURITY](./SECURITY.md) para o modelo completo de cofre + scrub.
+
+---
+
+## 12. Solução de problemas 🛰️
+
+| Sintoma | Causa provável | Correção |
+|---------|----------------|----------|
+| "Connect GitHub first." | sem PAT e sem token OAuth | execute `connectGitHub` com um PAT de escopo `repo` |
+| "Invalid token (401). ...needs the 'repo' scope." | PAT sem escopo `repo` ou errado | regenere com escopo `repo` |
+| "Repo not found, or this company's token can't access it." | `GET /repos/owner/repo` 404 | confira o nome do repositório + se a conta do token tem acesso |
+| "Origin (X) doesn't match this company's configured repo (Y)." | origin e vínculo divergiram | chame `setRepo` para re-vincular |
+| Commit `blocked` com `secrets[]` | a varredura achou um segredo/arquivo sensível | remova-o (ou mova para `.env`), ou use `force` após revisão |
+| "Push rejected — \<repo\>" no Inbox | o remoto avançou / conflito | faça pull + resolva, então push novamente |
+| O módulo GitHub mostra "No changes" mas os arquivos mudaram | `file.gitStatus` não reconciliado | dispare `refreshGitStatus()` (botão Refresh / `/github`) |
+| "committed locally — connect a GitHub PAT to push" | commit feito, sem credenciais para push | conecte um PAT |
+| "Nothing to export yet..." | nenhum arquivo de produto limpo encontrado | adicione código do produto fora dos diretórios internos |
+
+---
+
+## 13. Links relacionados 🌠
+
+- [PREPARE_DEPLOY](./PREPARE_DEPLOY.md) · [DEPLOY](./DEPLOY.md) · [PUBLISHING](./PUBLISHING.md)
+- [SECURITY](./SECURITY.md) · [INBOX](./INBOX.md) · [CHAT_COMMANDS](./CHAT_COMMANDS.md)
+- [AGENTS](./AGENTS.md) · [ONBOARDING](./ONBOARDING.md) · [CONFIGURATION](./CONFIGURATION.md)
+- [✦ Voltar ao Índice da documentação](./README.md)