constella 0.1.0

package/docs/pt/START_MODE.md

@@ -0,0 +1,340 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/START_MODE.md) · [✦ Constella](../../README.pt-BR.md)
+
+# Start Mode ✦ — a plataforma de lançamento
+
+> A ignição padrão para uma nave de piloto único: o Constella sobe em `127.0.0.1`, provisiona um operador local automaticamente, faz seu login sem tela de autenticação e deixa a constelação de agentes rodar com permissões locais totais.
+
+O Start Mode é o modo de execução que você obtém ao iniciar o Constella sem nenhuma flag de modo (ou com `--start`). Ele otimiza para um único operador na própria máquina: zero atrito, sem senhas, autonomia total dos agentes.
+
+---
+
+## 🛰️ Quando usar
+
+| Use o Start Mode quando… | Prefira outro modo quando… |
+| --- | --- |
+| Você roda o Constella **no seu próprio notebook / estação** | Você o expõe em rede → [AUTH_MODE](./AUTH_MODE.md) / [VPS_MODE](./VPS_MODE.md) |
+| Você quer **sem tela de login**, sempre autenticado | Vários humanos precisam de contas / 2FA → [AUTH_MODE](./AUTH_MODE.md) |
+| Você quer agentes que **instalam dependências + rodam testes** (shell completo) | Você quer agentes presos a só-edições → [AUTH_MODE](./AUTH_MODE.md) |
+| Você está desenvolvendo, demonstrando ou rodando uma agent-company pessoal | Você inicializa de um pen-drive entre máquinas → [PORTABLE_MODE](./PORTABLE_MODE.md) |
+
+O Start Mode é **local por design**. Ele faz bind na interface de loopback e usa uma credencial de operador previsível — ambos seguros em uma única máquina, ambos inseguros em rede. O código se recusa a provisionar essa credencial em qualquer outro modo.
+
+---
+
+## 🌌 Como funciona
+
+O Start Mode é um dos quatro valores de `RunMode` (`src/lib/run-mode.ts`):
+
+```ts
+export type RunMode = "start" | "auth" | "vps" | "portable";
+```
+
+O launcher (`bin/constella.mjs`) seleciona o modo a partir da flag de lançamento e o exporta como `CONSTELLA_RUN_MODE`. O servidor inteiro o lê de volta através de `getRunMode()`, que **assume `start` como padrão** quando a variável de ambiente está ausente ou é desconhecida:
+
+```ts
+// src/lib/run-mode.ts
+export function getRunMode(): RunMode {
+  const m = process.env.CONSTELLA_RUN_MODE as RunMode | undefined;
+  return m && m in RUN_MODES ? m : "start";
+}
+```
+
+O registro `RUN_MODES` marca `start` como o único modo que **não** exige login:
+
+```ts
+start: { label: "Start", requiresLogin: false, note: "Local auto-created account · always signed in." },
+```
+
+Três comportamentos derivam desse único fato:
+
+1. **Sem tela de login.** O guarda de workspace envia requisições não autenticadas para a rota silenciosa de auto-login, em vez de `/login`.
+2. **Operador provisionado automaticamente.** Um usuário local real + um hash de senha real do better-auth são criados de forma idempotente, e a sessão é iniciada.
+3. **Agentes com acesso total.** O adaptador da CLI roda os agentes com `--permission-mode bypassPermissions` (instalar dependências, rodar testes, shell completo) porque você está na sua própria máquina.
+
+O modo escolhido também é **persistido na organização** no momento do onboarding (`organization.runMode`), de forma que o registro da org lembra que nasceu em Start Mode.
+
+---
+
+## 🚀 Fluxo principal
+
+```mermaid
+flowchart TD
+  A["constella  (sem flag)  ou  constella --start"] --> B["bin/constella.mjs"]
+  B --> C["CONSTELLA_RUN_MODE=start<br/>host=127.0.0.1  port=3000"]
+  C --> D["Persiste segredos em &lt;HOME&gt;/.env (chmod 600)<br/>BETTER_AUTH_SECRET · VAULT_KEY · WORKER_SECRET"]
+  D --> E["drizzle-kit migrate (DB novo ganha as tabelas)"]
+  E --> F["next start + worker (supervisionados)"]
+  F --> G["Navegador acessa qualquer página (app)"]
+  G --> H{"requireWorkspace():<br/>cookie de sessão?"}
+  H -- "sim" --> Z["Renderiza o app"]
+  H -- "não (start mode)" --> I["redirect /api/dev-login"]
+  I --> J["ensureLocalOperator()"]
+  J --> K["auth.signInEmail(operator@constella.dev)"]
+  K --> L["Set-Cookie + redirect /"]
+  L --> Z
+```
+
+### Fluxo de auto-login (o coração do Start Mode) 🌠
+
+```mermaid
+sequenceDiagram
+  participant U as Navegador
+  participant W as requireWorkspace()
+  participant R as /api/dev-login
+  participant D as dev-auth.ts
+  participant A as better-auth
+
+  U->>W: GET /(app)/...
+  W->>W: getSession()
+  Note over W: sem cookie de sessão
+  W-->>U: 307 → /api/dev-login
+  U->>R: GET /api/dev-login
+  R->>R: getRunMode() === "start" ?
+  alt não é start mode
+    R-->>U: 307 → /login
+  else start mode
+    R->>D: ensureLocalOperator()
+    D->>D: upsert user_operator + hash da credencial
+    R->>A: signInEmail(operator@constella.dev / operator123)
+    A-->>R: cookie de sessão (plugin nextCookies)
+    R-->>U: 307 → /  (agora autenticado)
+  end
+```
+
+---
+
+## 🪐 Conceitos-chave
+
+### O operador local
+
+`src/server/dev-auth.ts` define a conta previsível:
+
+```ts
+export const DEV_OPERATOR = {
+  id: "user_operator",
+  email: "operator@constella.dev",
+  password: "operator123",
+  name: "Operator",
+};
+```
+
+`ensureLocalOperator()` é **idempotente** e seguro de chamar a cada requisição:
+
+- Busca o usuário por e-mail; se ausente, insere `user_operator` (com `emailVerified: true`).
+- Busca a conta `credential`; se ausente, gera o hash de `operator123` pelo próprio `ctx.password.hash` do better-auth e insere uma linha de credencial real.
+- Retorna o id do usuário.
+
+Como o id é fixo (`user_operator`) e coincide com o dono do seed, uma org de demonstração semeada pertence ao operador provisionado automaticamente — então uma **limpeza do DB do zero se auto-recupera**: o próximo carregamento de página recria o operador e faz login, sem passo manual.
+
+> 🕳️ **Trava de defesa em profundidade:** `ensureLocalOperator()` lança `"ensureLocalOperator is start-mode only"` se `getRunMode() !== "start"`. A credencial previsível `operator/operator123`, portanto, **nunca** pode existir em um modo exposto à rede, onde a senha padrão seria um login remoto.
+
+### A rota de auto-login
+
+`src/app/api/dev-login/route.ts` é um handler `GET`:
+
+- Fora do Start Mode → `redirect("/login")` (a tela normal).
+- No Start Mode → `ensureLocalOperator()` → `auth.api.signInEmail({ email, password })` (o cookie é definido pelo plugin `nextCookies()` do better-auth) → `redirect("/")`.
+- Em qualquer falha → `redirect("/login?autologin=failed")`, para que o guarda nunca entre em loop.
+
+### O guarda de workspace
+
+`requireWorkspace()` de `src/lib/workspace.ts` é a barreira por onde passa toda página `(app)` e toda server action. O ramo do Start Mode:
+
+```ts
+if (!session) redirect(getRunMode() === "start" ? "/api/dev-login" : "/login");
+```
+
+Essa única linha é o que transforma "sem sessão" em "auto sign-in" no Start Mode, e em "mostrar a tela de login" em qualquer outro lugar.
+
+### Agentes com acesso total (`bypassPermissions`)
+
+`src/server/adapters/cli.ts` decide quanto poder de shell os agentes recebem:
+
+```ts
+const RUN_MODE = process.env.CONSTELLA_RUN_MODE ?? "start";
+const AGENT_FULL_ACCESS = process.env.CONSTELLA_AGENT_FULL_ACCESS != null
+  ? process.env.CONSTELLA_AGENT_FULL_ACCESS !== "0"
+  : RUN_MODE === "start";
+
+function claudePermArgs(): string[] {
+  return AGENT_FULL_ACCESS
+    ? ["--permission-mode", "bypassPermissions"]   // start → total: instala + testa
+    : ["--permission-mode", "acceptEdits"];        // modos de rede → presos: só edições
+}
+```
+
+Assim, no Start Mode as CLIs `claude` / `codex` rodam com `bypassPermissions` — podem instalar dependências e rodar testes no workspace — porque você está na sua própria máquina. Modos de rede (`auth` / `vps` / `portable`) assumem `acceptEdits` por padrão (só-edições, presos). Sobrescreva nos dois sentidos com `CONSTELLA_AGENT_FULL_ACCESS=1|0`. Os agentes ainda rodam sempre **vanilla** (um overlay temporário de settings define `disableAllHooks: true`), de modo que os hooks/plugins pessoais do `~/.claude` do operador nunca vazem para as execuções dos agentes. Veja [AGENTS](./AGENTS.md) e [AI_ARCHITECTURE](./AI_ARCHITECTURE.md).
+
+### O segredo de auth no Start Mode
+
+`next start` roda sob `NODE_ENV=production`, onde o better-auth **lança erro com o segredo padrão**. Então até o Start Mode local precisa de um `BETTER_AUTH_SECRET` real — o launcher gera e persiste um em `<HOME>/.env` (`chmod 600`). A única flexibilização: `assertAuthSecret()` aceita um segredo ausente **apenas** quando `RUN_MODE === "start"`; todo modo de rede falha de forma fechada sem ele (`src/lib/auth.ts`). Os cookies de sessão continuam não-`Secure` no Start Mode porque é `http` local apenas.
+
+---
+
+## Tabelas 📊
+
+### Start Mode vs os outros modos de execução
+
+| Propriedade | **start** | auth | vps | portable |
+| --- | --- | --- | --- | --- |
+| `requiresLogin` | **false** | true | true | true |
+| Tela de login | nenhuma (auto) | e-mail + senha | e-mail + senha | e-mail + senha |
+| Host de bind | `127.0.0.1` | `127.0.0.1` | `0.0.0.0` | `0.0.0.0` |
+| Operador | auto `operator@constella.dev` | você cria | você cria | você cria |
+| Permissão dos agentes | `bypassPermissions` | `acceptEdits` | `acceptEdits` | `acceptEdits` |
+| `BETTER_AUTH_SECRET` obrigatório | persistido, não imposto | imposto | imposto | imposto |
+| Cookies Secure | não (http local) | se atrás de https | sim | se atrás de https |
+| Uso típico | máquina própria / dev | máquina compartilhada, rede local | servidor via Tailscale | USB entre máquinas |
+
+### Comandos de lançamento → Start Mode
+
+| Comando | Resultado |
+| --- | --- |
+| `constella` | Start Mode (padrão `cmd === "start"`) |
+| `constella --start` | Start Mode (explícito) |
+| `constella --bind local` | Start Mode (compatibilidade legada de `--bind`) |
+| `CONSTELLA_RUN_MODE=start` | Força Start Mode no processo do servidor |
+
+### Variáveis de ambiente que moldam o Start Mode
+
+| Variável | Padrão no Start Mode | Efeito |
+| --- | --- | --- |
+| `CONSTELLA_RUN_MODE` | `start` | O modo de execução que o servidor lê |
+| `CONSTELLA_HOME` | `~/.constella` | Raiz de runtime (DB, segredos, orgs) |
+| `--host` / host | `127.0.0.1` | Bind de loopback |
+| `--port` / `PORT` | `3000` | Porta web |
+| `CONSTELLA_AGENT_FULL_ACCESS` | `1` (implícito pelo start) | `0` reaprisiona os agentes em só-edições |
+| `CONSTELLA_WEB_RESEARCH` | ligado | `0` desativa WebSearch/WebFetch dos agentes |
+| `BETTER_AUTH_SECRET` | gerado → `<HOME>/.env` | Chave de assinatura de sessão |
+
+### Arquivos-chave
+
+| Arquivo | Papel |
+| --- | --- |
+| `src/lib/run-mode.ts` | Tipo `RunMode`, `RUN_MODES`, `getRunMode()`, `requiresLogin()` |
+| `bin/constella.mjs` | Launcher: escolhe o modo, define host/porta, persiste segredos, sobe web + worker |
+| `src/lib/workspace.ts` | `requireWorkspace()` — redireciona para `/api/dev-login` no Start Mode |
+| `src/app/api/dev-login/route.ts` | Rota de auto sign-in silenciosa |
+| `src/server/dev-auth.ts` | `DEV_OPERATOR`, `ensureLocalOperator()` |
+| `src/lib/auth.ts` | Config do better-auth; `assertAuthSecret()` flexibiliza só para `start` |
+| `src/server/adapters/cli.ts` | `claudePermArgs()` → `bypassPermissions` no Start Mode |
+| `src/lib/run-context.ts` | `detectRunContext()` para o caminho de Update |
+
+---
+
+## Passo a passo 🧭
+
+### Suba uma nave nova em Start Mode
+
+1. **Lance** sem flag (ou `--start`):
+   ```bash
+   npx constella
+   # ou, instalado globalmente:
+   constella --start
+   ```
+2. O launcher imprime a raiz de runtime e `Mode : start · 127.0.0.1:3000`, persiste os segredos em `<HOME>/.env`, aplica as migrations e sobe `next start` + o worker.
+3. **Abra** `http://127.0.0.1:3000`.
+4. `requireWorkspace()` não encontra sessão → redireciona para `/api/dev-login`.
+5. A rota provisiona `operator@constella.dev`, faz login, define o cookie e devolve para `/`.
+6. Se nenhuma org existir ainda, você cai no [ONBOARDING](./ONBOARDING.md); caso contrário, você está no app, já autenticado.
+
+### Limpar e auto-recuperar
+
+```bash
+# pare o Constella, depois:
+rm ~/.constella/constella.db
+constella
+```
+O próximo carregamento de página reexecuta `ensureLocalOperator()` e recria o operador — sem passo manual de conta.
+
+### Reaprisionar os agentes no Start Mode (cautela extra)
+
+```bash
+CONSTELLA_AGENT_FULL_ACCESS=0 constella --start
+```
+Os agentes agora rodam `acceptEdits` (só-edições, sem shell arbitrário), enquanto você mantém a conveniência do sem-login.
+
+---
+
+## Exemplos 🌟
+
+**Lançamento padrão (Start Mode):**
+```bash
+$ constella
+Constella runtime root : /home/you/.constella
+Mode                   : start  ·  127.0.0.1:3000
+• Secrets ready (stored in /home/you/.constella/.env, never printed).
+• Starting: next start -H 127.0.0.1 -p 3000  (…)  +  worker
+```
+
+**Porta personalizada, ainda Start Mode:**
+```bash
+$ constella --start --port 4000
+# → http://127.0.0.1:4000, auto-login, agentes com acesso total
+```
+
+**Fixar outra raiz de runtime:**
+```bash
+$ CONSTELLA_HOME=/data/constella constella --start
+# DB em /data/constella/constella.db; segredos em /data/constella/.env
+```
+
+---
+
+## Estados possíveis 🛰️
+
+| Situação | Comportamento |
+| --- | --- |
+| Sem cookie de sessão, Start Mode | Redireciona `/api/dev-login` → auto sign-in → `/` |
+| Sem cookie de sessão, **não** Start Mode | Redireciona `/login` |
+| Auto sign-in bem-sucedido | Cookie definido, cai em `/` (ou `/onboarding` se não houver org) |
+| Auto sign-in **falha** | Redireciona `/login?autologin=failed` (sem loop) |
+| `CONSTELLA_FORCE_ONBOARDING=1` | Após a sessão, redireciona `/onboarding` (one-shot, limpo por `completeOnboarding`) |
+| Org ausente / workspace ausente | Redireciona `/onboarding` |
+| `ensureLocalOperator()` chamado fora do start | Lança `"ensureLocalOperator is start-mode only"` |
+| Execução de agente, Start Mode | `claude --permission-mode bypassPermissions` (shell completo) |
+| Execução de agente, `CONSTELLA_AGENT_FULL_ACCESS=0` | `claude --permission-mode acceptEdits` (preso) |
+
+---
+
+## Integrações relacionadas 🪐
+
+- O **Onboarding** persiste o modo ativo em `organization.runMode` (`src/server/onboarding.ts`). Veja [ONBOARDING](./ONBOARDING.md).
+- O **Worker** (`bin/worker.mjs`) conecta de volta via `127.0.0.1` independentemente do host de bind; no Start Mode esse também é o bind do web. Veja [ARCHITECTURE](./ARCHITECTURE.md).
+- O **Vault** ainda precisa de `CONSTELLA_VAULT_KEY` mesmo no Start Mode (as chaves de provedor são criptografadas). Veja [SECURITY](./SECURITY.md).
+- O caminho de **Update** é sensível ao modo via `detectRunContext()`. Veja [UPDATE](./UPDATE.md).
+
+---
+
+## Segurança 🕳️
+
+O Start Mode troca o endurecimento de rede por conveniência local — seguro justamente por ser local:
+
+- **Somente loopback.** O host faz bind em `127.0.0.1`; nada é alcançável fora da máquina.
+- **A credencial previsível é travada.** `operator@constella.dev / operator123` é provisionada **apenas** quando `getRunMode() === "start"`; `ensureLocalOperator()` lança erro caso contrário. A rota de dev-login também retorna `/login` fora do Start Mode.
+- **Segredo de auth real persistido.** Um `BETTER_AUTH_SECRET` real é gerado em `<HOME>/.env` (`chmod 600`) para que as sessões não sejam forjáveis; os cookies são não-`Secure` apenas porque o transporte local é `http` puro.
+- **Agentes com acesso total são apenas locais.** `bypassPermissions` deixa os agentes rodarem shell, mas o workspace ainda é uma jaula de FS (`safe()` com checagens léxicas + de symlink), e os hooks de guarda/lock continuam valendo. Defina `CONSTELLA_AGENT_FULL_ACCESS=0` para reaprisionar.
+- **Não faça port-forward do Start Mode.** Se precisar de acesso remoto, mude para [VPS_MODE](./VPS_MODE.md) (Tailscale + Docker) ou [AUTH_MODE](./AUTH_MODE.md) — nunca exponha o Start Mode de loopback a uma rede, onde a senha padrão vira um login remoto.
+
+---
+
+## Solução de problemas 🧰
+
+| Sintoma | Causa provável | Correção |
+| --- | --- | --- |
+| Preso em `/login` apesar de `--start` | `CONSTELLA_RUN_MODE` não é `start` no servidor | Verifique a flag de lançamento; confira a linha `Mode : start` no boot |
+| `/login?autologin=failed` | Auto sign-in lançou erro (DB travado, schema não migrado) | Cheque o console `[dev-login] auto sign-in failed`; garanta que as migrations rodaram |
+| Loop de login | Guarda ↔ dev-login se rebatendo | A rota cai em `/login?autologin=failed` por design; inspecione o erro logado |
+| Agentes não instalam deps / não rodam testes | `CONSTELLA_AGENT_FULL_ACCESS=0` definido, ou não é Start Mode | Remova o override, ou relance com `--start` |
+| Alcançável de outra máquina | Você sobrescreveu `--host` para `0.0.0.0` | Remova `--host`; o Start Mode faz bind em `127.0.0.1` |
+| Erro de segredo do better-auth no boot | Forçou um modo de rede sem segredo | Modos de rede exigem `BETTER_AUTH_SECRET`; o launcher persiste um — deixe rodar, ou defina-o |
+| Operador sumiu após reset do DB | Esperado | Recarregue qualquer página — `ensureLocalOperator()` o recria |
+
+---
+
+## Links relacionados 🌌
+
+- [INSTALLATION](./INSTALLATION.md) · [ONBOARDING](./ONBOARDING.md) · [CONFIGURATION](./CONFIGURATION.md)
+- [AUTH_MODE](./AUTH_MODE.md) · [VPS_MODE](./VPS_MODE.md) · [PORTABLE_MODE](./PORTABLE_MODE.md)
+- [ARCHITECTURE](./ARCHITECTURE.md) · [AI_ARCHITECTURE](./AI_ARCHITECTURE.md) · [AGENTS](./AGENTS.md)
+- [SECURITY](./SECURITY.md) · [UPDATE](./UPDATE.md) · [TROUBLESHOOTING](./TROUBLESHOOTING.md) · [FAQ](./FAQ.md)

package/docs/pt/SYNCED_BLOCKS.md

@@ -0,0 +1,320 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/SYNCED_BLOCKS.md) · [✦ Constella](../../README.pt-BR.md)
+
+# 🌌 Synced Blocks — a nebulosa de memória canônica
+
+![](../assets/divider-orbit.svg)
+
+Os synced blocks (blocos sincronizados) são a **fonte única de verdade** para o conhecimento durável do projeto: uma unidade nomeada (`slug` + `body` em Markdown) editada em exatamente um lugar e exibida por referência em todos os outros — prompts dos agentes, a home de boas-vindas e transcluída em relatórios. Edite um bloco uma vez e toda superfície reflete a versão mais recente, sem o desalinhamento de copiar e colar. Eles são distintos do conhecimento auto-capturado em `kb_entry`: um synced block é **curado, canônico e versionado**; os agentes só podem *propor* edições nele.
+
+Fonte de verdade no código: `src/server/blocks.ts`, schema `src/db/schema.ts` (`synced_block`, `block_proposal`).
+
+---
+
+## 1. Quando usar 🪐
+
+Use synced blocks para fatos que:
+
+- são **duráveis** e **reutilizados** em muitas execuções e superfícies (a stack oficial, regras de negócio, padrões de segurança, a arquitetura que todo agente deve tratar como canônica);
+- precisam permanecer **consistentes** em todos os lugares onde aparecem (sem desalinhamento entre o arquivo de persona, um relatório e uma resposta no chat);
+- se beneficiam de **revisão do operador / agente de KB** antes de mudar a verdade compartilhada.
+
+**Não** os use para aprendizados transitórios, específicos de uma execução. Esses fluem para a KB auto-capturada via o token `[[REMEMBER type=<t>: <fact>]]` (sem aprovação) — veja [KB_RAG.md](./KB_RAG.md) e [MEMORY_RAG.md](./MEMORY_RAG.md).
+
+| Tipo de conhecimento | Mecanismo | Aprovação | Versionado | Doc |
+|---|---|---|---|---|
+| Fato canônico e curado | Synced block (`synced_block`) | Operador / agente de KB faz merge das propostas | Sim (`version`) | este doc |
+| Aprendizado auto-capturado | `kb_entry` via `[[REMEMBER …]]` | Nenhuma (ingerido diretamente) | Não (ciclo de status) | [KB_RAG.md](./KB_RAG.md) |
+
+---
+
+## 2. Como funciona 🛰️
+
+Um synced block vive na tabela `synced_block`, chaveado por `(workspaceId, slug)`. Seu `body` é Markdown canônico. Duas coisas acontecem sempre que um bloco é gravado via `upsertBlock`:
+
+1. A linha é **upsertada** — na criação `version = 1`; na atualização o `version` é incrementado (`cur.version + 1`), e `updatedBy` e `updatedAt` são atualizados.
+2. O corpo é **re-embeddado** em `rag_chunk` no caminho `block/<slug>` (`embedBlock`), para que os agentes também *recuperem* o bloco atual via RAG, não apenas o recebam injetado. Os chunks antigos desse caminho são apagados primeiro, então os embeddings nunca ficam obsoletos.
+
+O bloco então chega aos agentes por **três** superfícies distintas:
+
+- **Injetado** — `canonicalFactsSection(wsId)` monta uma seção compacta "Canonical project facts" (até os 20 blocos atualizados mais recentemente, cada um com título + kind + os primeiros 800 caracteres, limitada a 5000 caracteres no total) que o gestor de contexto injeta no topo de todo prompt de agente.
+- **Transcluído** — `resolveBlocks(orgId, text)` substitui marcadores `{{kb:slug}}` em qualquer texto (arquivos de persona, instruções, corpos de relatório) pelo `body` atual do bloco. Um slug ausente renderiza um marcador BEM visível `[[missing block: <slug>]]` em vez de sumir silenciosamente.
+- **Recuperado** — os chunks de RAG em `block/<slug>` são retornados pela recuperação normal do `kbQuery`, então um bloco pode aparecer mesmo quando não está na janela sempre-injetada.
+
+### Regras de slug
+
+Os slugs são normalizados (`normSlug`): em minúsculas, sem espaços nas pontas, caracteres fora de `[a-z0-9-]` colapsados em `-`, traços inicial/final removidos, truncado em 60 caracteres, e validado contra `/^[a-z0-9][a-z0-9-]{0,60}$/`. Um slug inválido faz o upsert falhar (`{ ok: false }`).
+
+### Limites de campo (impostos em `upsertBlock`)
+
+| Campo | Limite |
+|---|---|
+| `title` | cortado em 200 caracteres |
+| `body` | cortado em 20000 caracteres |
+| `kind` | cortado em 40 caracteres (padrão `note`) |
+| `updatedBy` | cortado em 60 caracteres (padrão `operator`) |
+
+---
+
+## 3. Fluxo principal 🌠
+
+```mermaid
+flowchart TD
+  subgraph Autoria
+    OP["Operador edita na UI de Knowledge"] -->|saveBlockAction| UP["upsertBlock()"]
+    SEED["Seeding no boot / KB card"] -->|seedDefaultBlocks · seedCanonicalBlocks| UP
+    AG["Agente propõe [[KB-BLOCK]]"] -->|proposeBlockEdit| PQ["block_proposal (pending)"]
+    PQ -->|mergeProposal| UP
+  end
+  UP -->|version++| TBL["synced_block (workspaceId, slug)"]
+  UP -->|re-embed| RC["rag_chunk path=block/&lt;slug&gt;"]
+  TBL -->|canonicalFactsSection| PROMPT["Prompt do agente: Canonical project facts"]
+  TBL -->|"resolveBlocks {{kb:slug}}"| SURF["Relatórios · persona · instruções"]
+  RC -->|recuperação kbQuery| PROMPT
+```
+
+---
+
+## 4. Conceitos-chave ✦
+
+| Conceito | O que é |
+|---|---|
+| **Block** | `typeof syncedBlock.$inferSelect` — uma unidade canônica de conhecimento `(slug, kind, title, body, version, updatedBy)`. |
+| **Proposal** | `typeof blockProposal.$inferSelect` — uma edição *sugerida* por um agente, aguardando merge/rejeição. |
+| **Marcador `{{kb:slug}}`** | Um token de transclusão resolvido em tempo de leitura para o corpo atual do bloco. |
+| **`[[KB-BLOCK slug]]…[[/KB-BLOCK]]`** | O token que um agente emite na saída da execução para *propor* uma edição de bloco. |
+| **Seção de fatos canônicos** | O resumo limitado de blocos injetado em todo prompt de agente como a fonte de verdade autoritativa. |
+| **Re-embedding** | Cada gravação atualiza o `rag_chunk` em `block/<slug>` para manter a recuperação por RAG atual. |
+| **Versionamento** | `version` começa em 1, incrementa a cada atualização; a UI mostra `v<n>` e `updatedBy`. |
+
+---
+
+## 5. Tabelas 🗄️
+
+### `synced_block` (PK `(workspaceId, slug)`)
+
+| Coluna | Tipo | Notas |
+|---|---|---|
+| `workspace_id` | text | FK → `workspace.id`, `onDelete: cascade` |
+| `slug` | text | handle estável, ex.: `official-stack` |
+| `kind` | text | padrão `note`; veja os kinds abaixo |
+| `title` | text | padrão `""` |
+| `body` | text | Markdown canônico — a fonte única de verdade |
+| `version` | integer | padrão `1`, incrementado a cada atualização |
+| `updated_by` | text | handle do agente ou `operator` (ou `system` para os semeados) |
+| `created_at` | timestamp | `unixepoch()` |
+| `updated_at` | timestamp | `unixepoch()`; os blocos são listados/resumidos em `desc(updatedAt)` |
+
+**Valores de `kind`** (do comentário no schema): `mission`, `objective`, `stack`, `architecture`, `business-rule`, `ui-pattern`, `security`, `commands`, `deploy-checklist`, `review-checklist`, `glossary`, `policy`, `note`. `kind` é texto livre (cortado em 40 caracteres), então são convenções, não um enum de banco.
+
+### `block_proposal` (PK `id`, índice `block_prop_ws_idx` em `(workspaceId, status)`)
+
+| Coluna | Tipo | Notas |
+|---|---|---|
+| `id` | text | `randomUUID()` |
+| `workspace_id` | text | FK → `workspace.id`, `onDelete: cascade` |
+| `slug` | text | slug do bloco alvo (normalizado) |
+| `kind` | text | padrão `note` |
+| `title` | text | padrão `""` |
+| `body` | text | corpo Markdown proposto |
+| `by_agent_handle` | text | quem propôs |
+| `status` | text enum | `pending` \| `merged` \| `rejected` (padrão `pending`) |
+| `created_at` | timestamp | `unixepoch()` |
+| `decided_at` | timestamp | definido no merge/rejeição |
+| `decided_by` | text | padrão `""`; `operator` a partir da action |
+
+---
+
+## 6. O conjunto canônico de blocos 🚀
+
+`seedCanonicalBlocks(orgId)` (ligado ao KB card e ao botão "Create central blocks" da Welcome Home via `seedDefaultBlocksAction`) garante que o conjunto curado completo exista. `mission`, `objective` e `official-stack` são preenchidos a partir dos próprios campos do workspace; o restante é criado como **placeholders iniciais editáveis** para que apareçam e sejam preenchidos. É **idempotente** — nunca sobrescreve um bloco existente e retorna quantos foram recém-criados.
+
+| slug | kind | origem do corpo |
+|---|---|---|
+| `mission` | `mission` | `workspace.mission` |
+| `objective` | `objective` | `workspace.objective` |
+| `official-stack` | `stack` | renderizado de `workspace.stack` (`- **key:** value`, ignora `None`) |
+| `current-architecture` | `architecture` | placeholder inicial |
+| `business-rules` | `business-rule` | placeholder inicial |
+| `ui-patterns` | `ui-pattern` | placeholder inicial |
+| `security-patterns` | `security` | placeholder inicial |
+| `deploy-checklist` | `deploy-checklist` | placeholder inicial |
+| `code-review-checklist` | `review-checklist` | placeholder inicial |
+| `glossary` | `glossary` | placeholder inicial |
+| `technical-decisions` | `note` | placeholder inicial |
+
+Um `seedDefaultBlocks(orgId)` mais leve semeia apenas `mission` / `objective` / `official-stack` e só se ausentes **e** não vazios. Ele roda no boot para cada workspace via `seedDefaultBlocksForExistingWorkspaces()` (chamado de `src/server/boot.ts`).
+
+---
+
+## 7. Propostas dos agentes: propor → revisar → merge ✦
+
+Os agentes nunca gravam blocos diretamente. A instrução do runner diz a eles:
+
+> Se você descobrir um FATO canônico DURÁVEL que pertence ao conhecimento compartilhado … você PODE propor uma edição de synced-block emitindo em linhas próprias: `[[KB-BLOCK <kebab-slug>]]` depois o novo corpo Markdown depois `[[/KB-BLOCK]]` — o operador / agente de Knowledge revisa e faz o merge. Use com moderação, apenas para fatos reutilizáveis (ex.: `official-stack`, `security-patterns`).
+
+Após uma execução bem-sucedida, `src/server/runner.ts` varre a saída por blocos `[[KB-BLOCK slug]]…[[/KB-BLOCK]]`, chama `proposeBlockEdit` para cada um (enfileirando um `block_proposal` com `status = pending`), registra os slugs tocados (→ chips na room), e **remove os tokens** do texto visível. Cada proposta também:
+
+- empurra um item de **Inbox** (`kind: review`, `refType: validation`, `refId = proposalId`) com título `Block edit proposed — <slug>`;
+- dispara uma notificação ao operador via `notifyOps`.
+
+O operador (ou o agente de Knowledge, Vannevar) então faz **merge** ou **rejeita** no `BlocksPanel` do módulo de Knowledge.
+
+```mermaid
+sequenceDiagram
+  participant A as Agente
+  participant R as runner.ts
+  participant P as block_proposal
+  participant I as Inbox / notifyOps
+  participant OP as Operador / agente de KB
+  participant B as synced_block
+
+  A->>R: saída com [[KB-BLOCK slug]]…[[/KB-BLOCK]]
+  R->>P: proposeBlockEdit() → status=pending
+  R->>I: pushInbox(review/validation) + notifyOps
+  Note over OP: revisa em Knowledge → BlocksPanel
+  alt merge
+    OP->>P: mergeProposalAction(id)
+    P->>B: upsertBlock(body, updatedBy=byAgentHandle) → version++
+    B->>B: re-embed rag_chunk block/<slug>
+    P->>P: status=merged, decidedAt, decidedBy
+    P->>I: resolveInboxFor(validation, id)
+  else reject
+    OP->>P: rejectProposalAction(id)
+    P->>P: status=rejected, decidedAt, decidedBy
+    P->>I: resolveInboxFor(validation, id)
+  end
+```
+
+No **merge**, `mergeProposal(wsId, id, by)` só prossegue se a proposta ainda estiver `pending`; ele então roda `upsertBlock` com `updatedBy` definido como o handle do agente proponente (preservando a autoria), marca a proposta como `merged` e resolve o item de Inbox. Na **rejeição**, `rejectProposal` a marca como `rejected` e resolve o item de Inbox sem tocar no bloco.
+
+---
+
+## 8. Passo a passo 🛠️
+
+**Semear o conjunto canônico**
+
+1. Abra o módulo **Knowledge** (ou o KB card da Welcome Home / dashboard).
+2. Clique em **Create central blocks** → `seedDefaultBlocksAction` → `seedCanonicalBlocks`.
+3. `mission` / `objective` / `official-stack` vêm pré-preenchidos do workspace; o restante aparece como placeholders iniciais para editar.
+
+**Editar um bloco como operador**
+
+1. No `BlocksPanel`, clique em **Edit** em um bloco (ou em **New**).
+2. Defina `slug`, `title`, `kind`, `body` (Markdown).
+3. Salve → `saveBlockAction` → `upsertBlock(…, updatedBy: "operator")` → `version++` + re-embed.
+
+**Transcluir um bloco em um relatório ou persona**
+
+1. Escreva `{{kb:official-stack}}` em qualquer lugar do texto.
+2. Em tempo de leitura, `resolveBlocks` o troca pelo corpo atual do bloco (relatórios resolvem em `src/app/(app)/reports/[id]/page.tsx`; prompts resolvem ao final da montagem de contexto).
+
+**Deixar um agente propor uma mudança**
+
+1. O agente emite `[[KB-BLOCK security-patterns]] …novo corpo… [[/KB-BLOCK]]` na saída da execução.
+2. A proposta cai na lista de pendentes do módulo de Knowledge + na Inbox.
+3. Você faz **Merge** (aplica + incrementa a versão) ou **Reject**.
+
+---
+
+## 9. Exemplos 📡
+
+**Marcador de transclusão** (em um relatório ou em `.claude/agents/<handle>/Agent.md`):
+
+```markdown
+## Stack you must use
+{{kb:official-stack}}
+
+## Rules you must never break
+{{kb:business-rules}}
+```
+
+Um slug ausente permanece bem visível:
+
+```markdown
+{{kb:does-not-exist}}   →   [[missing block: does-not-exist]]
+```
+
+**Token de proposta do agente** (emitido pelo agente, removido do chat após a captura):
+
+```text
+[[KB-BLOCK official-stack]]
+- **language:** TypeScript
+- **framework:** Next.js 16
+- **db:** SQLite via drizzle-orm
+[[/KB-BLOCK]]
+```
+
+**Resumo injetado** (o que `canonicalFactsSection` produz, abreviado):
+
+```text
+### Official stack (stack)
+- **framework:** Next.js 16
+- **db:** SQLite
+
+### Business rules (business-rule)
+...primeiros 800 caracteres...
+```
+
+---
+
+## 10. Estados possíveis 🕳️
+
+**Block** — não tem coluna de status; seu ciclo de vida é o contador `version`. Um bloco existe, é editado (versão incrementa), ou é deletado (`deleteBlock` remove a linha **e** suas entradas em `rag_chunk` no caminho `block/<slug>`).
+
+**Proposal** (`block_proposal.status`):
+
+| Estado | Significado | Definido por |
+|---|---|---|
+| `pending` | aguardando decisão do operador/agente de KB; aparece em `listProposals` + Inbox | `proposeBlockEdit` (padrão) |
+| `merged` | aplicado ao bloco (versão incrementada), Inbox resolvida | `mergeProposal` |
+| `rejected` | descartado, bloco intocado, Inbox resolvida | `rejectProposal` |
+
+`listProposals(wsId)` retorna apenas as propostas `pending`, mais recentes primeiro.
+
+---
+
+## 11. Integrações relacionadas 🔗
+
+- **RAG** ([KB_RAG.md](./KB_RAG.md), [MEMORY_RAG.md](./MEMORY_RAG.md)) — cada gravação re-embedda o bloco em `rag_chunk` (`embed` + `chunksOf`) no caminho `block/<slug>`, então blocos participam da recuperação normal. Um fallback por palavra-chave se aplica se o servidor de embeddings estiver fora.
+- **Gestor de contexto** ([AI_ARCHITECTURE.md](./AI_ARCHITECTURE.md)) — `canonicalFactsSection` é injetado como a seção de prioridade máxima "Canonical project facts"; `resolveBlocks` roda por último sobre o prompt montado.
+- **Inbox** ([INBOX.md](./INBOX.md)) — propostas levantam e resolvem itens de revisão `validation`.
+- **Agentes / agente de Knowledge** ([AGENTS.md](./AGENTS.md), [KB_AGENT.md](./KB_AGENT.md)) — agentes propõem; Vannevar / o operador faz o merge.
+- **Relatórios & specs** ([GOALS_SPECS_ISSUES.md](./GOALS_SPECS_ISSUES.md)) — corpos de relatório transcluem `{{kb:slug}}` em tempo de leitura.
+- **Tokens de conhecimento** ([CHAT_COMMANDS.md](./CHAT_COMMANDS.md)) — `[[KB-BLOCK …]]` convive com `[[REMEMBER …]]` / `[[CONSULT …]]` no vocabulário de tokens dos agentes.
+
+---
+
+## 12. Segurança 🛡️
+
+- **Sem gravações diretas de agentes.** Agentes só podem *propor*; o corpo canônico muda apenas via `mergeProposal` / `saveBlockAction` (operador ou agente de KB). Isso mantém a fonte de verdade compartilhada sob controle humano/curador.
+- **Isolamento de workspace.** Toda consulta é escopada por `workspaceId`; a PK é `(workspaceId, slug)` e as FKs cascateiam na exclusão do workspace.
+- **Entrada limitada.** `title`/`body`/`kind`/`updatedBy` têm tamanho limitado; slugs são normalizados e validados por regex antes de qualquer gravação.
+- **Higiene de segredos.** Blocos são conhecimento curado, mas trate os corpos como qualquer superfície compartilhada — não cole segredos; a plataforma faz scrub de segredos na ingestão de KB, no Telegram e nos logs (`scrubSecrets`, veja [SECURITY.md](./SECURITY.md)).
+- **Resiliência.** Todas as funções de bloco envolvem o trabalho de banco em `try/catch` e degradam graciosamente (`listBlocks` → `[]`, `resolveBlocks` → texto original), então uma falha transitória nunca quebra a montagem do prompt.
+
+---
+
+## 13. Solução de problemas 🔧
+
+| Sintoma | Causa provável | Correção |
+|---|---|---|
+| `[[missing block: <slug>]]` em um relatório/prompt | o bloco referenciado não existe (ou erro de digitação no slug) | crie o bloco, ou corrija o marcador `{{kb:slug}}`; slugs são kebab minúsculo |
+| Gravação do bloco falha em silêncio (`{ ok: false }`) | slug inválido (falha o `SLUG_RE`) ou vazio após normalização | use `[a-z0-9-]`, comece com alfanumérico, ≤ 60 caracteres |
+| A proposta do agente nunca aparece | o agente não a envolveu corretamente, ou o corpo estava vazio | os tokens devem ser exatamente `[[KB-BLOCK <slug>]]` … `[[/KB-BLOCK]]` com corpo não vazio |
+| O botão de merge não faz nada | a proposta não está mais `pending` (já decidida) | recarregue; `mergeProposal` ignora propostas não pendentes |
+| O bloco editado não aparece nas respostas do agente | recuperação de RAG fria / servidor de embeddings fora | o bloco ainda é injetado via `canonicalFactsSection`; verifique o servidor de embeddings (veja [MODELS.md](./MODELS.md)) |
+| Nenhum bloco após o onboarding | `mission`/`objective`/`stack` do workspace estavam vazios (nada a semear) | clique em **Create central blocks** para semear o conjunto completo com placeholders |
+
+---
+
+## 14. Links relacionados ✦
+
+- [KB_RAG.md](./KB_RAG.md) — a base de conhecimento, ingestão e `kbQuery`
+- [MEMORY_RAG.md](./MEMORY_RAG.md) — embeddings, a nebulosa de memória
+- [KB_AGENT.md](./KB_AGENT.md) — Vannevar, o agente de Knowledge
+- [AI_ARCHITECTURE.md](./AI_ARCHITECTURE.md) — como o contexto é montado para os agentes
+- [AGENTS.md](./AGENTS.md) — o elenco de agentes e como eles executam
+- [INBOX.md](./INBOX.md) — itens de revisão e resolução
+- [GOALS_SPECS_ISSUES.md](./GOALS_SPECS_ISSUES.md) — specs, relatórios, alvos de transclusão
+- [CHAT_COMMANDS.md](./CHAT_COMMANDS.md) — vocabulário de tokens dos agentes
+- [SECURITY.md](./SECURITY.md) — isolamento, scrubbing, vault