constella 0.1.0

package/docs/pt/ONBOARDING.md

@@ -0,0 +1,327 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/ONBOARDING.md) · [✦ Constella](../../README.pt-BR.md)
+
+# Onboarding 🌌 — Acendendo uma Nova Constelação
+
+O assistente de primeira execução que transforma um runtime vazio em uma empresa de agentes viva: cria a organização + workspace, monta a camada de controle `.claude/`, acende a constelação de dez agentes, semeia skills e plugins, opcionalmente importa um projeto existente e entrega o operador ao Planner do CEO.
+
+---
+
+## Quando usar
+
+- **Na primeiríssima execução.** Sem organização ainda, [`requireWorkspace()`](../pt/ARCHITECTURE.md) redireciona para `/onboarding` automaticamente (`src/lib/workspace.ts`).
+- **Forçando o assistente de novo.** Lance com `npx constella --onboarding` (ou o subcomando `onboard` / `onboarding`). O `bin/constella.mjs` define `CONSTELLA_FORCE_ONBOARDING=1`, que o `requireWorkspace()` respeita redirecionando para `/onboarding` mesmo quando já existe uma org.
+- **Criando uma organização adicional** para um operador que já possui uma (o assistente mostra o botão Fechar apenas nesse caso).
+
+> 🪐 O onboarding é uma *armadilha de disparo único*. No instante em que `completeOnboarding()` roda, ele chama `delete process.env.CONSTELLA_FORCE_ONBOARDING`, então o próximo `requireWorkspace()` não redireciona mais para cá.
+
+---
+
+## Como funciona
+
+O onboarding é um assistente cliente de cinco passos (`src/app/(auth)/onboarding/page.tsx`) apoiado por uma única server action, `completeOnboarding()` em `src/server/onboarding.ts`. O assistente coleta a identidade da empresa, o cérebro do CEO (provider + model), um teste de conexão real, o stack do projeto e um brief / source — então a server action faz o trabalho pesado:
+
+1. Cria as linhas `organization` + `member` (owner) + `workspace`. O run mode ativo (`getRunMode()`) é gravado em `organization.runMode`.
+2. Opcionalmente registra um provider de fallback e guarda sua chave no vault.
+3. **Importa** material existente (repo do GitHub ou diretório local) *antes* do scaffold, para que o `README.md` importado sobreviva.
+4. **Monta** a camada de controle `.claude/` mais `DOCS/`, `PO/`, `Reports/`, `specs/`, `issues/` (`scaffoldWorkspace`).
+5. Apenas para um projeto realmente novo, escreve um **starter executável** (`scaffoldProjectStarter`).
+6. Persiste o descritor da fonte do projeto em `workspace.settings.source` (com `analyzed: false`).
+7. Cria os **dez agentes**, aplica as escolhas de CEO do operador na Ada e guarda o brief em `.claude/BRIEF.md`.
+8. Escreve quaisquer arquivos de mock anexados em `mock/`.
+9. Semeia as **skills** nativas + da biblioteca, reconcilia os vínculos por stack/role e cria os quatro **plugins** nativos.
+10. Marca a org como ativa na sessão e faz `redirect("/planner")`.
+
+O **primeiro plano** (disparado depois, quando o operador clica em *Generate plan* no `/planner`) roda a análise arquivo-por-arquivo que produz `specs/SUPER-SPEC.md` — veja [Análise do primeiro plano](#análise-do-primeiro-plano--specssuper-specmd-) abaixo.
+
+---
+
+## Fluxo principal 🛰️
+
+```mermaid
+flowchart TD
+  L["npx constella<br/>(sem org ainda)"] --> RW["requireWorkspace()"]
+  RW -->|sem org / FORCE=1| OB["assistente /onboarding"]
+  OB --> S0["1 · Empresa<br/>nome · missão · objetivo"]
+  S0 --> S1["2 · Cérebro do CEO<br/>provider + model"]
+  S1 --> S2["3 · Teste de conexão<br/>env → adapter → connection → model"]
+  S2 --> S3["4 · Stack do projeto<br/>17 categorias"]
+  S3 --> S4["5 · Brief & source<br/>new | github | local · mock · system prompt"]
+  S4 --> CO["completeOnboarding()"]
+  CO --> ORG["cria org + workspace + member"]
+  ORG --> IMP{"source?"}
+  IMP -->|github| GH["cloneRepoIntoWorkspace()"]
+  IMP -->|local| LD["copyLocalDirIntoWorkspace()"]
+  IMP -->|new| NEW["sem import"]
+  GH --> SCAF["scaffoldWorkspace()<br/>(preserveReadme se importado)"]
+  LD --> SCAF
+  NEW --> SCAF
+  SCAF --> ST{"tem material?"}
+  ST -->|não| STARTER["scaffoldProjectStarter()<br/>dev server executável"]
+  ST -->|sim| SKIP["starter suprimido"]
+  STARTER --> AG["cria 10 agentes · brief · skills · plugins"]
+  SKIP --> AG
+  AG --> RP["redirect('/planner')"]
+  RP --> GP["operador clica Generate plan"]
+  GP --> ANA{"hasMaterial && !analyzed?"}
+  ANA -->|sim| SS["analyzeExistingProject()<br/>→ specs/SUPER-SPEC.md"]
+  ANA -->|não| PLAN["rascunha specs + issues"]
+  SS --> PLAN
+```
+
+---
+
+## Os cinco passos do assistente 🌠
+
+As chaves dos passos são fixas em `STEP_KEYS = ["company", "ceoModel", "connection", "stack", "brief"]`.
+
+| # | Passo | O que o operador fornece | Obrigatório |
+|---|---|---|---|
+| 0 | **Empresa** | nome `company`, `mission`, `objective` | Os três |
+| 1 | **Cérebro do CEO** | Escolhe um `provider` + `model` detectado (ou registra um com uma API key) | Um provider + model |
+| 2 | **Teste de conexão** | Uma verificação real de quatro estágios: `checkSetupEnv` → `checkAdapter` → `testConnection` → `probeModel` | Tem que passar |
+| 3 | **Stack do projeto** | Escolhe entre 17 categorias de stack (cards ou busca) | Opcional (qualquer/todas podem ficar `None`) |
+| 4 | **Brief & source** | `source` do projeto (new/github/local), brief opcional, pasta de mock opcional, `systemPrompt` da Ada | `systemPrompt` + uma source pronta |
+
+Alguns comportamentos notáveis do código:
+
+- **A detecção de provider** roda na montagem (`detectProviders()`); o primeiro provider detectado + seu primeiro model são pré-selecionados.
+- **O teste de conexão é real** — sem timers falsos. Cada estágio é uma sonda de verdade; um estágio que falha mostra seu erro e bloqueia o *Continuar*. O `adapter:model` verificado é cacheado (`testedKey`), então Voltar → Continuar não re-executa as checagens a menos que o provider ou model mude.
+- **O stack** não tem auto-seleção; o operador escolhe cada categoria manualmente. Opções incompatíveis ficam desabilitadas (`incompat()`), e `stackNote()` traz uma dica.
+- **Finalizar** empacota tudo (`source`, `provider`, `model`, `systemPrompt`, `briefText`/`briefName`, `mockFiles`, `providerCatalogId`/`providerKey` opcionais) em `completeOnboarding()`.
+
+---
+
+## Source do projeto: `new | github | local` 🕳️
+
+O passo 5 escolhe de onde vem o produto. O campo `source` de `OnboardingInput` é um destes:
+
+```ts
+source?:
+  | { type: "new" }
+  | { type: "github"; pat: string; repoFull: string; branch?: string; login?: string }
+  | { type: "local"; path: string };
+```
+
+| Source | Função de import | Efeito | README |
+|---|---|---|---|
+| `new` | nenhuma | Projeto novo; um **starter executável** é montado | `README.md` gerado é escrito |
+| `github` | `cloneRepoIntoWorkspace()` | Clona raso `owner/repo` no workspace, guarda o PAT no vault como `github_pat`, aponta o `origin` para a URL **limpa** (sem token) | README próprio do repo preservado |
+| `local` | `copyLocalDirIntoWorkspace()` | Copia um snapshot de um diretório local absoluto para o workspace | README próprio do repo preservado |
+
+Mais uma quarta source implícita: **mock** — quando `source.type === "new"` *e* `mockFiles` estão anexados, `sourceMeta.type` vira `"mock"`.
+
+### Regras de import (de `onboarding-import.ts`)
+
+- Diretórios pesados/de dependências são pulados (`HEAVY_DIRS`); `.git`, `.env*` (mas **não** `.env.example`/`.sample`), `.DS_Store`, binários e arquivos grandes demais (> 512 KB cada) são pulados.
+- O import local é limitado a `DEFAULT_MAX_FILES = 4000` arquivos; `DEFAULT_MAX_BYTES = 512 * 1024`.
+- Toda escrita passa por `writeWorkspaceFile()` → `safe()` (jaulada por caminho; travessia rejeitada).
+- O clone do GitHub usa `git clone --depth 1 --single-branch` (`--branch` opcional) em um diretório temporário com uma URL transitória `x-access-token:<pat>@github.com`, depois copia para dentro e aponta o `origin` para `https://github.com/<owner>/<repo>.git`. O token é **redigido** de toda string retornada/logada.
+- `validateLocalDir(path)` (server action via `scanLocalDir`) verifica que o caminho é absoluto e um diretório real com arquivos importáveis; retorna um `fileCount` + uma `sample` de 8 arquivos (sem vazar conteúdo).
+
+### `preserveReadme` — por que o README importado vence
+
+Após o import, `completeOnboarding()` computa `importedReadme = readWorkspaceFile(orgId, "README.md") != null` e passa `preserveReadme` para `scaffoldWorkspace()`. Em `workspaceFiles()` o `README.md` gerado só é adicionado quando `!c.preserveReadme`, então um repo importado mantém seu **próprio** README enquanto a camada de controle `.claude/` se assenta por cima.
+
+---
+
+## O starter executável (apenas projetos realmente novos) 🚀
+
+Quando não há **material** (`hasMaterial = sourceMeta.type !== "new" || hasMock` é `false`), `scaffoldProjectStarter()` escreve um app real e configurado que sobe um dev server de imediato — para que o [Test Dev](../pt/TEST_DEV.md) possa pré-visualizá-lo já e os agentes construam o produto *por cima* dele. O starter é escrito **somente-se-ausente**, então edições dos agentes nunca são sobrescritas, e ele **não** faz parte de `workspaceFiles()` (então `bootstrapWorkspace`/`rerenderMissionDocs` nunca podem sobrescrever código de produto).
+
+O template é escolhido por `pickStarter(stack)` em `src/data/project-starter.ts`. A precedência da seleção: meta-framework → estático/sem-framework explícito → baseline Vite pelo frontend → framework de backend → fallback de linguagem → o servidor Node `static` sempre-inicializável.
+
+### Ids de starter (`StarterId`)
+
+| `StarterId` | Escolhido quando (exemplos) | Sobe com |
+|---|---|---|
+| `next` | `meta = "Next.js"` | `next dev` |
+| `vite-react` | `frontend = "React"` (ou fallback de linguagem TS/JS) | `vite` |
+| `vite-vue` | `frontend = "Vue"` | `vite` |
+| `vite-svelte` | `frontend = "Svelte"` ou `meta = "SvelteKit"` | `vite` |
+| `node-express` | `backend = "Express"` | `node server.js` |
+| `node-fastify` | `backend = "Fastify"` | `node server.js` |
+| `node-koa` | `backend = "Koa"` | `node server.js` |
+| `node-hono` | `backend = "Hono"` | `node server.js` |
+| `node-nest` | `backend = "NestJS"` | `tsx watch src/main.ts` |
+| `fastapi` | `backend = "FastAPI"` | `uvicorn` |
+| `flask` | `backend = "Flask"` ou `language = "Python"` | `python main.py` |
+| `django` | `backend = "Django"` | `manage.py` |
+| `go-http` | `language = "Go"` | `net/http` |
+| `go-gin` | `backend = "Gin"` | `gin` |
+| `rust-axum` | `language = "Rust"` | `axum` |
+| `rust-actix` | `backend = "Actix"` | `actix-web` |
+| `static` | `HTML/CSS`, `Vanilla JS`, `Static (no framework)`, ou qualquer coisa desconhecida | `http` puro do Node |
+
+> 🌠 O template `static` é o **fallback universal**: o Node está sempre presente, então todo projeto sobe *alguma coisa* independentemente do stack.
+
+Cada starter traz uma landing page temática e autocontida (paleta determinística por empresa via `paletteFor()`), um `.gitignore`, um `.env.example` e um servidor ciente de `PORT` ligado a `127.0.0.1`. A página diz "Your AI team is building **\<objective\>** on top of this starter."
+
+---
+
+## Análise do primeiro plano → `specs/SUPER-SPEC.md` 🌌
+
+Quando o projeto tem material (repo importado, dir local copiado, mock anexado **ou** um projeto detectado em disco), o **primeiro** plano não salta direto para as specs. Em `src/server/planner-core.ts`:
+
+```ts
+const hasMaterial = srcType !== "new" || mockFiles.length > 0 || !!detectProject(org.id);
+if (!isNewWork && hasMaterial && !wsSettings.source?.analyzed) {
+  await analyzeExistingProject({ orgId, wsId, ada, binary, model });
+  // → marca settings.source.analyzed = true
+}
+```
+
+`analyzeExistingProject()` (`src/server/analyze.ts`) roda uma **passagem de agente real** como Ada (`cwd = workspace`, lê os arquivos literalmente), transmitida ao canal `planner`, que escreve/sobrescreve `specs/SUPER-SPEC.md`. Roda **uma vez por projeto** — protegida por `settings.source.analyzed`. O agente é instruído a ler em ordem: docs → manifests/config → código arquivo-por-arquivo (pulando `node_modules`, `dist`, `build`, `.next`, `.git`, `vendor`), depois escrever estas seções:
+
+`## Overview & purpose` · `## Architecture & layers` · `## Tech stack & dependencies` · `## Directory / module map` · `## Frontend` · `## Backend` · `## Data model & database` · `## Auth & security` · `## Integrations / external services` · `## Business rules & key flows` · `## What is mock/stubbed vs real` · `## Gaps to make it production-real`.
+
+O enquadramento crucial: a Constella **estende** exatamente o sistema existente — deve apontar qual UI/UX, comportamento e identidade visual **preservar** e onde **adicionar** backend/dados/integrações reais; nunca constrói um segundo protótipo separado. O planner do CEO então lê `specs/SUPER-SPEC.md` por completo antes de rascunhar specs e issues, e o `runner` injeta o mesmo enquadramento de "estender o código existente" em cada tarefa (`src/server/runner.ts`). Se o agente esquecer de escrever o arquivo, `analyzeExistingProject()` escreve o texto do resumo final como o super spec, então o entregável sempre existe.
+
+---
+
+## O que `completeOnboarding()` cria 🪐
+
+| Artefato | Onde | Notas |
+|---|---|---|
+| `organization` | DB | `runMode` de `getRunMode()` |
+| `member` | DB | role `owner` |
+| `workspace` | DB | `mission`, `objective`, `stack`; `settings.source` + `settings.github` opcional |
+| Camada de controle `.claude/` | disco | org/workspace/permissions/memory/routing/index/CLAUDE.md/settings.json |
+| Starter do projeto | disco | apenas quando sem material (`scaffoldProjectStarter`) |
+| 10 agentes | DB | Ada `working`, demais `idle`; health `alive` |
+| Overrides de CEO da Ada | DB + `.claude/agents/ada/Agent.md` | `adapter`, `model`, system prompt |
+| `.claude/BRIEF.md` | disco | quando `briefText` é fornecido |
+| arquivos de `mock/` | disco | até 200 arquivos + um `mock/README.md` gerado |
+| `budget` | DB | `monthlyCapUsd: 400` |
+| `plan` | DB | `stage: 4` |
+| Skills nativas + da biblioteca | DB + disco | 6 skills procedurais + toda a biblioteca de skills; `reconcileStackRoleSkills()` vincula por stack/role |
+| 4 plugins nativos | DB | GitHub, Telegram, Vault (habilitados), Web Search (desligado por padrão) |
+| Org ativa na sessão | DB | depois `redirect("/planner")` |
+
+### Os dez agentes
+
+| Handle | Nome | Função | Reporta a | Model | Teto diário (USD) | Tier |
+|---|---|---|---|---|---|---|
+| `ada` | Ada | CEO | — | opus¹ | 15 | critical |
+| `linus` | Linus | CTO | `ada` | sonnet | 40 | critical |
+| `donald` | Donald | Product Owner | `ada` | haiku | 20 | heavy |
+| `margaret` | Margaret | Backend | `linus` | sonnet | 50 | heavy |
+| `grace` | Grace | Frontend | `linus` | sonnet | 45 | heavy |
+| `edsger` | Edsger | QA | `linus` | haiku | 25 | heavy |
+| `werner` | Werner | DevOps | `linus` | haiku | 20 | heavy |
+| `barbara` | Barbara | Docs | `ada` | haiku | 15 | light |
+| `whitfield` | Whitfield | CyberSec | `linus` | opus | 30 | critical |
+| `vannevar` | Vannevar | Knowledge | `ada` | haiku | 10 | light |
+
+¹ O arquivo de persona da Ada usa `sonnet` por padrão, mas a escolha de cérebro-do-CEO do operador (`provider`/`model`) o sobrescreve durante o onboarding. Os tetos diários são limites em USD; o workspace também recebe um orçamento `monthlyCapUsd: 400`.
+
+---
+
+## Passo a passo (operador) ✦
+
+1. **Lançar.** `npx constella` (ou `--onboarding` para forçar o assistente).
+2. **Empresa.** Informe o nome da empresa, missão e objetivo. Os três são obrigatórios.
+3. **Cérebro do CEO.** Escolha um provider + model detectado, ou expanda *Registrar* para adicionar um com um id de model e API key.
+4. **Teste de conexão.** Acompanhe os quatro testes reais passarem. Corrija qualquer estágio falho antes de continuar.
+5. **Stack.** Navegue pelos cards das 17 categorias (ou busque) e escolha o que se aplica; deixe o resto como `None`.
+6. **Brief & source.** Escolha `new`, `github` (cole um PAT → liste repos → escolha um) ou `local` (digite um caminho absoluto → Validar). Opcionalmente cole um brief e/ou anexe uma pasta de mock. Edite o system prompt da Ada.
+7. **Entregar.** Clique no botão de finalizar. O assistente chama `completeOnboarding()` e redireciona para `/planner`.
+8. **Gerar plano.** No Planner, clique em *Generate plan* para disparar o ritual do CEO (e, para projetos importados/mock, a análise de super-spec de uma vez).
+
+---
+
+## Exemplos
+
+**Forçar o assistente pela CLI:**
+
+```bash
+npx constella --onboarding
+# ou o subcomando explícito
+npx constella onboard
+```
+
+**Importar um repo do GitHub no onboarding** — o assistente envia:
+
+```ts
+source = { type: "github", pat: "ghp_…", repoFull: "acme/web-app", branch: "main", login: "acme" }
+```
+
+→ `cloneRepoIntoWorkspace()` clona raso `acme/web-app`, guarda o PAT no vault, define `origin` para a URL limpa, e `preserveReadme` mantém o README do repo.
+
+**Importar um diretório local:**
+
+```ts
+source = { type: "local", path: "C:\\Users\\voce\\projeto" }
+```
+
+→ `validateLocalDir()` confirma, depois `copyLocalDirIntoWorkspace()` faz snapshot de até 4000 arquivos (pulando deps/segredos/binários).
+
+---
+
+## Estados possíveis 🕳️
+
+| Estado | Significado | Onde |
+|---|---|---|
+| `CONSTELLA_FORCE_ONBOARDING=1` | Assistente forçado; limpo no primeiro `completeOnboarding()` | `bin/constella.mjs`, `workspace.ts`, `onboarding.ts` |
+| `source.type = new` | Projeto novo; starter executável montado | `workspace.settings.source` |
+| `source.type = github\|local\|mock` | Material importado; starter suprimido | `workspace.settings.source` |
+| `source.analyzed = false` | O primeiro plano rodará a análise de super-spec | `workspace.settings.source` |
+| `source.analyzed = true` | Análise feita; o planner lê `specs/SUPER-SPEC.md` | definido por `planner-core.ts` |
+| import falhou | Logado no console; org criada mesmo assim; `sourceMeta` recomputado pelo que chegou | `onboarding.ts` |
+| status do agente | Ada `working`, o resto `idle`; health `alive` | tabela `agent` |
+
+---
+
+## Integrações relacionadas 🛰️
+
+- **[Project stacks](../pt/PROJECT_STACKS.md)** — o `stack` escolhido dirige o template do starter e o vínculo de skills.
+- **[Skills](../pt/SKILLS.md)** — `seedLibrarySkills` + `reconcileStackRoleSkills` vinculam cada agente às skills que seu stack e função precisam.
+- **[Plugins](../pt/PLUGINS.md)** — GitHub, Telegram, Vault e Web Search são criados como plugins nativos.
+- **[GitHub](../pt/GITHUB.md)** — import de repo, guarda do PAT no vault e limpeza do `origin`.
+- **[Models](../pt/MODELS.md)** — detecção de provider/model e o teste de conexão.
+- **[Workflow](../pt/WORKFLOW.md)** / **[Goals, specs & issues](../pt/GOALS_SPECS_ISSUES.md)** — o que o primeiro plano produz após o onboarding.
+- **[Test Dev](../pt/TEST_DEV.md)** — sobe o starter executável para uma pré-visualização imediata.
+
+---
+
+## Segurança 🔒
+
+- **Jaula de caminho.** Todo arquivo importado é escrito através de `writeWorkspaceFile()` → `safe()` (checagens léxicas + de symlink; travessia rejeitada; caminhos começando com `..` pulados).
+- **Higiene de token.** O PAT do GitHub é usado apenas transitoriamente na URL de clone, depois o `origin` é resetado para a `https://github.com/<owner>/<repo>.git` limpa; o token é redigido de todas as strings retornadas/logadas e guardado no vault como `github_pat` (AES-256-GCM via o [Vault](../pt/SECURITY.md)).
+- **Pulando segredos no import.** `.env`, `.env.local`, `.env.development`, `.env.production` e `.DS_Store` nunca são copiados (`.env.example`/`.sample` são mantidos); binários e arquivos grandes demais são pulados.
+- **Estado vazio honesto.** Nenhum goal/task/spec/issue falso é semeado — os boards começam realmente vazios; artefatos reais vêm do ritual do CEO e das execuções de agentes.
+- **Permissões ligadas ao modo.** O `runMode` da org/workspace (de `getRunMode()`) determina o modo de permissão de agente que o runner aplica depois (`bypassPermissions` no `start`, `acceptEdits` caso contrário) — veja [Segurança](../pt/SECURITY.md).
+
+---
+
+## Solução de problemas
+
+| Sintoma | Causa provável | Correção |
+|---|---|---|
+| O assistente reabre após finalizar | `CONSTELLA_FORCE_ONBOARDING` ainda definido no ambiente | É limpo no processo no primeiro `completeOnboarding()`; remova a flag `--onboarding` / desfaça a env var ao relançar |
+| *Continuar* desabilitado no passo de teste | Uma checagem real falhou (`env`/`adapter`/`connection`/`model`) | Leia o erro inline; corrija o provider/CLI/API key, depois re-selecione o provider para re-verificar |
+| GitHub *List repos* falha | PAT inválido/expirado ou sem escopo `repo` | Use um token válido; `githubReposForToken()` retorna a string de erro |
+| Local *Validate* falha | Caminho não absoluto, não é um diretório, ou vazio | `scanLocalDir()` exige um caminho absoluto para um diretório com arquivos importáveis |
+| Repo importado mostra o README gerado | `preserveReadme` não disparou (sem `README.md` de topo no import) | Adicione um `README.md` à source; caso contrário o gerado é esperado |
+| Sem `specs/SUPER-SPEC.md` após Generate plan | Projeto sem material, ou `source.analyzed` já era `true` | A análise só roda uma vez, e só com material; cheque `workspace.settings.source` |
+| Starter não criado | O projeto tinha material (`hasMaterial`) | Por design — os agentes estendem o material importado/mock em vez disso |
+
+---
+
+## Links relacionados
+
+- [Instalação](./INSTALLATION.md)
+- [Configuração](./CONFIGURATION.md)
+- [Arquitetura](./ARCHITECTURE.md)
+- [Arquitetura de IA](./AI_ARCHITECTURE.md)
+- [Agentes](./AGENTS.md)
+- [Workflow](./WORKFLOW.md)
+- [Goals, specs & issues](./GOALS_SPECS_ISSUES.md)
+- [Project stacks](./PROJECT_STACKS.md)
+- [Skills](./SKILLS.md)
+- [Plugins](./PLUGINS.md)
+- [Models](./MODELS.md)
+- [GitHub](./GITHUB.md)
+- [Test Dev](./TEST_DEV.md)
+- [Segurança](./SECURITY.md)
+- [Solução de problemas](./TROUBLESHOOTING.md)
+- [FAQ](./FAQ.md)

package/docs/pt/PLUGINS.md

@@ -0,0 +1,290 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/PLUGINS.md) · [✦ Constella](../../README.pt-BR.md)
+
+# 🛰️ Plugins — Baias de Acoplagem para Capacidades
+
+![](../assets/divider-orbit.svg)
+
+Um **plugin** no Constella é uma entrada de catálogo com escopo por workspace que nomeia uma capacidade com a qual a constelação de agentes pode se acoplar: GitHub, Telegram, o Vault, Web Search. A linha do plugin é um registro e um interruptor — o comportamento *real* vive em módulos dedicados, controlados por suas próprias configurações, segredos e variáveis de ambiente.
+
+> Modelo mental: plugins são as **baias de acoplagem** da nave central. A baia diz que uma capacidade *existe* e se a porta dela está aberta (`enabled`). O motor ao qual a baia leva (o motor do GitHub, o relé do Telegram, o Vault) é cabeado em outro lugar.
+
+---
+
+## Quando usar 🌌
+
+- Você quer ver, de relance, quais **integrações nativas** este workspace traz.
+- Você quer ligar ou desligar o interruptor de catálogo de uma capacidade (`togglePlugin`).
+- Você está registrando um placeholder para uma extensão de terceiros que pretende cabear depois (`installPlugin` — **PARCIAL / mock**, veja abaixo).
+- Você precisa distinguir **plugins** de **Skills** (conhecimento do agente) e de **servidores MCP externos** (ferramentas que a CLI `claude` consome). As três camadas são distintas — veja a seção [Plugins vs Skills vs MCP externo](#plugins-vs-skills-vs-mcp-externo-).
+
+Se você procura *habilidades de agente* (conhecimento em nível de prompt que molda como um agente trabalha), isso é **Skills**, não plugins — veja [SKILLS.md](./SKILLS.md).
+
+---
+
+## Como funciona 🪐
+
+Existe exatamente uma tabela e três server actions. Nada além disso — a superfície é deliberadamente minúscula.
+
+### A tabela `plugin`
+
+Fonte: `src/db/schema.ts`.
+
+```ts
+export const plugin = sqliteTable("plugin", {
+  id: text("id").primaryKey(),
+  workspaceId: text("workspace_id").notNull().references(() => workspace.id, { onDelete: "cascade" }),
+  name: text("name").notNull(),
+  description: text("description").notNull().default(""),
+  enabled: integer("enabled", { mode: "boolean" }).notNull().default(false),
+  native: integer("native", { mode: "boolean" }).notNull().default(false),
+});
+```
+
+| Coluna        | Tipo      | Padrão | Significado |
+|---------------|-----------|--------|-------------|
+| `id`          | text PK   | —      | UUID (`randomUUID()`). |
+| `workspaceId` | text FK   | —      | Workspace dono; `ON DELETE CASCADE` — plugins morrem com o workspace. |
+| `name`        | text      | —      | Nome de exibição (`"GitHub"`, `"Telegram"`, …). |
+| `description` | text      | `""`   | Descrição de uma linha exibida no grid. |
+| `enabled`     | boolean   | `false`| Interruptor da porta da baia. `installPlugin` cria linhas novas como `true`; algumas linhas nativas nascem `false`. |
+| `native`      | boolean   | `false`| `true` = criado pelo onboarding; não pode ser removido pela UI. |
+
+Cada linha tem escopo em um único `workspaceId`. Não existe registro global de plugins — cada workspace tem sua própria constelação de baias de acoplagem.
+
+### Server actions
+
+Fonte: `src/server/actions/plugin-actions.ts` (um `togglePlugin` irmão também existe em `src/server/modules.ts`).
+
+| Action | Assinatura | O que faz |
+|--------|-----------|-----------|
+| `togglePlugin` | `(id: string, enabled: boolean)` | Define `plugin.enabled` para uma linha com escopo no workspace atual, e então `revalidatePath("/plugins")`. |
+| `installPlugin` | `(name: string, description = "")` | **PARCIAL / mock.** Insere uma nova linha não-nativa (`enabled: true`, `native: false`) nomeada a partir da URL/nome. **Não** baixa, verifica, isola em sandbox nem cabeia nada. Retorna `{ ok }`. |
+| `removePlugin` | `(id: string)` | Apaga uma linha — mas a cláusula `WHERE` inclui `eq(plugin.native, false)`, então **plugins nativos nunca podem ser removidos**. |
+
+Toda action chama `requireWorkspace()` primeiro, então todas as escritas são isoladas por workspace e autenticadas.
+
+---
+
+## Fluxo principal 🌠
+
+```mermaid
+flowchart TD
+  OB["Onboarding<br/>completeOnboarding()"] -->|"cria 4 linhas nativas"| TBL[("tabela plugin<br/>escopo por workspace")]
+  UI["página /plugins<br/>PluginGrid"] -->|"interruptor toggle"| TOGGLE["togglePlugin(id, enabled)"]
+  UI -->|"Install from URL"| INSTALL["installPlugin(name)<br/>PARCIAL / mock"]
+  UI -->|"Remove (só não-nativo)"| REMOVE["removePlugin(id)"]
+  TOGGLE --> TBL
+  INSTALL --> TBL
+  REMOVE --> TBL
+  TBL -. "apenas catálogo" .-> ENG["Motores reais<br/>github.ts · telegram.ts · vault.ts · cli.ts web research"]
+  ENG -.->|"controlados por SUAS PRÓPRIAS settings/segredos/env"| AGENTS["Constelação de agentes"]
+```
+
+A aresta tracejada é a nuance importante: a tabela `plugin` é uma **camada de catálogo e exibição**. Os motores de capacidade reais são cabeados por seus próprios módulos e são controlados por sua própria configuração — não por `plugin.enabled`. Virar o interruptor do plugin GitHub não, por si só, define um repositório nem armazena um token; isso acontece na integração do GitHub (`src/server/github.ts`). Veja [Plugins nativos](#plugins-nativos-).
+
+---
+
+## Conceitos-chave 🕳️
+
+- **Escopo por workspace.** Todo plugin pertence a um workspace; não há armazenamento de plugins compartilhado/global.
+- **Nativo vs instalado.** Linhas `native: true` são criadas pelo onboarding e são permanentes (a UI esconde o botão de remover; `removePlugin` as ignora). Linhas `native: false` vêm de `installPlugin` e podem ser removidas.
+- **Catálogo, não portão.** `enabled` é um interruptor de registro e um sinal de UI. As integrações nativas impõem a própria ativação por meio de segredos e settings — ex.: GitHub precisa de um `github_pat` no vault ou de token OAuth, Telegram precisa de um `telegram_bot_token` no vault, Web Search é controlado por `CONSTELLA_WEB_RESEARCH` / `settings.agents.webResearch` por workspace.
+- **`installPlugin` é um placeholder.** Ele é honesto sobre ser um mock: o comentário no código diz *"mock — just registers it disabled"* e a descrição cai no padrão `"Installed from URL"`. Nenhum código busca, valida ou executa a URL.
+
+---
+
+## Plugins nativos 🚀
+
+Criados uma vez durante o onboarding. Fonte: `src/server/modules.ts`:
+
+```ts
+const plugins: [string, string, boolean][] = [
+  ["GitHub",     "Commit, push & open PRs from the workspace.", true],
+  ["Telegram",   "Route reports and alerts to a channel.",      true],
+  ["Vault",      "Encrypted secret storage for provider keys.", true],
+  ["Web Search", "Let agents look things up while planning.",   false],
+];
+```
+
+| Plugin | `enabled` inicial | Motor real | Controlado por | Docs |
+|--------|-------------------|------------|----------------|------|
+| **GitHub** | `true` | `src/server/github.ts` (`setRepo`, `refreshGitStatus`, commit/push, `scanForSecrets`) | `github_pat` no vault (preferido) ou `account.accessToken` OAuth; `settings.github.repo` | [GITHUB.md](./GITHUB.md) |
+| **Telegram** | `true` | `src/server/telegram.ts` (`pollTelegram` no cron tick, allowlist, menu de comandos) | `telegram_bot_token` no vault; allowlist de chat/usuário | [TELEGRAM.md](./TELEGRAM.md) |
+| **Vault** | `true` | `src/lib/vault.ts` (AES-256-GCM, tabela `vault`) | `CONSTELLA_VAULT_KEY` | [SECURITY.md](./SECURITY.md) |
+| **Web Search** | `false` | `src/server/adapters/cli.ts` (`--allowedTools WebSearch WebFetch`) | `CONSTELLA_WEB_RESEARCH` (padrão ON) e `settings.agents.webResearch` por workspace | [AGENTS.md](./AGENTS.md) |
+
+> Nota sobre Web Search: a linha do plugin nasce `enabled: false`, mas a capacidade subjacente de web research está **ON por padrão** na camada do agente (`webResearchOn()` retorna true a menos que `CONSTELLA_WEB_RESEARCH=0` ou a setting do workspace desative). Esta é a prova mais clara de que a linha do plugin é uma **entrada de catálogo, não o portão real** — o interruptor de verdade é a variável de ambiente / setting do workspace que o runner empurra via `setWebResearch` antes de cada spawn.
+
+---
+
+## Tabelas 🌌
+
+### `plugin` (já coberta acima)
+
+A única tabela desta funcionalidade. Veja [A tabela `plugin`](#a-tabela-plugin).
+
+### Onde vive o estado real da capacidade (para contraste)
+
+| Capacidade | Tabela / armazenamento de estado | Não fica em `plugin` |
+|------------|----------------------------------|----------------------|
+| Token / repo do GitHub | `vault` (`github_pat`), `workspace.settings.github` | ✓ |
+| Token / offset / allowlist do Telegram | `vault` (`telegram_bot_token`), `workspace.settings.telegram` | ✓ |
+| Chave do Vault | env `CONSTELLA_VAULT_KEY`, tabela `vault` | ✓ |
+| Flag de web research | env `CONSTELLA_WEB_RESEARCH`, `settings.agents.webResearch` | ✓ |
+
+---
+
+## Plugins vs Skills vs MCP externo 🪐
+
+Três camadas que as pessoas costumam confundir. Elas são genuinamente diferentes:
+
+```mermaid
+flowchart LR
+  subgraph "Plugins (este doc)"
+    P[("tabela plugin<br/>catálogo de integrações")]
+  end
+  subgraph "Skills"
+    S[("tabelas skill / agentSkill<br/>.claude/skills/*.md")]
+  end
+  subgraph "MCP externo"
+    M["config ~/.claude da CLI claude<br/>mcpServers — FORA da tabela plugin"]
+  end
+  P -. "nomeia integrações<br/>(GitHub/Telegram/Vault/Web Search)" .-> ENG["Motores reais + segredos"]
+  S -. "molda como os agentes trabalham<br/>(conhecimento em nível de prompt)" .-> AG["Persona do agente"]
+  M -. "adiciona ferramentas que a CLI claude pode chamar" .-> AG
+```
+
+| Camada | O que é | Onde fica armazenada | Cabeada por |
+|--------|---------|----------------------|-------------|
+| **Plugins** | Um catálogo de integrações nativas (este doc) | tabela `plugin` (por workspace) | `plugin-actions.ts`; trabalho real em `github.ts` / `telegram.ts` / `vault.ts` / `cli.ts` |
+| **Skills** | Arquivos de conhecimento que moldam *como* um agente trabalha | tabelas `skill` / `agentSkill`, `.claude/skills/<name>.md` no disco | `src/server/skills-library.ts` — veja [SKILLS.md](./SKILLS.md) |
+| **MCP externo** | Servidores MCP de terceiros que a **CLI `claude` consome como ferramentas** | config `~/.claude` do operador (`mcpServers`) — **não** a tabela `plugin` | A própria CLI `claude` vanilla; veja [MCP.md](./MCP.md) |
+
+Dois esclarecimentos cruciais:
+
+1. **O servidor MCP do próprio Constella é a direção OUTBOUND.** `scripts/mcp-server.mjs` permite que um host *externo* (Claude Desktop, Cursor) dirija o Constella via MCP. Isso está documentado em [MCP.md](./MCP.md) e [PUBLIC_API.md](./PUBLIC_API.md). Não tem nada a ver com a tabela `plugin`.
+2. **Agentes do Constella consumindo servidores MCP externos** acontece pela configuração `~/.claude` da própria CLI `claude` vanilla — novamente **não** pela tabela `plugin`. (E note: agentes da empresa rodam *vanilla* com os hooks do operador desativados, conforme `src/server/adapters/cli.ts`, para que plugins/hooks pessoais do operador, propensos a vazamento, não contaminem as execuções dos agentes.)
+
+---
+
+## Passo a passo 🛰️
+
+### Ligar/desligar um plugin nativo
+
+1. Abra a página **Plugins** (`/plugins`).
+2. Clique no interruptor de uma linha. A UI chama `togglePlugin(p.id, !p.enabled)`.
+3. `plugin.enabled` vira para aquele workspace; a página revalida.
+4. Lembre: para integrações nativas, o portão *operante* é a própria configuração da integração (token / env / setting), não este interruptor.
+
+### "Instalar" um plugin placeholder (PARCIAL)
+
+1. Clique em **Install from URL** na topbar.
+2. O `window.prompt` do navegador pede uma URL ou nome (texto placeholder: `github.com/acme/slack-bridge`).
+3. `installPlugin(url.trim())` insere uma linha não-nativa, `enabled: true`, `description: "Installed from URL"`.
+4. Nada é baixado nem cabeado. A linha é apenas um marcador — **isto é um mock** (veja [Estados possíveis](#estados-possíveis-)).
+
+### Remover um plugin instalado
+
+1. Linhas não-nativas mostram um botão **Remove** (linhas nativas não).
+2. Clique nele → `removePlugin(p.id)`.
+3. O delete é protegido por `eq(plugin.native, false)`, então nem uma chamada forjada consegue apagar uma linha nativa.
+
+---
+
+## Exemplos 🌠
+
+### Toggle programático (server action)
+
+```ts
+import { togglePlugin } from "@/server/actions/plugin-actions";
+
+// Desliga o interruptor de catálogo do GitHub no workspace atual.
+await togglePlugin(githubPluginId, false);
+// NOTA: isto NÃO remove o repo nem o token — veja github.ts.
+```
+
+### Registrar um placeholder (install mock)
+
+```ts
+import { installPlugin } from "@/server/actions/plugin-actions";
+
+const res = await installPlugin("github.com/acme/slack-bridge");
+// res => { ok: true }
+// Uma linha não-nativa aparece em /plugins, enabled, descrição "Installed from URL".
+// Nenhum código de bridge roda — é um marcador de catálogo.
+```
+
+### O que um workspace recém-onboardado contém
+
+| name | description | enabled | native |
+|------|-------------|---------|--------|
+| GitHub | Commit, push & open PRs from the workspace. | true | true |
+| Telegram | Route reports and alerts to a channel. | true | true |
+| Vault | Encrypted secret storage for provider keys. | true | true |
+| Web Search | Let agents look things up while planning. | false | true |
+
+---
+
+## Estados possíveis 🕳️
+
+| Estado | `native` | `enabled` | Removível? | Origem |
+|--------|----------|-----------|------------|--------|
+| Nativo, ligado | `true` | `true` | Não | seed do onboarding |
+| Nativo, desligado | `true` | `false` | Não | seed do onboarding (ex.: Web Search) ou `togglePlugin` |
+| Instalado (mock), ligado | `false` | `true` | Sim | `installPlugin` |
+| Instalado, desligado | `false` | `false` | Sim | `installPlugin` + `togglePlugin` |
+
+**Maturidade da funcionalidade:**
+
+- `togglePlugin` — **real.** Persiste, tem escopo, revalida.
+- `removePlugin` — **real.** Protegido para que nativos sobrevivam.
+- `installPlugin` — **PARCIAL (mock).** Apenas registra uma linha. Não há fetch, verificação, sandbox nem cabeamento em runtime da extensão nomeada. Trate linhas instaladas como marcadores até que isso seja totalmente implementado.
+
+---
+
+## Integrações relacionadas 🪐
+
+Os plugins nativos são rótulos finos sobre subsistemas reais documentados em outro lugar:
+
+- **GitHub** → [GITHUB.md](./GITHUB.md) (commit/push, cabeamento de repo, escaneamento de segredos).
+- **Telegram** → [TELEGRAM.md](./TELEGRAM.md) (bot token, allowlist, menu de comandos, polling).
+- **Vault** → [SECURITY.md](./SECURITY.md) (armazenamento de segredos AES-256-GCM).
+- **Web Search** → [AGENTS.md](./AGENTS.md) (web research do agente via `--allowedTools WebSearch WebFetch`).
+- **MCP (outbound + externo)** → [MCP.md](./MCP.md) e [PUBLIC_API.md](./PUBLIC_API.md).
+
+---
+
+## Segurança 🛰️
+
+- **Isolamento por workspace.** Toda action chama `requireWorkspace()` e restringe seu `WHERE` por `workspaceId`, então um workspace não pode ler nem mutar plugins de outro.
+- **Imutabilidade de nativos.** A cláusula `eq(plugin.native, false)` em `removePlugin` impede a remoção de integrações nativas mesmo via requisição forjada.
+- **Sem execução de código a partir de `installPlugin`.** Como o caminho de install é um mock, *atualmente não há* superfície de ataque de download/execução de código por ele. Quando for construído, a URL nomeada precisará ser buscada, escaneada e isolada em sandbox — não presuma que uma linha instalada é segura para executar hoje.
+- **Segredos nunca vivem aqui.** Tokens e chaves ficam no `vault` criptografado (`CONSTELLA_VAULT_KEY`) e em `workspace.settings`, nunca na tabela `plugin`. A linha de catálogo não carrega material secreto.
+- **Agentes rodam vanilla.** Plugins/hooks do `~/.claude` do operador são desativados nas execuções dos agentes da empresa (`src/server/adapters/cli.ts`), então os plugins pessoais do Claude do operador não podem alterar silenciosamente o comportamento do agente. Este é um conceito de "plugin" totalmente diferente — plugins da CLI do operador, não linhas de plugin do Constella.
+
+---
+
+## Solução de problemas 🕳️
+
+| Sintoma | Causa provável | Correção |
+|---------|----------------|----------|
+| Ligar o GitHub não fez nada | `enabled` é uma flag de catálogo, não o portão | Configure o repo e o token em [GITHUB.md](./GITHUB.md). |
+| Web Search mostra `enabled: false` mas os agentes ainda pesquisam | Web research está ON por padrão na camada do agente | Desative via `CONSTELLA_WEB_RESEARCH=0` ou `settings.agents.webResearch=false` — veja [AGENTS.md](./AGENTS.md). |
+| Plugin instalado "não faz nada" | `installPlugin` é um mock (apenas registra uma linha) | Esperado — funcionalidade PARCIAL; a extensão nomeada não é cabeada. |
+| Botão Remove sumiu em uma linha | A linha é `native: true` | Plugins nativos são permanentes por design; use o toggle. |
+| Página Plugins vazia | Sem linhas para este workspace (raro; onboarding cria 4) | Reconfira o workspace; linhas nativas são criadas por `completeOnboarding`. |
+| Quero que agentes usem uma ferramenta MCP externa | Isso é configurado na CLI `claude` em `~/.claude`, não aqui | Veja [MCP.md](./MCP.md). |
+
+---
+
+## Links relacionados 🌌
+
+- [SKILLS.md](./SKILLS.md) — camada de conhecimento do agente (não é o mesmo que plugins)
+- [MCP.md](./MCP.md) — servidor MCP do Constella + consumo de MCP externo
+- [GITHUB.md](./GITHUB.md) — o motor da integração com o GitHub
+- [TELEGRAM.md](./TELEGRAM.md) — o motor do relé do Telegram
+- [SECURITY.md](./SECURITY.md) — o Vault e o tratamento de segredos
+- [AGENTS.md](./AGENTS.md) — agentes e web research
+- [PUBLIC_API.md](./PUBLIC_API.md) — superfície REST v1 sobre a qual o MCP mapeia
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — onde os plugins ficam no control plane
+- [CONFIGURATION.md](./CONFIGURATION.md) — variáveis de ambiente e settings do workspace