nexus-core-v3 3.0.0

package/knowledge/engineering/testing-strategy-beyond-unit.md

@@ -0,0 +1,307 @@
+---
+id: testing-strategy-beyond-unit
+domain: engineering
+agents: [qa, dev]
+when: "ao desenhar a estratégia de testes de uma feature ou avaliar a cobertura de uma story"
+---
+
+# Testing strategy beyond unit — testes que pegam bug, não que decoram cobertura
+
+Suíte de teste medíocre tem uma "cara": ela é verde, tem 85% de cobertura, e mesmo assim
+bugs escapam pra produção. O motivo é quase sempre o mesmo — os testes visitam o código
+sem testar nada, ou estão tão acoplados aos internos que quebram a cada refactor e ninguém
+mais confia neles. Este pack ensina a **escolher o tipo de teste certo, escrevê-lo pra pegar
+bug de verdade, e medir se ele presta** — destilado do
+[goldbergyoni/javascript-testing-best-practices](https://github.com/goldbergyoni/javascript-testing-best-practices)
+(Yoni Goldberg). A regra-mãe (o "Golden Rule" do repo): **código de teste não é código de
+produção — projete-o pra ser curto, raso e óbvio. Olhe um teste e entenda a intenção na hora.**
+Tudo abaixo deriva disso.
+
+## O problema / os tells
+
+Se a suíte tem 3+ destes, ela é teatro de cobertura, não rede de segurança:
+
+1. **Nome de teste que não diz nada** — `it("Add product")`, `it("Test addNewOrder")`. Falhou no
+   CI: você não faz ideia do que quebrou sem abrir o código.
+2. **Sem separação AAA** — arrange, act e assert grudados num bloco só; o leitor gasta CPU mental
+   só pra achar onde o teste age e onde verifica.
+3. **Asserção imperativa** — `forEach` + `if` + flags booleanas + `throw` manual em vez de um
+   `expect` declarativo. A "história" do teste some no meio do controle de fluxo.
+4. **Testa método privado / internals** — o teste chama `calculateVATAdd()` (interno) e quebra
+   quando você renomeia o método, embora o resultado final esteja certo. O teste vira o menino
+   que gritou lobo: dá falso-positivo até alguém ignorar o CI e um bug real passar.
+5. **Mock que verifica "foi chamado com esses args"** — `mock.expects("deleteProduct").withArgs(...)`.
+   Acoplado ao como, não ao quê. Qualquer refactor obriga a caçar e reescrever todos os mocks.
+6. **Input `"Foo"` / `123`** — input sintético nunca dispara o regex de validação, o path de erro,
+   o caso de borda. Verde no dev, vermelho quando um usuário manda `"@3e2ddsf . ##' 1 fdsfds"`.
+7. **`setTimeout(2000)` esperando algo async** — o teste é lento (espera demais) ou flaky (espera
+   de menos). Trade-off entre lentidão e flakiness, perde nos dois.
+8. **Seed global de DB** (`before(() => DB.seed('seed.json'))`) — testes acoplados a dados que
+   vivem fora deles; dois testes mutam a mesma linha e o deploy aborta sem causa óbvia.
+9. **Selector por classe CSS** — `wrapper.find("[className='thin-border']")`. O designer troca a
+   classe e o teste de *lógica* de login quebra.
+10. **Snapshot gigante externo** — `toMatchSnapshot()` de 2000 linhas que ninguém leu; quebra a
+    cada espaço, comentário ou mudança de CSS, e o autor aprova cegamente o "novo correto".
+11. **100% de cobertura, 0% de teste** — o teste chama a função e não tem **nenhum** `expect`.
+    Visitou todas as linhas, não verificou nada.
+12. **Só pirâmide de unit** — 50% do budget em unit tests pra uma app que é integração-cêntrica
+    (ingest Kafka → data warehouse → UI), quase sem lógica. Muito esforço, 20% de cobertura real.
+
+## Os princípios do craft (com pares bad→good reais do repo)
+
+### 1. Nome do teste em 3 partes: o quê / cenário / esperado
+O relatório do CI tem que dizer o que está quebrado pra quem **não** conhece o código (o ops que
+faz deploy, você daqui a dois anos). Três partes: (1) unidade sob teste, (2) cenário/circunstância,
+(3) resultado esperado.
+
+```javascript
+// ❌ "Add product" — falhou no deploy. Isso te diz o que está com defeito?
+
+// ✅ describe aninhado carrega a parte (1); o it() carrega (2) e (3)
+describe('Products Service', () => {
+  describe('Add new product', () => {
+    it('When no price is specified, then the product status is pending approval', () => {
+      const newProduct = new ProductService().add(/* ... */);
+      expect(newProduct.status).to.equal('pendingApproval');
+    });
+  });
+});
+```
+
+### 2. Estruture com AAA — Arrange, Act, Assert, separados
+Três seções marcadas. Garante que o leitor não gasta "brain-CPU" decifrando o plano do teste.
+Act e Assert costumam ser 1 linha cada.
+
+```javascript
+// ❌ tudo num bloco só, mais difícil de interpretar
+test("Should be classified as premium", () => {
+  const customerToClassify = { spent: 505, joined: new Date(), id: 1 };
+  const DBStub = sinon.stub(dataAccess, "getCustomer").reply({ id: 1, classification: "regular" });
+  const received = customerClassifier.classifyCustomer(customerToClassify);
+  expect(received).toMatch("premium");
+});
+
+// ✅ Arrange / Act / Assert separados
+test("When customer spent more than 500$, should be classified as premium", () => {
+  // Arrange
+  const customerToClassify = { spent: 505, joined: new Date(), id: 1 };
+  sinon.stub(dataAccess, "getCustomer").reply({ id: 1, classification: "regular" });
+  // Act
+  const receivedClassification = customerClassifier.classifyCustomer(customerToClassify);
+  // Assert
+  expect(receivedClassification).toMatch("premium");
+});
+```
+
+### 3. Asserção declarativa (BDD), não fluxo imperativo
+Código imperativo com `if`/`forEach`/flags força o leitor a executar o teste na cabeça. Use
+`expect`/`should` declarativo. Se a asserção que você precisa não existe e é repetível, estenda o
+matcher — não escreva lógica de verificação inline.
+
+```javascript
+// ❌ o leitor tem que percorrer o loop pra entender a história do teste
+allAdmins.forEach(u => {
+  if (u === "user1") assert.notEqual(u, "user1", "A user was found and not admin");
+  if (u === "admin1") admin1Found = true;
+  if (u === "admin2") admin2Found = true;
+});
+if (!admin1Found || !admin2Found) throw new Error("Not all admins were returned");
+
+// ✅ uma linha declarativa
+expect(allAdmins)
+  .to.include.ordered.members(["admin1", "admin2"])
+  .but.not.include.ordered.members(["user1"]);
+```
+
+Corolário — **não capture erro, espere-o.** Nada de `try/catch` + flag pra provar que lançou.
+
+```javascript
+// ❌ se a asserção final falhar, o relatório só diz "valor null" — nada sobre exceção faltando
+let caught = null;
+try { await addNewProduct({}); } catch (e) { expect(e.code).to.equal("InvalidInput"); caught = e; }
+expect(caught).not.to.be.null;
+
+// ✅ legível até pro QA/PM, e o tipo do erro é verificado
+await expect(addNewProduct({}))
+  .to.eventually.throw(AppError)
+  .with.property("code", "InvalidInput");
+```
+
+### 4. Teste comportamento via API pública (black-box), nunca internals
+Verificar o comportamento público testa a implementação privada **implicitamente**. Testar o
+interno (white-box) desloca o foco pro detalhe e quebra o teste em refactors inofensivos.
+
+```javascript
+// ❌ white-box: testa um método interno que nem é requisito
+class ProductService {
+  calculateVATAdd(price) { return { finalPrice: price * 1.2 }; } // renomear → testes quebram
+  getPrice(id) { return this.calculateVATAdd(DB.getProduct(id).price).finalPrice; }
+}
+expect(new ProductService().calculateVATAdd(0).finalPrice).to.equal(0);
+
+// ✅ teste o que é requisito (preço final via método público); o VAT é coberto de tabela
+```
+
+No frontend, a mesma regra vira "renderize de verdade e aja como o usuário", não shallow render +
+invocar método interno:
+
+```javascript
+// ✅ realista: monta o componente, clica, verifica o que o usuário vê
+const wrapper = mount(<Calendar showFilters={false} />);
+wrapper.find("button").simulate("click");
+expect(wrapper.text().includes("Choose Filter"));
+
+// ❌ shallow + .instance().showFilters() — tapeia a UI e chama método privado (white-box)
+```
+
+### 5. Escolha o test double certo: stub/spy (comportamento), não mock (internals)
+Antes de qualquer double, pergunte: **isto aparece (ou poderia aparecer) no documento de requisitos?**
+Se não, é cheiro de white-box. Stub pra simular um cenário ("pagamento fora do ar"), spy pra
+verificar um efeito que **é** requisito ("envie e-mail se o pagamento falhar"). Mock que checa
+"foi chamado com esses tipos/args" testa o interno — vai mudar toda hora.
+
+```javascript
+// ❌ mock: o objetivo virou verificar a chamada interna ao DAL, não o requisito
+const dataAccessMock = sinon.mock(DAL);
+dataAccessMock.expects("deleteProduct").once().withArgs(DBConfig, product, true, false);
+new ProductService().deletePrice(product);
+dataAccessMock.verify();
+
+// ✅ spy: verifica o requisito (e-mail enviado); tocar no interno é só efeito colateral
+const spy = sinon.spy(Emailer.prototype, "sendEmail");
+new ProductService().deletePrice(product);
+expect(spy.calledOnce).to.be.true;
+```
+
+### 6. Input realista, não `"Foo"`
+Bug de produção aparece em input específico e surpreendente. Use Faker/Chance pra gerar dado que
+se parece com produção; suba pra property-based testing quando quiser cobrir permutações.
+
+```javascript
+// ❌ "Foo" nunca dispara o regex (sem espaço) — falso verde
+const r = addProduct("Foo", 5);
+expect(r).toBe(true);
+
+// ✅ input pseudo-real cobre paths que você não planejou
+const r = addProduct(faker.commerce.productName(), faker.random.number());
+expect(r).to.be.true;
+
+// ✅✅ property-based (fast-check): roda 100 permutações automáticas
+fc.assert(fc.property(fc.integer(), fc.string(), (id, name) => {
+  expect(addNewProduct(id, name).status).toEqual("approved");
+}));
+```
+
+### 7. Anti-flakiness: determinismo, sem sleep, dados por-teste
+- **Não durma.** Em vez de `setTimeout`, use a espera determinística do framework (`cy.wait('@route')`,
+  `waitFor`/`findBy` do testing-library, fake timers). Sleep é trade-off entre lento e flaky.
+
+```javascript
+// ❌ sleep/polling caseiro, sem timeout
+const interval = setInterval(() => { if (getByText("the lion king")) clearInterval(interval); }, 100);
+
+// ✅ espera determinística do framework
+await waitFor(() => expect(getByText("the lion king")).toBeInTheDocument());
+```
+
+- **Dados isolados por teste.** Cada caso adiciona e age só nas próprias linhas de DB. Seed global é
+  acoplamento: dois testes mutam o mesmo registro e o deploy aborta sem causa óbvia.
+
+```javascript
+// ❌ before(() => DB.AddSeedDataFromJson('seed.json'));  // o dado vive fora do teste
+// ✅ cada teste cria o que precisa: const site = await SiteService.addSite({ name: faker.... });
+```
+
+- **Stub recurso flaky/lento** (API de backend) nos testes que não são E2E — staging cai sozinho e
+  reprova seu componente que está correto; e chamada de rede deixa o teste ~20x mais lento.
+- **Selector estável**: `data-test-id`, não classe CSS. Classe muda com o visual e derruba teste de lógica.
+
+```javascript
+// ❌ expect(wrapper.find("[className='d-flex-column']").text()).toBe("0");
+// ✅ <span data-test-id="errorsLabel">{value}</span>  →  getByTestId("errorsLabel")
+```
+
+### 8. Pirâmide vs. troféu: enriqueça o portfólio, não empilhe só unit
+A pirâmide de testes (muito unit, pouco E2E) ainda vale pra muita app — mas "todo modelo está
+errado às vezes". App integração-cêntrica com pouca lógica não merece 50% do budget em unit. Combine
+o **tipo de teste ao risco real** da feature, como um investidor diversifica por análise de risco.
+O nível mais valioso e subestimado costuma ser o **component test** (o "troféu"): bate na API do
+microsserviço, usa DB real (ou in-memory), e faz stub só do que é externo (outros serviços). Testa
+o que você faz deploy, de fora pra dentro, com cobertura realista a custo razoável.
+
+### 9. Meça a *qualidade* do teste, não só a cobertura — mutation testing
+Cobertura tradicional mente: pode mostrar 100% e nenhuma função retornar o certo, porque ela mede
+linha **visitada**, não **testada** (asserção certa). É como provar trabalho mostrando carimbos no
+passaporte. Mutation testing (Stryker) **planta bugs** no código (`price === 0` vira `price != 0`)
+e roda a suíte: se os testes passam mesmo assim, o mutante "sobreviveu" — seu teste não pega aquele
+bug. Mutante morto = teste de verdade.
+
+```javascript
+// ❌ 100% de cobertura, 0% de teste — visita tudo, não verifica nada
+function addNewOrder(o) { logger.log(o); DB.save(o); Mailer.sendMail(o.assignee, "..."); return { approved: true }; }
+it("Test addNewOrder", () => { addNewOrder({ assignee: "j@x.com", price: 120 }); }); // sem expect
+```
+
+Complemente com **lint de teste** (`eslint-plugin-jest`/`-mocha`): pega teste sem asserção, teste
+skipado, título duplicado — coisas que viram "90% verde" enganoso.
+
+### 10. Garanta o contrato entre serviços — contract tests
+Microsserviço com múltiplos clientes: você muda um campo e quebra um cliente importante. O provider
+publica o typing da API (JSDoc/TypeScript) como pacote npm, e os consumidores ganham validação em
+tempo de build. Abordagem mais rica: **PACT** — o cliente define as expectativas, grava num "broker",
+e o servidor roda contra elas em todo build, pegando o mismatch cedo no CI.
+
+### 11. Cubra os 5 resultados possíveis de um fluxo (foco no de fora, não no como)
+Ao planejar o que verificar numa ação (ex.: chamada de API), cubra os cinco resultados observáveis
+de fora: **(1) Response** (dados, schema, status HTTP) · **(2) Novo estado** (dado publicamente
+acessível mudou) · **(3) Chamadas externas** (SMS, e-mail, cobrança) · **(4) Filas de mensagem**
+(mensagem publicada) · **(5) Observabilidade** (erro tratado, log/métrica certos — o "usuário ops"
+também é usuário).
+
+## Checklist (qualquer "sim" é um tell a corrigir)
+
+- [ ] Algum nome de teste não tem as 3 partes (o quê / cenário / esperado)?
+- [ ] Tem teste sem separação AAA, ou com asserção imperativa (`if`/`forEach`/flag) em vez de `expect`?
+- [ ] Algum teste verifica método privado / internal que não é requisito?
+- [ ] Tem mock checando "foi chamado com esses args" em vez de stub/spy de comportamento?
+- [ ] Input é `"Foo"`/`123` em vez de dado realista (Faker) ou property-based onde compensa?
+- [ ] Tem `setTimeout`/sleep esperando async em vez de espera determinística do framework?
+- [ ] Tem seed global de DB em vez de dado criado por-teste?
+- [ ] Selector de teste de lógica depende de classe CSS em vez de `data-test-id`?
+- [ ] Tem snapshot externo gigante em vez de inline curto (3–7 linhas) e focado?
+- [ ] Existe teste sem nenhuma asserção (cobre linha, não testa nada)?
+- [ ] A confiança vem só de "% de cobertura", sem mutation testing nos caminhos críticos?
+- [ ] A estratégia é "só unit" mesmo numa feature integração-cêntrica?
+
+## Tabela de decisão (use X quando Y)
+
+| Quando Y | Use X | O que pega / o que custa |
+|---|---|---|
+| Lógica pura, sem IO (cálculo, classificação, validação) | **Unit test** (black-box, API pública) | Pega bug de lógica; barato e rápido, mas cobre pouca área por teste |
+| Feature que cruza camadas de **um** serviço (rota → lógica → DB) | **Component test** (API real, DB real/in-memory, stub do externo) | Pega bug de integração interna com cobertura realista; melhor ROI no backend |
+| Risco de mismatch de schema **entre** serviços/clientes | **Contract test** (typing publicado ou PACT) | Pega quebra de contrato no CI, antes do deploy; setup extra no provider+consumer |
+| Validar fluxo ponta-a-ponta (front + backend real) | **E2E**, mas só **1–10** sobre staging production-like | Pega falha de deploy e de integração front↔back; caro, frágil, lento — use com parcimônia |
+| Sanidade de produção / dev | **1 smoke E2E** que percorre o site map | ROI altíssimo, pega falha funcional/rede/empacotamento; não substitui teste funcional |
+| Input com muitas permutações possíveis | **Property-based** (fast-check) sobre o unit | Acha o caso de borda que você não imaginou; roda N vezes, um pouco mais lento |
+| Você quer saber se os testes **prestam** (não só cobrem) | **Mutation testing** (Stryker) nos caminhos críticos | Mede teste real (mutante morto); setup ~igual ao de cobertura, execução mais cara |
+| Componente UI (lógica + alguns filhos, tamanho razoável) | **Render realista** (`mount`) + query por `data-test-id` | Pega bug que dado certo não chega na UI; evite shallow + chamar método interno |
+| Recurso externo lento/instável num teste não-E2E (API backend) | **Stub** (nock/Sinon) | Mata flakiness e ~20x de lentidão; nunca stube o que você está justamente testando |
+| Async com tempo desconhecido (animação, fetch) | Espera **determinística** do framework (`waitFor`, `cy.wait`, fake timers) | Determinismo sem sleep; sleep troca lentidão por flakiness |
+| Asserção em markup que muda muito | **Inline snapshot** curto (3–7 linhas) sobre o trecho que importa | Self-explanatory e estável; snapshot externo gigante quebra por espaço/CSS |
+
+## O que NÃO testar
+
+- **Métodos privados / internals** — cobertos implicitamente pela API pública; testá-los só cria
+  testes frágeis e custo de manutenção.
+- **Como (interação interna)** quando o que importa é o **resultado observável** — não verifique
+  "chamou o DAL com esses args"; verifique o efeito que é requisito.
+- **100% de tudo** — 100% desloca o foco dos caminhos críticos pros cantos exóticos; ~80% é o número
+  de bolso (Fowler: "nos 80s ou 90s altos"), e o limiar é contextual (A380 ≠ site de cartoon).
+- **Detalhe gráfico (HTML/CSS) em teste de lógica** — separe UI de funcionalidade; asserte dado contra
+  dado.
+- **Documento gigante via snapshot externo** que ninguém leu — 1000 motivos pra falhar, zero sinal útil.
+- Às vezes vale **dropar um teste** e trocar confiabilidade por agilidade — o Golden Rule manda manter
+  a suíte enxuta e deliciosa de manter, não exaustiva por exaustão.
+
+---
+*Fonte: [goldbergyoni/javascript-testing-best-practices](https://github.com/goldbergyoni/javascript-testing-best-practices) — Yoni Goldberg. Exemplos de código extraídos do repositório real.*

package/knowledge/governance/risk-matrix.md

@@ -0,0 +1,56 @@
+---
+sla:
+  P0: imediato
+  P1: menos de 4h
+  P2: menos de 24h
+  P3: menos de 1 semana
+categorias:
+  - { categoria: Dívida técnica, dono: architect, mitigador: dev, escalacao: nexus-master, severidade: P2 }
+  - { categoria: Regressão de qualidade, dono: qa, mitigador: dev, escalacao: nexus-master, severidade: P1 }
+  - { categoria: Vulnerabilidade de segurança, dono: qa, mitigador: devops, escalacao: nexus-master, severidade: P0 }
+  - { categoria: Estouro de custo, dono: pm, mitigador: nexus-master, escalacao: nexus-master, severidade: P1 }
+  - { categoria: Perda ou corrupção de dados, dono: data-engineer, mitigador: devops, escalacao: nexus-master, severidade: P0 }
+  - { categoria: Escopo furado (invenção), dono: po, mitigador: pm, escalacao: nexus-master, severidade: P2 }
+  - { categoria: Dependência externa instável, dono: devops, mitigador: architect, escalacao: nexus-master, severidade: P2 }
+  - { categoria: Acessibilidade/UX quebrada, dono: ux-design-expert, mitigador: dev, escalacao: nexus-master, severidade: P2 }
+  - { categoria: Falha de release, dono: devops, mitigador: dev, escalacao: nexus-master, severidade: P0 }
+  - { categoria: Requisito ambíguo, dono: analyst, mitigador: pm, escalacao: nexus-master, severidade: P3 }
+---
+
+# Matriz de risco — donos, mitigadores e SLA
+
+> A FONTE ÚNICA é o frontmatter YAML acima; a tabela abaixo é derivada dele. Um risco sem dono é um
+> risco órfão — o validator `risk-ownership` confere que todo dono, mitigador e escalação existe no
+> roster. O SLA amarra a severidade ao tempo de resposta esperado.
+
+## SLA por severidade
+
+| Severidade | Resposta esperada |
+|---|---|
+| P0 | imediato |
+| P1 | menos de 4h |
+| P2 | menos de 24h |
+| P3 | menos de 1 semana |
+
+## Categorias (10)
+
+| Categoria | Dono (detecta) | Mitigador (corrige) | Escalação | Severidade |
+|---|---|---|---|---|
+| Dívida técnica | architect | dev | nexus-master | P2 |
+| Regressão de qualidade | qa | dev | nexus-master | P1 |
+| Vulnerabilidade de segurança | qa | devops | nexus-master | P0 |
+| Estouro de custo | pm | nexus-master | nexus-master | P1 |
+| Perda ou corrupção de dados | data-engineer | devops | nexus-master | P0 |
+| Escopo furado (invenção) | po | pm | nexus-master | P2 |
+| Dependência externa instável | devops | architect | nexus-master | P2 |
+| Acessibilidade/UX quebrada | ux-design-expert | dev | nexus-master | P2 |
+| Falha de release | devops | dev | nexus-master | P0 |
+| Requisito ambíguo | analyst | pm | nexus-master | P3 |
+
+## Como usar
+
+- **Dono** monitora a categoria e levanta a bandeira quando o risco aparece (ele detecta, não
+  necessariamente conserta).
+- **Mitigador** executa a correção sob o SLA da severidade.
+- **Escalação** entra quando o SLA estoura ou o mitigador não converge — o `nexus-master` medeia.
+- Um risco P0 (segurança, dados, release) para a linha: imediato, sem exceção.

package/knowledge/integration/mcp-server-selection-matrix.md

@@ -0,0 +1,235 @@
+---
+id: mcp-server-selection-matrix
+domain: integration
+agents: [devops]
+when: "ao escolher e adicionar um servidor MCP ao roster do projeto"
+---
+
+# Matriz de seleção de servidor MCP — o melhor por categoria do NEXUS
+
+Adicionar um MCP ao roster é decisão de DevOps (@devops detém a authority exclusiva de add/remove/configure de
+MCP). O erro comum é tratar isso como "instala o primeiro que aparece na busca": pega-se um fork community não
+mantido, com token de admin, write habilitado, sem nunca ter rodado o servidor uma vez fora do agente. Este pack dá
+a **matriz canônica** (melhor servidor por categoria), o critério de escolha e o passo **obrigatório** de validar
+com o **MCP Inspector** antes de qualquer `mcp add`.
+
+## O problema
+
+Os tells de um roster de MCP mal montado:
+
+1. **Fork community no lugar do oficial** — pega `asifdotpy/github-mcp-server` em vez de `github/github-mcp-server`;
+   `bkeys73/mcp-supabase` em vez de `supabase-community/supabase-mcp`. O awesome-mcp-servers lista 142 servidores de
+   database e 188 de busca — a maioria é redundante. Sem marcar o oficial, escolhe-se ruído.
+2. **Servidor arquivado tratado como vivo** — `@modelcontextprotocol/server-github`, `server-postgres`,
+   `server-brave-search`, `server-puppeteer`, `server-gitlab` etc. **foram arquivados** para `servers-archived`. Quem
+   copia config de tutorial velho instala um servidor morto.
+3. **Write por padrão** — adiciona supabase ou github sem `--read-only`. O agente ganha poder de `DROP TABLE` ou
+   `git push --force` num servidor que devia só ler.
+4. **Credencial com escopo total** — um Personal Access Token `repo` + `admin:org` colado no env quando o agente só
+   precisava ler issues. Token vaza no log, no handoff, no histórico do shell.
+5. **Nunca validou** — adiciona o MCP direto no roster e descobre no meio de uma story que o servidor não sobe, pede
+   prompt em vez de expor tools, ou expõe 60 tools quando precisava de 5.
+6. **Transport errado** — usa stdio (local, processo filho) onde queria HTTP remoto gerenciado, ou vice-versa, e
+   depois briga com Docker/credencial que nem precisava existir.
+
+## O conhecimento
+
+### Critério de escolha (a ordem importa)
+
+```text
+1. Oficial > community          # mantido pelo vendor/steering group, não por um fork
+2. Manutenção ativa             # commits recentes, releases, issues respondidas
+3. Read-only por padrão         # write só quando a categoria exige e a story justifica
+4. Credencial de escopo mínimo  # o menor token/role que faz a tool funcionar
+5. Transport adequado           # stdio p/ local-dev, HTTP/SSE p/ remoto gerenciado
+6. Validado no MCP Inspector    # GATE — nunca entra no roster sem passar por aqui
+```
+
+"Oficial" tem um significado concreto: os **reference servers** vivem em `modelcontextprotocol/servers` e são
+mantidos pelo steering group; os servidores de vendor (`github/`, `supabase-community/`, `microsoft/`, `exa-labs/`,
+`brave/`) são o canônico de cada produto. Tudo o mais é community — útil, mas só depois de descartar o oficial.
+
+### Transport: stdio vs HTTP/SSE
+
+| Transport | Como roda | Quando usar | Custo |
+|---|---|---|---|
+| **stdio** | processo filho local (`npx`/`uvx`/binário) | dev local, filesystem/git, controle total da credencial | você gerencia processo + token |
+| **HTTP/SSE (remoto)** | endpoint hospedado pelo vendor, OAuth | quando o vendor oferece remoto gerenciado (GitHub, Exa, Supabase) | sem Docker/atualização manual, mas depende do vendor |
+
+Regra prática: **filesystem, git e qualquer coisa que toque o disco do dev → stdio sempre.** Serviço de nuvem com
+remoto oficial (GitHub `https://api.githubcopilot.com/mcp/`, Exa `https://mcp.exa.ai/mcp`, Supabase
+`https://mcp.supabase.com/mcp`) → prefira o **HTTP remoto** e evite manter Docker/binário/atualização à mão.
+
+### A matriz — melhor MCP por categoria do NEXUS
+
+| Categoria NEXUS | Servidor canônico | Origem | Transport | Escopo de tools | Agente consumidor |
+|---|---|---|---|---|---|
+| Dados / DB | `supabase-community/supabase-mcp` | oficial (vendor) | stdio (npx) **ou** HTTP remoto | `execute_sql`, `apply_migration`, branches, projetos | @data-engineer, @dev |
+| Browser / QA | `microsoft/playwright-mcp` (`@playwright/mcp`) | oficial (Microsoft) | stdio (npx) | navegar, snapshot a11y, click/type, screenshot | @qa, @ux-design-expert |
+| DevOps / Git remoto | `github/github-mcp-server` | oficial (GitHub) | HTTP remoto **ou** stdio/Docker | issues, PRs, repos, actions (por toolset) | **@devops apenas** |
+| Filesystem | `@modelcontextprotocol/server-filesystem` | reference (steering group) | stdio (npx) | leitura/escrita de arquivo com paths permitidos | @dev |
+| Git local | `mcp-server-git` | reference (steering group) | stdio (uvx) | ler/buscar/manipular repo Git local | @dev |
+| Fetch / web → markdown | `mcp-server-fetch` | reference (steering group) | stdio (uvx) | buscar URL e converter p/ LLM | @analyst, @dev |
+| Memória / knowledge graph | `@modelcontextprotocol/server-memory` | reference (steering group) | stdio (npx) | grafo de conhecimento persistente | @analyst |
+| Busca web | `exa-labs/exa-mcp-server` **ou** `brave/brave-search-mcp-server` | oficial (vendor) | HTTP remoto (Exa) / stdio (Brave) | `web_search`, research, crawling | @analyst |
+
+> **Authority:** adicionar/remover/configurar QUALQUER linha desta matriz é operação **exclusiva do @devops**. O
+> servidor `github-mcp-server` em particular só é consumido pelo @devops — push, PR e gerência de repo remoto não
+> saem de outro agente.
+
+### Config: ruim → bom
+
+#### Filesystem — escopo de paths
+
+```jsonc
+// RUIM — sem restrição: o agente lê/escreve qualquer lugar do disco
+{ "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/"] }
+
+// BOM — paths permitidos explícitos; o servidor recusa fora deles
+{ "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem",
+    "/Users/me/projeto/docs", "/Users/me/projeto/packages"] }
+```
+
+#### Git local — repo escopado
+
+```jsonc
+// RUIM — server arquivado + sem repo definido
+{ "command": "npx", "args": ["-y", "@modelcontextprotocol/server-git"] }   // não existe mais
+
+// BOM — reference server oficial via uvx, repo explícito
+{ "command": "uvx", "args": ["mcp-server-git", "--repository", "/Users/me/projeto"] }
+```
+
+#### Supabase — read-only e projeto escopado
+
+```jsonc
+// RUIM — write habilitado, sem escopo de projeto, token inline com todos os escopos
+{ "command": "npx", "args": ["-y", "@supabase/mcp-server-supabase"],
+  "env": { "SUPABASE_ACCESS_TOKEN": "sbp_live_admin_total_no_codigo" } }
+
+// BOM — --read-only (queries rodam como Postgres read-only user),
+//       --project-ref escopa só o projeto, token vem do ambiente
+{ "command": "npx",
+  "args": ["-y", "@supabase/mcp-server-supabase", "--read-only", "--project-ref=abcdef123456"],
+  "env": { "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}" } }
+```
+
+`--read-only` faz `execute_sql`/`apply_migration` rodarem como usuário Postgres read-only; `--project-ref` remove as
+tools de nível de conta (`list_projects`, `list_organizations`). Em CI, prefira o remoto:
+`https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true`.
+
+#### GitHub — read-only, toolsets e remoto
+
+```jsonc
+// RUIM — server arquivado, token com escopo total no código
+{ "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"],   // arquivado
+  "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_token_repo_admin_org_workflow" } }
+
+// BOM (stdio/binário) — oficial, read-only, só os toolsets necessários, token do ambiente
+{ "command": "github-mcp-server", "args": ["stdio", "--read-only", "--toolsets=repos,issues,pull_requests"],
+  "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}" } }
+```
+
+```http
+# BOM (remoto HTTP) — sem Docker, OAuth, headers de hardening
+# endpoint:
+https://api.githubcopilot.com/mcp/
+X-MCP-Readonly: true
+X-MCP-Toolsets: repos,issues,pull_requests
+```
+
+#### Playwright — perfil isolado e capabilities mínimas
+
+```jsonc
+// RUIM — perfil persistente (estado vaza entre sessões), todas as caps
+{ "command": "npx", "args": ["@playwright/mcp@latest", "--caps=vision,pdf,devtools"] }
+
+// BOM — --isolated (sessão descartável, sem storage state vazando), só a cap que a story pede
+{ "command": "npx", "args": ["@playwright/mcp@latest", "--isolated", "--caps=vision"] }
+```
+
+#### Busca — chave de escopo mínimo
+
+```jsonc
+// RUIM — server de busca arquivado
+{ "command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search"],   // arquivado
+  "env": { "BRAVE_API_KEY": "chave_colada" } }
+
+// BOM (Brave) — server oficial do vendor, chave do ambiente
+{ "command": "npx", "args": ["-y", "@brave/brave-search-mcp-server"],
+  "env": { "BRAVE_API_KEY": "${BRAVE_API_KEY}" } }
+
+// BOM (Exa) — remoto, sem setup local; ou local com --tools restrito
+{ "url": "https://mcp.exa.ai/mcp" }
+// local, só as tools que a story usa:
+{ "command": "npx", "args": ["-y", "exa-mcp-server", "--tools=web_search_exa,crawling"],
+  "env": { "EXA_API_KEY": "${EXA_API_KEY}" } }
+```
+
+### O GATE obrigatório: validar no MCP Inspector ANTES do roster
+
+**Nenhum servidor entra no roster sem passar pelo Inspector.** O Inspector (`@modelcontextprotocol/inspector`) sobe o
+servidor isolado, mostra as tools/resources reais e prova que a credencial funciona — antes de você confiar nele
+dentro de um agente.
+
+```bash
+# 1. CLI mode — lista as tools que o servidor REALMENTE expõe (não as que o README promete)
+npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list
+
+# 2. Passa a credencial via -e e roda o binário/comando real do servidor
+npx @modelcontextprotocol/inspector -e SUPABASE_ACCESS_TOKEN=$SUPABASE_ACCESS_TOKEN \
+  npx -y @supabase/mcp-server-supabase --read-only --project-ref=abcdef123456
+
+# 3. UI mode — abre o cliente em :6274 (proxy em :6277) p/ inspeção interativa
+npx @modelcontextprotocol/inspector node build/index.js
+```
+
+Sinais de **reprovação** no Inspector (não adicione ao roster):
+- Mostra **"(N prompts)" em vez de "(N tools)"** — o servidor subiu mas **falhou autenticação** (credencial não
+  chegou). Corrija o env antes de prosseguir.
+- A lista de tools não bate com o esperado, ou expõe write quando você passou `--read-only`.
+- O servidor não sobe, trava ou exige um runtime que o projeto não tem.
+
+Só depois de uma `tools/list` limpa, com a credencial certa e o escopo correto, o @devops roda o `mcp add`.
+
+### Hardening — não-negociável
+
+- **Read-only por padrão.** DB, git remoto e qualquer servidor com poder de escrita entram com `--read-only` (ou
+  `X-MCP-Readonly: true`). Write só quando a story exige e o @devops aprova.
+- **Escopo de credencial mínimo.** O menor PAT/role que faz a tool funcionar. GitHub: só os escopos que você se
+  sente confortável em dar ao agente; nunca `admin:org` "por garantia". Supabase: `--project-ref` para tirar as
+  tools de conta.
+- **Credencial via ambiente, nunca inline.** Token vai em `${VAR}`/env, não colado no JSON que vira commit/handoff.
+- **Tools/toolsets enxutos.** `--toolsets` (GitHub), `--tools` (Exa), `--caps` (Playwright) reduzem a superfície:
+  menos tools expostas = menos vetor de erro/abuso.
+- **Sessão descartável onde fizer sentido.** Playwright `--isolated` evita vazar storage state entre stories.
+
+## Checklist
+
+Antes de o @devops rodar `mcp add`, todo "não" é um bloqueio:
+
+- [ ] É o servidor **oficial** da categoria (reference do steering group ou do vendor), não um fork community?
+- [ ] O servidor **não está arquivado** (não é `@modelcontextprotocol/server-{github,postgres,brave-search,...}`)?
+- [ ] Tem **manutenção ativa** (commits/releases recentes)?
+- [ ] O **transport** é o certo (stdio p/ local; HTTP remoto quando o vendor oferece gerenciado)?
+- [ ] Está em **read-only** por padrão (ou a escrita é justificada pela story)?
+- [ ] A **credencial é de escopo mínimo** e vem do **ambiente** (`${VAR}`), nunca inline?
+- [ ] O conjunto de **tools/toolsets/caps** está enxuto p/ o que a story precisa?
+- [ ] Foi **validado no MCP Inspector** — `tools/list` limpa, mostra "(N tools)" e não "(N prompts)"?
+- [ ] É consumido pelo **agente certo** (ex.: `github-mcp-server` só @devops)?
+
+## Tabela de decisão
+
+| Situação | Decisão |
+|---|---|
+| Preciso ler/escrever arquivos do projeto | `@modelcontextprotocol/server-filesystem` (stdio) com paths permitidos explícitos |
+| Preciso operar um repo Git **local** | `mcp-server-git` (uvx, stdio) com `--repository` escopado |
+| Preciso de issues/PRs/repo **remoto** no GitHub | `github/github-mcp-server` — remoto HTTP ou stdio, **read-only + toolsets**, **só @devops** |
+| Preciso consultar/migrar banco Supabase | `supabase-community/supabase-mcp` com `--read-only` + `--project-ref` |
+| Preciso de QA de browser / screenshot | `microsoft/playwright-mcp` (`--isolated`, `--caps` mínimo) |
+| Preciso de busca web p/ pesquisa | Exa (`https://mcp.exa.ai/mcp`, remoto) ou Brave (oficial, stdio) com `--tools` restrito |
+| Preciso buscar URL e virar markdown | `mcp-server-fetch` (uvx, stdio) |
+| Preciso de memória persistente entre sessões | `@modelcontextprotocol/server-memory` (stdio) |
+| Encontrei só um fork community da categoria | Procure o oficial primeiro; se não existir, **só** após Inspector + hardening + aprovação @devops |
+| O tutorial manda usar `@modelcontextprotocol/server-{github,postgres,...}` | **Recuse** — está arquivado; use o servidor do vendor |
+| O Inspector mostra "(N prompts)" | **Não adicione** — credencial falhou; corrija o env e revalide |

package/knowledge/marketing/copy-que-converte.md

@@ -0,0 +1,43 @@
+# Copy que converte — clareza antes de esperteza
+
+Copy de conversão não é escrever bonito. É fazer a pessoa parar, entender a oferta em três segundos e
+ter uma razão para agir agora. O adjetivo empilhado ("inovador, revolucionário, único") é o que se
+escreve quando não se tem uma promessa de verdade.
+
+## A anatomia que converte
+
+1. **Headline com promessa específica.** O que a pessoa ganha, em número quando possível. "Economize 6
+   horas por semana" vence "produtividade revolucionária". Especificidade é credibilidade.
+2. **Subheadline / abertura.** A razão de continuar lendo — o custo de não resolver ou a facilidade de resolver.
+3. **Corpo que antecipa objeções.** Cada "sim, mas..." do leitor (é caro? é difícil? funciona pra mim?)
+   respondido antes de ele fechar a página.
+4. **Prova.** Número, caso, garantia, redução de risco — o que torna o "sim" seguro.
+5. **Um call-to-action, sem atrito.** Uma ação clara, com o menor esforço possível.
+
+## Clareza vence esperteza
+
+A pessoa tem de entender na primeira leitura. Trocadilho que precisa ser explicado já falhou. A copy
+esperta premia o ego do autor; a copy clara converte. Na dúvida, corte a piada e diga a coisa.
+
+## Específico vence superlativo
+
+| Fraco (superlativo) | Forte (específico) |
+|---|---|
+| "resultados incríveis" | "3 leads a mais por dia" |
+| "solução revolucionária" | "configura em 5 minutos, sem código" |
+| "atendimento de excelência" | "resposta em menos de 2 horas, sempre" |
+
+## Objeções: a venda mora nos "sim, mas..."
+
+Liste o que o leitor pensa antes de fechar e responda cada um NA copy:
+- "é caro" → mostre o retorno / o custo de não ter.
+- "é complicado" → mostre a facilidade / o tempo de setup.
+- "não funciona pra mim" → mostre o caso parecido com o dele.
+- "e se eu me arrepender" → garantia / risco reduzido.
+
+## Anti-padrões
+
+- Adjetivo empilhado sem promessa concreta.
+- Dois CTAs — dividem a decisão; nenhum — não vende.
+- Prometer o que o produto não entrega — copy é contrato; overpromise é churn.
+- Esconder o preço/oferta atrás de esperteza — clareza fecha, mistério cansa.