constellai 0.3.0

package/docs/pt/PUBLIC_API.md

@@ -0,0 +1,315 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/PUBLIC_API.md) · [✦ Constella](../../README.pt-BR.md)
+
+# 🛰️ API Pública — pilotando a nave a partir da órbita
+
+![](../assets/divider-orbit.svg)
+
+Uma superfície REST pequena e honesta (`/api/v1`) que permite a sistemas externos — scripts, jobs de CI, um celular ou um servidor MCP — ler o estado do projeto e guiar a constelação sem uma sessão de navegador. Uma única credencial bearer (um **Personal Access Token**), um único dispatcher, um único envelope de erro.
+
+---
+
+## Quando usar ✦
+
+Use a API Pública quando quiser dirigir o Constella **de fora** da UI web:
+
+- Um **pipeline de CI** que aprova um plano ou liga a execução 24/7 após um build verde.
+- Um **script de celular / shell** que consulta a revisão matinal e as contagens.
+- Um **host MCP** (Claude Desktop, Cursor, …) — o servidor MCP incluído (veja [MCP.md](./MCP.md)) é um wrapper fino, de saída, exatamente sobre estas rotas v1.
+- Um **painel de status** que lista goals, issues, tasks ou specs.
+- Perguntar à **Base de Conhecimento** de forma programática.
+
+Se, em vez disso, você quiser que um host de IA externo *consuma* o Constella como ferramentas, você não chama estas rotas à mão — você aponta o servidor MCP para elas. As duas coisas são a mesma superfície vista de duas distâncias.
+
+---
+
+## Como funciona 🌌
+
+A API inteira é **uma única rota catch-all dinâmica**: `src/app/api/v1/[[...path]]/route.ts`. Ela exporta apenas `GET` e `POST`; ambos afunilam para uma única função `dispatch()`, de modo que **autenticação, escopo, rate-limit e o envelope de resposta vivem em exatamente um lugar**.
+
+As mutações **não** reinventam lógica. Elas reutilizam os mesmos cores sem-sessão que o controle remoto via Telegram usa:
+
+- `approvePlanFor`, `setAuto247For`, `requestPlanChangesFor`, `reviewSummaryFor` → `src/server/plan-ops.ts`
+- `cancelGoalFor`, `archiveGoalFor` → `src/server/work-ops.ts`
+- `startNewWorkFor` → `src/server/planner-core.ts`
+- `kbAnswer` → `src/server/kb.ts`
+- Leituras estruturadas (`apiStatus`, `apiGoals`, `apiIssues`, `apiTasks`, `apiSpecs`) → `src/server/api/service.ts`
+
+Não há **sessão nem cookie** nas rotas v1. A única credencial é o PAT. A rota também define `runtime = "nodejs"` e `dynamic = "force-dynamic"` (ela acessa o banco a cada requisição).
+
+### Envelope de resposta
+
+Toda resposta é JSON com um formato uniforme:
+
+| Campo   | Tipo      | Significado                              |
+| ------- | --------- | ---------------------------------------- |
+| `ok`    | `boolean` | `true` em sucesso, `false` em erro       |
+| `data`  | qualquer  | presente quando `ok: true`               |
+| `error` | `string`  | presente quando `ok: false`              |
+
+```jsonc
+// sucesso
+{ "ok": true, "data": { /* … */ } }
+// erro
+{ "ok": false, "error": "this token has read scope; a write-scope token is required" }
+```
+
+---
+
+## Autenticação 🔑 — Personal Access Tokens (`cn_…`)
+
+Um PAT é gerado na UI web (`createPAT` em `src/server/actions/profile-actions.ts`) e armazenado **com hash**, nunca em texto puro.
+
+```ts
+// profile-actions.ts (geração)
+const raw = "cn_" + randomBytes(24).toString("base64url");
+const tokenHash = createHash("sha256").update(raw).digest("hex");
+// armazenado: { tokenHash, prefix: raw.slice(0,7), scope, name, userId }
+```
+
+Propriedades principais:
+
+- **Formato** — `cn_` seguido de uma string base64 URL-safe (24 bytes aleatórios). A rota aceita `cn_[A-Za-z0-9_-]{8,}`.
+- **Exibido uma vez** — o valor bruto `cn_…` é retornado por `createPAT` e exibido uma única vez. Apenas seu **hash SHA-256** (`tokenHash`) e um `prefix` de exibição de 7 caracteres (ex.: `cn_a1b2`) são persistidos na tabela `personalAccessToken`. Se você o perder, gere um novo.
+- **Nunca registrado em log** — `authenticatePAT` apenas calcula o hash do token recebido e compara o hash; o token em texto puro nunca chega a uma linha de log.
+- **Escopo** — `read` (padrão) ou `write`. Leituras são abertas a qualquer token válido; mutações exigem `write`.
+- **Carimbo de uso** — toda chamada autenticada atualiza, em best-effort, o `lastUsedAt` (uma falha de escrita nunca bloqueia a autenticação).
+
+### O handshake (`authenticatePAT`)
+
+`src/server/api/pat-auth.ts` roda a cada requisição:
+
+1. Faz parse de `Authorization: Bearer cn_…`. Mal-formado → **401** `missing or malformed bearer token`.
+2. Calcula o SHA-256 do token e o busca por `tokenHash`. Sem correspondência → **401** `invalid token`.
+3. Resolve a org do dono do token via `getActiveOrg(userId, X-Constella-Org)`. Isto é um **join de associação** — um valor de `X-Constella-Org` ao qual o usuário não pertence é *ignorado* (cai de volta na primeira org dele), então um token nunca pode ser apontado para um tenant alheio. Sem org → **404**.
+4. Org arquivada → **409** `organization is archived`.
+5. Resolve o workspace da org via `getWorkspace`. Nenhum → **404**.
+
+Em caso de sucesso, a requisição carrega `{ userId, tokenId, scope, org, workspace }`.
+
+### `X-Constella-Org`
+
+Header opcional. Se um usuário pertence a múltiplas organizações, defina `X-Constella-Org: <orgId>` para escolher sobre qual delas o token atua. Omitido (ou inválido) → a **primeira** org do usuário. A escolha é sempre validada através do join de associação.
+
+---
+
+## Limite de taxa 🪐
+
+Uma **janela deslizante de 60 segundos**, em best-effort, indexada por `tokenId`, vive em memória no único processo de servidor Next:
+
+```ts
+const RL_MAX = 120; // requisições por token por 60s
+```
+
+Ultrapassá-lo retorna **429** `rate limit exceeded (120 req/min)`. Como o contador é em memória, um reinício do servidor o zera — aceitável para o design de operador único. Não há limite por IP nem header `Retry-After`.
+
+---
+
+## Fluxo de autorização 🌠
+
+```mermaid
+flowchart TD
+  A["Requisição → /api/v1/…"] --> B{"Bearer cn_… presente e bem-formado?"}
+  B -- não --> E401["401 ausente/mal-formado"]
+  B -- sim --> C["sha256(token) → casar tokenHash"]
+  C -- sem match --> E401b["401 invalid token"]
+  C -- match --> D["getActiveOrg(userId, X-Constella-Org)\njoin de associação"]
+  D -- nenhuma --> E404["404 no organization"]
+  D -- arquivada --> E409["409 archived"]
+  D -- ok --> R{"rate limit\n(120/min)?"}
+  R -- excedido --> E429["429 rate limit"]
+  R -- ok --> M{"método + rota"}
+  M -- "GET" --> RD["serviços de leitura"]
+  M -- "POST (write?)" --> W{"scope == write?"}
+  W -- não --> E403["403 write scope required"]
+  W -- sim --> MUT["plan-ops / work-ops / planner-core"]
+```
+
+---
+
+## Endpoints 📡
+
+A Base URL é o host do seu Constella, ex.: `http://localhost:3000/api/v1`. Todas as rotas exigem o header `Authorization`; rotas de escrita exigem adicionalmente um token de escopo `write`.
+
+### GET (escopo de leitura basta)
+
+| Método | Caminho             | Retorna                                                           |
+| ------ | ------------------- | ---------------------------------------------------------------- |
+| GET    | `/api/v1` ou `/me`  | `{ user, org{id,name}, workspace{id,name,slug}, scope }`         |
+| GET    | `/api/v1/status`    | contagens: goals, issues (`byCol`), tasks (`byCol`), resumo do plano |
+| GET    | `/api/v1/review`    | `{ text }` — o resumo de revisão estilo mobile (`reviewSummaryFor`) |
+| GET    | `/api/v1/goals`     | `[{ id, title, status, progress }]`                              |
+| GET    | `/api/v1/issues`    | `[{ id, key, title, col, prio, points, moscow, approved }]`      |
+| GET    | `/api/v1/tasks`     | `[{ id, key, title, col, prio }]`                                |
+| GET    | `/api/v1/specs`     | `[{ id, key, title, status, approved }]`                         |
+| GET    | `/api/v1/kb?q=…`    | `{ text, sources }` — resposta da Base de Conhecimento (`kbAnswer`) |
+
+### POST (escopo de escrita, exceto `kb`)
+
+| Método | Caminho                       | Corpo                      | Efeito                                              |
+| ------ | ----------------------------- | -------------------------- | --------------------------------------------------- |
+| POST   | `/api/v1/plan/approve`        | —                          | Aprova o plano, enfileira tasks (`approvePlanFor`)  |
+| POST   | `/api/v1/plan/reject`         | `{ reason? }`              | Devolve o plano com notas (`requestPlanChangesFor`) |
+| POST   | `/api/v1/execution`           | `{ on?: boolean }`         | Liga/desliga execução autônoma 24/7 (`setAuto247For`) — padrão `on:true` |
+| POST   | `/api/v1/work`                | `{ brief, title? }`        | Inicia uma nova unidade de trabalho (`startNewWorkFor`) |
+| POST   | `/api/v1/goals/{id}/cancel`   | —                          | Cancela um goal (`cancelGoalFor`)                   |
+| POST   | `/api/v1/goals/{id}/archive`  | —                          | Arquiva um goal (`archiveGoalFor`)                  |
+| POST   | `/api/v1/kb`                  | `{ q }`                    | Resposta da Base de Conhecimento — **quase-leitura, não exige escopo write** |
+
+> `POST /api/v1/kb` é a exceção deliberada: não muta nada, então não exige um token `write`. Todo outro POST exige.
+
+---
+
+## Exemplos 🌠
+
+Exporte seu token uma vez:
+
+```bash
+export CN_TOKEN="cn_xxxxxxxxxxxxxxxxxxxxxxxx"
+export CN_BASE="http://localhost:3000/api/v1"
+```
+
+### Quem sou eu
+
+```bash
+curl -s "$CN_BASE/me" -H "Authorization: Bearer $CN_TOKEN"
+# { "ok": true, "data": { "user": "…", "org": { "id": "…", "name": "Acme" },
+#   "workspace": { "id": "…", "name": "web", "slug": "web" }, "scope": "write" } }
+```
+
+### Status do projeto e revisão matinal
+
+```bash
+curl -s "$CN_BASE/status" -H "Authorization: Bearer $CN_TOKEN"
+curl -s "$CN_BASE/review" -H "Authorization: Bearer $CN_TOKEN"
+```
+
+### Listar boards
+
+```bash
+curl -s "$CN_BASE/goals"  -H "Authorization: Bearer $CN_TOKEN"
+curl -s "$CN_BASE/issues" -H "Authorization: Bearer $CN_TOKEN"
+curl -s "$CN_BASE/tasks"  -H "Authorization: Bearer $CN_TOKEN"
+curl -s "$CN_BASE/specs"  -H "Authorization: Bearer $CN_TOKEN"
+```
+
+### Perguntar à Base de Conhecimento
+
+```bash
+# Forma GET (query string)
+curl -s "$CN_BASE/kb?q=como%20tratamos%20auth" -H "Authorization: Bearer $CN_TOKEN"
+
+# Forma POST (corpo JSON) — também não exige escopo write
+curl -s -X POST "$CN_BASE/kb" \
+  -H "Authorization: Bearer $CN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"q":"como tratamos auth"}'
+```
+
+### Aprovar / rejeitar um plano (escopo write)
+
+```bash
+curl -s -X POST "$CN_BASE/plan/approve" -H "Authorization: Bearer $CN_TOKEN"
+
+curl -s -X POST "$CN_BASE/plan/reject" \
+  -H "Authorization: Bearer $CN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"reason":"dividir a issue de auth em duas"}'
+```
+
+### Alternar execução 24/7 (escopo write)
+
+```bash
+curl -s -X POST "$CN_BASE/execution" \
+  -H "Authorization: Bearer $CN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"on":true}'
+# { "ok": true, "data": { "auto247": true } }
+```
+
+### Lançar novo trabalho (escopo write) 🚀
+
+```bash
+curl -s -X POST "$CN_BASE/work" \
+  -H "Authorization: Bearer $CN_TOKEN" -H "Content-Type: application/json" \
+  -d '{"title":"Reset de senha","brief":"Adicionar um fluxo de esqueci-a-senha com tokens por e-mail"}'
+```
+
+### Cancelar / arquivar um goal (escopo write) 🕳️
+
+```bash
+curl -s -X POST "$CN_BASE/goals/$GOAL_ID/cancel"  -H "Authorization: Bearer $CN_TOKEN"
+curl -s -X POST "$CN_BASE/goals/$GOAL_ID/archive" -H "Authorization: Bearer $CN_TOKEN"
+```
+
+### Apontar um token para uma org específica
+
+```bash
+curl -s "$CN_BASE/status" \
+  -H "Authorization: Bearer $CN_TOKEN" \
+  -H "X-Constella-Org: $ORG_ID"
+```
+
+---
+
+## Estados possíveis 🛰️
+
+| HTTP | `error`                                                   | Causa                                                      |
+| ---- | -------------------------------------------------------- | ---------------------------------------------------------- |
+| 200  | —                                                        | sucesso (`ok: true`)                                       |
+| 400  | `missing ?q=` / `missing body.q`                         | consulta de KB sem pergunta                                |
+| 400  | `could not start work` (ou mensagem do core)            | `POST /work` com `brief` vazio                             |
+| 401  | `missing or malformed bearer token`                      | sem `Authorization`, ou não é `Bearer cn_…`               |
+| 401  | `invalid token`                                          | hash do token não está em `personalAccessToken`           |
+| 403  | `this token has read scope; a write-scope token is required` | rota de mutação com um token `read`                    |
+| 404  | `no organization for this token's user`                  | dono do token não tem org                                 |
+| 404  | `no workspace for the organization`                      | org não tem workspace                                     |
+| 404  | `unknown GET /…` / `unknown POST /…` / `goal not found`  | rota inválida ou goal inexistente                        |
+| 409  | `organization is archived`                               | a org por trás do token está arquivada                    |
+| 429  | `rate limit exceeded (120 req/min)`                      | mais de 120 requisições/token em 60s                      |
+| 500  | (mensagem de erro)                                       | exceção inesperada (capturada na borda `GET`/`POST`)      |
+
+---
+
+## Integrações relacionadas 🌌
+
+- **[MCP.md](./MCP.md)** — o servidor MCP de saída (`scripts/mcp-server.mjs`) é um wrapper stdio sobre exatamente estas rotas; um host de IA externo dirige o Constella através dele usando o mesmo PAT `cn_…`.
+- **[TELEGRAM.md](./TELEGRAM.md)** — o controle remoto via Telegram compartilha os mesmíssimos cores sem-sessão (`plan-ops.ts`, `work-ops.ts`, `planner-core.ts`).
+- **[CHAT_COMMANDS.md](./CHAT_COMMANDS.md)** — os comandos com barra mapeiam para as mesmas ações que você alcança via HTTP aqui.
+- **[WORKFLOW.md](./WORKFLOW.md)** / **[GOALS_SPECS_ISSUES.md](./GOALS_SPECS_ISSUES.md)** — o ciclo de vida Goal → Spec → Issue → Plan sobre o qual `status`, `plan/approve` e `work` operam.
+
+---
+
+## Segurança 🕳️
+
+- **Hash em repouso** — apenas o `tokenHash` SHA-256 e um `prefix` de exibição de 7 caracteres são armazenados; o `cn_…` bruto é exibido uma vez e nunca persistido ou registrado.
+- **Isolamento de tenant** — `getActiveOrg` faz join através de `member`, então um token só pode atuar em orgs às quais seu dono pertence; um `X-Constella-Org` forjado é silenciosamente ignorado.
+- **Portão de escopo** — toda mutação chama `needWrite()` e retorna **403** para tokens `read`. O único POST que pula isso é `/kb` (uma leitura pura).
+- **Revogação** — `revokePAT` (UI de perfil) apaga a linha; a próxima requisição com aquele token recebe **401 invalid token**.
+- **Sem vazamento de sessão** — as rotas v1 nunca leem cookies ou sessões; uma sessão de navegador roubada não pode ser reproduzida aqui, e um PAT roubado não alcança a UI web autenticada.
+- **Transporte** — não há TLS embutido. Sob os modos `start`/`auth`, o servidor escuta em loopback (`127.0.0.1`); para `vps`/`portable` (bind `0.0.0.0`), coloque-o atrás de um proxy reverso TLS / tailnet e trate o PAT como uma senha. Veja [SECURITY.md](./SECURITY.md), [VPS_MODE.md](./VPS_MODE.md).
+
+---
+
+## Solução de problemas 🛠️
+
+| Sintoma                                   | Causa provável / correção                                                          |
+| ----------------------------------------- | ---------------------------------------------------------------------------------- |
+| `401 missing or malformed bearer token`   | O header deve ser exatamente `Authorization: Bearer cn_…`; verifique espaço/aspas extras. |
+| `401 invalid token`                       | Token revogado ou digitado errado. Gere um novo em **Profile → Personal Access Tokens**; é exibido uma vez. |
+| `403 … write-scope token is required`     | Você usou um token `read` numa mutação. Crie um token de escopo `write`.           |
+| `404 no organization` / `no workspace`    | O usuário do token ainda não tem org/workspace — conclua o [ONBOARDING.md](./ONBOARDING.md). |
+| `409 organization is archived`            | Desarquive a org, ou use um token cuja org esteja ativa.                           |
+| `429 rate limit exceeded`                 | Você cruzou 120 req/min para aquele token; reduza o ritmo (janela deslizante de 60s). |
+| Dados da org errada retornados            | Passe `X-Constella-Org: <orgId>`; um valor inválido cai de volta na primeira org.  |
+| `400 missing ?q=` / `missing body.q`      | A KB precisa de uma pergunta não vazia — `?q=…` no GET, `{"q":"…"}` no POST.       |
+| Conexão recusada de outra máquina         | Nos modos `start`/`auth` o servidor é apenas loopback; use `vps`/`portable` ou um proxy. |
+
+---
+
+## Links relacionados
+
+- [MCP.md](./MCP.md) — servidor MCP de saída sobre estas rotas
+- [TELEGRAM.md](./TELEGRAM.md) — controle remoto via Telegram (cores compartilhados)
+- [CHAT_COMMANDS.md](./CHAT_COMMANDS.md) — comandos com barra
+- [WORKFLOW.md](./WORKFLOW.md) — o ciclo de vida do trabalho
+- [GOALS_SPECS_ISSUES.md](./GOALS_SPECS_ISSUES.md) — goals, specs, issues
+- [SECURITY.md](./SECURITY.md) — vault, segredos, autenticação
+- [VPS_MODE.md](./VPS_MODE.md) · [PORTABLE_MODE.md](./PORTABLE_MODE.md) — binds remoto / portátil
+- [CONFIGURATION.md](./CONFIGURATION.md) — variáveis de ambiente e portas

package/docs/pt/PUBLISHING.md

@@ -0,0 +1,343 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/PUBLISHING.md) · [✦ Constella](../../README.pt-BR.md)
+
+# 🚀 Publicação e Distribuição — lançando a nave do estaleiro
+
+![](../assets/divider-orbit.svg)
+
+Publicar é como a nave-mãe deixa o estaleiro. Dois lançamentos acontecem, em duas direções: o **tarball do npm** leva o *runtime compilado* aos usuários finais, e o **espelho público no Git** leva a *árvore do produto* (docs, launcher, migrações — sem código-fonte) para `github.com/gabriel7silva/constella`. A árvore privada de desenvolvimento permanece em casa, em órbita, no remoto `dev`. ✦
+
+> **Resumo** — Usuários finais recebem um runtime compilado e minificado, **nunca o `src/`**. O `npm publish` envia o `.next` pré-compilado; `scripts/publish-public.mjs --push` espelha uma árvore limpa, escaneada contra segredos e sem código-fonte para o repositório Git público. Ambos os canais se recusam a publicar segredos.
+
+---
+
+## Quando usar
+
+| Você quer… | Use |
+| --- | --- |
+| Publicar uma nova versão no npm (usuários do `npx constellai`) | `npm publish` (executa `prepublishOnly` → `prepack`) |
+| Espelhar a árvore do produto no repositório Git público | `node scripts/publish-public.mjs --push` |
+| Simular o espelho público (apenas escanear, sem push) | `node scripts/publish-public.mjs` |
+| Verificar o tarball localmente antes de publicar | `npm pack` (executa `prepack` → `trim-next`) |
+| Remover artefatos de dev de um build antes de empacotar | automático no `prepack`; manual: `node scripts/trim-next.mjs` |
+| Remover arquivos de rascunho/mortos da raiz do repo | `npm run clean` (`scripts/clean-repo.mjs`) |
+
+Esta página cobre os **dois canais de distribuição** e os portões que os protegem. Para o caminho de atualização do usuário, veja [UPDATE](./UPDATE.md). Para a maquinaria de varredura de segredos, veja [SECURITY](./SECURITY.md). Para fazer deploy de um *produto construído* (e não da própria Constella), veja [DEPLOY](./DEPLOY.md) e [PREPARE_DEPLOY](./PREPARE_DEPLOY.md).
+
+---
+
+## Como funciona 🌌
+
+A Constella distribui por **dois canais** que compartilham um princípio: *publicar o produto, nunca o código-fonte.*
+
+```
+            ┌─────────────────── árvore de dev (privada) ────────────────────┐
+            │  src/   e2e/   tests   playwright.config.ts   drizzle/  bin/    │
+            │  .next/ (compilado)   docs/   skills/   scripts/   *.config.mjs │
+            └────────────────────────────────────────────────────────────────┘
+                         │                                   │
+        npm publish      │                                   │   publish-public.mjs --push
+   (prepublishOnly →     │                                   │   (árvore limpa + varredura)
+        prepack)         ▼                                   ▼
+   ┌─────────────────────────────┐               ┌────────────────────────────────┐
+   │ registro npm: constellai    │               │ Git público: gabriel7silva/     │
+   │ tarball do runtime COMPILADO │               │ constella (espelho force-push)  │
+   │ .next + bin + drizzle + docs │               │ docs + bin + drizzle + skills   │
+   │ SEM src/                     │               │ SEM src/, SEM .next, SEM segredo│
+   └─────────────────────────────┘               └────────────────────────────────┘
+```
+
+1. **Canal npm** — `npm publish` envia o runtime como um tarball. A allowlist `files` no `package.json` seleciona exatamente o que viaja; `prepublishOnly` valida a árvore; `prepack` (`trim-next.mjs`) remove os artefatos de dev do `.next`, de modo que os usuários finais recebam apenas o runtime de produção.
+2. **Canal Git** — `scripts/publish-public.mjs` constrói uma árvore filtrada em um índice git *temporário* (HEAD menos `src/`/testes, mais as migrações geradas em `drizzle/`), escaneia contra segredos exatamente esse conjunto e faz **force-push** dele como um commit-raiz novo para o remoto `public`. O `.next` compilado **não** viaja pelo git — ele chega aos usuários pelo tarball do npm.
+3. **Repositório duplo** — o remoto privado `dev` (`constella-Dev`) guarda todo o histórico do código-fonte; o remoto `public` (`constella`) é um espelho limpo e descartável, não um histórico compartilhado.
+
+> Nenhum dos canais carrega o `src/`. O esquema chega aos usuários como SQL gerado em `drizzle/`, aplicado por `drizzle-kit migrate`. Veja [INSTALLATION](./INSTALLATION.md).
+
+---
+
+## Fluxo principal 🌠
+
+```mermaid
+flowchart TD
+  subgraph DEV["Árvore de dev (este repo, remoto dev)"]
+    SRC["src/ + e2e/ + tests + configs"]
+    BUILT[".next (next build --webpack)"]
+    DRZ["drizzle/ (migrações SQL geradas)"]
+    SHIP["bin/ scripts/ skills/ docs/ *.config.mjs"]
+  end
+
+  SRC --> NPMHOOK
+  BUILT --> NPMHOOK
+  DRZ --> NPMHOOK
+  SHIP --> NPMHOOK
+
+  subgraph NPM["Canal npm — npm publish"]
+    NPMHOOK["prepublishOnly: drizzle-kit generate + validate (typecheck + parity + build)"]
+    PREPACK["prepack: trim-next.mjs remove .next/dev,cache,trace"]
+    TAR["allowlist files → tarball"]
+    NPMHOOK --> PREPACK --> TAR
+  end
+
+  SRC --> PUBHOOK
+  DRZ --> PUBHOOK
+  SHIP --> PUBHOOK
+
+  subgraph GIT["Canal Git — publish-public.mjs"]
+    PUBHOOK["ls-files menos EXCLUDE + force-add drizzle/"]
+    SCAN["varredura de segredos no conjunto exato"]
+    GATE{"findings == 0 ?"}
+    TREE["índice git temp → write-tree → commit-tree"]
+    PUSH["git push -f public commit:refs/heads/main"]
+    PUBHOOK --> SCAN --> GATE
+    GATE -- "não" --> ABORT["exit 1 — recusa"]
+    GATE -- "sim (--push)" --> TREE --> PUSH
+  end
+
+  TAR --> REG["registro npm: constellai"]
+  PUSH --> PUB["espelho Git público"]
+```
+
+---
+
+## Conceitos-chave 🪐
+
+### A allowlist `files` (`package.json`)
+
+O npm empacota **somente** o que `files` lista (mais alguns arquivos sempre incluídos). Essa é a única fonte de verdade para "o que um usuário final recebe":
+
+```json
+"files": [
+  ".next", "bin", "scripts", "skills", "docs",
+  "drizzle", "next.config.mjs", "drizzle.config.mjs",
+  "README.md", "LICENSE", "CHANGELOG.md"
+]
+```
+
+O `src/` está **ausente por design**. O comentário do package torna a intenção explícita:
+
+> *"Ships the COMPILED build (`.next`) + generated migrations (`drizzle`) + the launcher — NOT `src/`. End users get a compiled, minified runtime, never the source. `next.config` is `.mjs` so `next start` needs no TypeScript at runtime (devDeps aren't installed for end users)."*
+
+### `prepack` → `trim-next.mjs`
+
+O `prepack` roda em `npm pack` e `npm publish`, logo antes de o tarball ser construído. `scripts/trim-next.mjs` apaga as partes do `.next` que o `next start` **não** precisa:
+
+| Removido de `.next/` | Por quê |
+| --- | --- |
+| `dev` | Saída do dev-server do Turbopack + um log de desenvolvimento de vários GB; regenerado por `next dev`. |
+| `cache` | Cache de build; regenerado por `next build`. |
+| `trace` | Arquivos de trace de build; desnecessários em runtime. |
+
+Como a allowlist `files` reinclui o diretório `.next` **inteiro** (sobrepondo regras `.npmignore` aninhadas), apagar isso *em disco antes de empacotar* é a maneira confiável de manter o tarball pequeno e limpo. Se o `.next/` não existir, o script sai com código 0 e um aviso de skip.
+
+### `prepublishOnly` → `validate`
+
+O `prepublishOnly` roda **apenas** no `npm publish` (não no `npm pack` simples). É o portão de publicação:
+
+```json
+"prepublishOnly": "drizzle-kit generate --config drizzle.config.mjs && npm run validate"
+```
+
+…onde `validate` é:
+
+```json
+"validate": "npm run typecheck && npm run parity && npm run build"
+```
+
+| Etapa | Comando | Garante |
+| --- | --- | --- |
+| Gerar migrações | `drizzle-kit generate` | `drizzle/` reflete o `schema.ts` atual antes de viajar. |
+| Typecheck | `tsc --noEmit` | O código-fonte compila sem erros. |
+| Paridade i18n | `node scripts/i18n-parity.mjs` | Chaves dos dicionários EN ↔ PT batem (veja [CONFIGURATION](./CONFIGURATION.md)). |
+| Build | `next build --webpack` | Um `.next` novo e atual existe para ser empacotado. |
+
+### `publish-public.mjs` — o espelho Git limpo
+
+`scripts/publish-public.mjs` produz o espelho Git **sem código-fonte**. Ele nunca roda automaticamente; você o invoca deliberadamente.
+
+A constante que define todo o propósito:
+
+```js
+const EXCLUDE = ["src", "playwright.config.ts", "e2e", "tests"];
+```
+
+Fluxo dentro do script:
+
+1. **Garante que as migrações existem** — se `drizzle/` estiver ausente ou sem `.sql`, roda `npx drizzle-kit generate`. O repositório público envia essas migrações para que o usuário final construa um DB novo via `drizzle-kit migrate`.
+2. **Calcula o conjunto de publicação** — `git ls-files` (arquivos rastreados) menos `EXCLUDE`, **mais** os arquivos `drizzle/` em disco (ignorados pelo git no repo de dev, force-add na árvore pública). Deduplicado em `publishFiles`.
+3. **Escaneia contra segredos exatamente esse conjunto** — nomes de arquivos sensíveis + padrões inline de alta confiança (espelho de `src/server/git-scan.ts`). Qualquer achado → aborta.
+4. **Cinto e suspensório** — verifica explicitamente que nenhum arquivo `src/` escapou; se escapou, anexa um achado e aborta.
+5. **Simulação por padrão** — sem `--push`, imprime a contagem de arquivos e sai com 0. Com `--push`, continua.
+6. **Constrói a árvore filtrada** em um índice git temporário (`GIT_INDEX_FILE`): `git read-tree HEAD` → `git rm -r --cached` em cada caminho de `EXCLUDE` → `git add -f drizzle` → `git write-tree` → `git commit-tree` (um commit-raiz novo, sem histórico compartilhado).
+7. **Force-push** do objeto de commit para uma ref totalmente qualificada: `git push -f public <commit>:refs/heads/main`.
+
+### Regras da varredura de segredos (o portão de publicação)
+
+O `publish-public.mjs` carrega um espelho inline do scanner do repositório. Ele bloqueia em **qualquer** achado:
+
+| Categoria | Exemplos / intenção do padrão |
+| --- | --- |
+| **Arquivos** sensíveis | `.env` (e `.env.*` exceto `.example`/`.sample`/`.template`/`.dist`), `id_rsa`/`id_dsa`, `*.pem`/`*.key`/`*.p12`/`*.pfx`/`*.keystore`/`*.jks`/`*.ppk`/`*.asc`, `credentials*.json`, `service-account*.json`, `*.sql`/`*.dump`/`*.bak`/`*.sqlite*`/`*.db`, `npm-debug.log`, `*.local` |
+| Exceções permitidas | `.env.example`/`.sample`/`.template`/`.dist`, `.env-example`; e `drizzle/*.sql` (migrações DDL, não dumps de DB) |
+| Segredos inline | Chave AWS (`AKIA…`), token do GitHub (`gh[posru]_…`), PAT fine-grained do GitHub (`github_pat_…`), chave OpenAI/Anthropic (`sk-…`), chave Google API (`AIza…`), token Slack (`xox[baprs]-…`), bloco de chave privada (`-----BEGIN … PRIVATE KEY-----`), JWT (`eyJ…`), URL de DB com credenciais não-placeholder, token de bot do Telegram (`\d{6,}:…`) |
+| Vazamento de fonte | qualquer caminho igual a `src` ou começando com `src/` |
+
+> Arquivos escaneados são pulados se não forem texto (apenas `.js/.ts/.json/.md/.css/.yaml/.toml/.sh/.env/.txt/.html` são lidos) ou maiores que **512 KB**. Credenciais placeholder (`user`, `admin`, `changeme`, `xxx`, `your…`, `localhost`, …) **não** contam como segredo de URL de DB.
+
+### Repositório duplo (público vs dev) 🕳️
+
+| Remoto | Repositório | Contém | Histórico |
+| --- | --- | --- | --- |
+| `dev` | `gabriel7silva/constella-Dev` | Árvore de fonte privada completa (`src/`, testes, e2e, histórico) | Real, preservado |
+| `public` | `gabriel7silva/constella` | Apenas produto (docs, `bin/`, `drizzle/`, `skills/`, configs) | Descartável — sobrescrito por force-push |
+
+O espelho público **não** é um alvo de colaboração com histórico compartilhado. Cada `--push` escreve um commit-raiz novo e sobrescreve o `main` à força. O desenvolvimento acontece contra `dev`; o tarball do npm é publicado separadamente de qualquer push git.
+
+---
+
+## Passo a passo 🛰️
+
+### Publicar uma nova versão npm
+
+```bash
+# 1. Garanta que a árvore de trabalho está limpa e a versão foi incrementada no package.json.
+# 2. Publique — prepublishOnly + prepack rodam automaticamente:
+npm publish
+#    prepublishOnly: drizzle-kit generate && (typecheck + parity + build)
+#    prepack:        trim-next.mjs remove .next/{dev,cache,trace}
+#    allowlist files: .next, bin, scripts, skills, docs, drizzle, configs, README, LICENSE, CHANGELOG
+```
+
+> O `package.json` está atualmente com `"private": true` (a nota `//private`: *"Keep true until the npm account exists; flip to false (or remove) to publish."*). O npm se recusa a publicar um pacote privado até que essa flag seja removida. O `publishConfig.access` já é `"public"`.
+
+Para verificar o conteúdo exato do tarball **sem** publicar:
+
+```bash
+npm pack            # roda prepack → trim-next; escreve constellai-0.1.0.tgz
+tar -tf constellai-0.1.0.tgz | sort   # inspecione o que seria enviado — confirme que não há src/
+```
+
+### Espelhar a árvore limpa no repositório Git público
+
+```bash
+# Simulação — gera migrações se necessário, calcula o conjunto, escaneia segredos, imprime a contagem:
+node scripts/publish-public.mjs
+#   ✓ Clean: <N> files to publish (no src/, no secrets). Migrations: <M> file(s).
+
+# Push — constrói a árvore filtrada em um índice temp e faz force-push para o public main:
+node scripts/publish-public.mjs --push
+#   ✓ Pushed. The npm tarball (with the prebuilt .next) is published separately via `npm publish`.
+```
+
+### Limpeza antes de qualquer canal
+
+```bash
+npm run clean    # scripts/clean-repo.mjs — remove artefatos de rascunho na raiz do repo
+```
+
+O `clean-repo.mjs` é idempotente e conservador: ele só apaga um conjunto conhecido — `Constella App.html`, `extracted_design_system.css`, `tsconfig.tsbuildinfo` e `temp_*.{js,ts,jsx,tsx,html,css}` — nunca fonte ou config.
+
+---
+
+## Exemplos 🌠
+
+**Uma simulação limpa:**
+
+```text
+$ node scripts/publish-public.mjs
+✓ Clean: 412 files to publish (no src/, no secrets). Migrations: 7 file(s).
+
+Dry run. To publish the clean compiled tree to the public repo, run:
+  node scripts/publish-public.mjs --push
+```
+
+**Uma execução bloqueada (o portão fazendo seu trabalho):**
+
+```text
+$ node scripts/publish-public.mjs
+✖ Refusing to publish — 2 potential secret/sensitive/source finding(s):
+  - docs/notes/scratch.md: Telegram bot token
+  - private.pem: sensitive file
+```
+
+Nada é enviado; o script sai com `1`. Corrija os achados (mova-os para fora do conjunto de publicação, redija, ou adicione um caminho de allow legítimo) e re-execute a simulação até que reporte limpo.
+
+**Trim durante um pack:**
+
+```text
+$ npm pack
+• trim-next: removed .next/dev
+• trim-next: removed .next/cache
+• trim-next: removed .next/trace
+• trim-next: .next trimmed to the production runtime.
+constellai-0.1.0.tgz
+```
+
+---
+
+## Estados possíveis 🪐
+
+| Estado | Canal | Significado | Saída |
+| --- | --- | --- | --- |
+| `Clean: N files to publish` | Git (simulação) | Conjunto calculado, sem achados; nada enviado | `0` |
+| `Pushed` | Git (`--push`) | Árvore filtrada com force-push para `public main` | `0` |
+| `Refusing to publish — N finding(s)` | Git | Um caminho de segredo/sensível/fonte foi detectado | `1` |
+| `src/ leaked into the public tree` | Git | Um caminho `src/` escapou para o conjunto de publicação | `1` |
+| `trim-next: no .next/ — nothing to trim` | npm (`prepack`) | Sem build presente; pula silenciosamente | `0` |
+| `trim-next: .next trimmed…` | npm (`prepack`) | Dev/cache/trace removidos do build | `0` |
+| `Generating DB migrations (drizzle/)…` | Git | `drizzle/` estava ausente; regenerado antes da varredura | continua |
+
+---
+
+## Integrações relacionadas 🛰️
+
+| Integração | Relação com a publicação |
+| --- | --- |
+| **`drizzle-kit`** | `prepublishOnly` e `publish-public.mjs` regeneram as migrações em `drizzle/` para que o esquema viaje como SQL, não TypeScript. |
+| **Scanner de segredos** (`src/server/git-scan.ts`) | `publish-public.mjs` embute um espelho de suas regras; o mesmo motor protege commits do [GITHUB](./GITHUB.md) e exports do [PREPARE_DEPLOY](./PREPARE_DEPLOY.md). |
+| **Caminho de atualização** ([UPDATE](./UPDATE.md)) | Usuários puxam novas versões do registro npm para onde o tarball é publicado (`registry.npmjs.org/constellai/latest`). |
+| **Paridade i18n** ([CONFIGURATION](./CONFIGURATION.md)) | `validate` roda `i18n-parity.mjs`, bloqueando uma publicação se houver divergência de chaves EN ↔ PT. |
+
+---
+
+## Segurança 🕳️
+
+Publicar é uma operação de alta confiança; o design assume que um erro *vai* acontecer e o detém no portão.
+
+- **O código-fonte nunca viaja.** Ambos os canais excluem o `src/`. O espelho Git verifica duas vezes — `EXCLUDE` o filtra, e depois uma passagem final aborta se algum caminho `src/` sobreviveu.
+- **A varredura de segredos recusa em qualquer achado.** `publish-public.mjs` bloqueia no **primeiro** match por arquivo, em 10 padrões inline + uma regra de nome de arquivo sensível. É deliberadamente conservador (limite de `512 KB` para arquivos de texto, tolerância a credenciais placeholder para evitar falsos positivos em docs).
+- **`.env` e arquivos de DB são sensíveis por nome.** Eles são bloqueados mesmo que você nunca os tenha aberto — exceto a allowlist explícita (`.env.example`, etc.) e o DDL `drizzle/*.sql`.
+- **O force-push é intencional.** O repositório público é um *espelho limpo*, não um histórico de colaboração. Ele não carrega `.next` nem segredos, então sobrescrevê-lo é seguro por construção.
+- **O tarball é compilado.** Usuários finais rodam um `.next` minificado e migrações SQL aplicadas — sem fonte de aplicação legível, sem devDependencies.
+- **Segredos vivem fora da árvore.** Segredos de runtime são persistidos em `<HOME>/.env` (`chmod 600`) e nunca no repositório; a chave do vault, o segredo do worker e o segredo de auth são gerados no primeiro boot. Veja [SECURITY](./SECURITY.md).
+
+> O scanner é uma rede de segurança, não um substituto para disciplina. Mantenha segredos em `<HOME>/.env` e no vault, nunca em arquivos rastreados.
+
+---
+
+## Solução de problemas 🛰️
+
+| Sintoma | Causa | Correção |
+| --- | --- | --- |
+| `Refusing to publish — N finding(s)` | Um arquivo rastreado/`drizzle` casou com uma regra de segredo ou nome sensível | Inspecione cada caminho listado; redija, remova do conjunto de publicação ou (em casos legítimos) confirme que se encaixa numa regra de allow. Re-execute a simulação. |
+| `src/ leaked into the public tree` | Um caminho sob `src/` chegou ao conjunto de publicação | Isso deveria ser impossível via `EXCLUDE`; verifique que nada faz force-add de `src/` e re-execute. |
+| `npm publish` aborta imediatamente | O `package.json` tem `"private": true` | Remova/altere `private` quando a conta npm existir (conforme a nota `//private`). |
+| `trim-next: no .next/ — nothing to trim` e um tarball quebrado | Sem build antes de empacotar | Rode `npm run build` (ou confie no `prepublishOnly`, que faz build) antes do `npm pack`. |
+| Push público falha num remoto vazio | Enviar um commit sem ref para `main` não consegue inferir a ref | Já tratado — o script envia `<commit>:refs/heads/main` explicitamente. |
+| `git push -f public …` rejeitado | Remoto `public` ausente ou não autenticado | `git remote add public https://github.com/gabriel7silva/constella.git`; garanta que credenciais/`GIT_TERMINAL_PROMPT` permitam auth não-interativa. |
+| Migrações ausentes no espelho | `drizzle/` estava vazio e o generate falhou | Rode `npm run db:generate` manualmente e inspecione o erro antes de re-executar. |
+| Falha de paridade EN/PT no `validate` | Uma chave de dicionário existe em só um idioma | Corrija `src/lib/i18n.ts` para que as chaves EN ↔ PT batam; veja [CONFIGURATION](./CONFIGURATION.md). |
+
+---
+
+## Links relacionados
+
+- [INSTALLATION](./INSTALLATION.md) — o que um usuário final realmente recebe e onde isso aterrissa.
+- [UPDATE](./UPDATE.md) — como os usuários puxam novas versões publicadas.
+- [SECURITY](./SECURITY.md) — o vault, a jaula de FS e o motor de varredura de segredos.
+- [GITHUB](./GITHUB.md) — o caminho de commit/export que compartilha o scanner de segredos.
+- [PREPARE_DEPLOY](./PREPARE_DEPLOY.md) · [DEPLOY](./DEPLOY.md) — enviar um *produto construído*, distinto de publicar a própria Constella.
+- [CONFIGURATION](./CONFIGURATION.md) — paridade i18n e o portão de validação.
+- [ARCHITECTURE](./ARCHITECTURE.md) — o runtime root e o modelo "o diretório é a verdade".
+
+---
+
+<sub>✦ O estaleiro fica em silêncio, o lançamento é estrondoso. Publique o produto, guarde os blueprints. 🚀</sub>