---
name: knowledge
description: Router de conhecimento unificado. Classifica pergunta por tipo e encaminha para fonte certa (Hub granular/NLM/Context7/CC memory/Supabase/Desk CRM/Git). v3.1.0
---

# /knowledge — Router Unificado v3.1.0

> **Reescrita 13-04-2026:** v2.2.0 usava modelo Familia A/B com NLM restrito a "externo".
> v3.0.0 classifica por tipo de pergunta (8 rotas), adiciona Hub granular
> (QR/KB/APIs/Manuais/PROCs/Troubleshooting), reclassifica NLM como referencia
> tecnica primaria, e torna Supabase complementar (nao alicerce).
> Racional: `plans/atomic-fluttering-flame.md`

## Principio

**Classificar pergunta → fonte certa.** Nao e fallback linear, nao e "Familia A depois B". E routing directo por tipo.

---

## Router principal (8 tipos)

### 1. Facto rapido (ID, path, comando, credencial)

**Sinais:** "qual e o ID de", "path para", "comando para", "porta do"

**Fontes (sequencial — parar ao primeiro hit):**
1. `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/Quick-Reference/QR-*.md`
2. `Grep` em `~/.claude/projects/*/memory/*.md` (cross-projecto)

**QR routing por keyword:**

| Keywords | Ficheiro |
|----------|----------|
| servidor, ip, porta, ssh | QR-Servidores.md |
| cwp, virtualhost, conta cwp | QR-CWP.md |
| site cwp, dominio cwp | QR-Sites-CWP.md |
| easypanel, servico, container | QR-EasyPanel.md |
| desk, tabela, campo bd, relacao | QR-Desk-BD.md |
| staff id, project id, category id | QR-IDs-Frequentes.md |
| moloni, serie, imposto, metodo | QR-Moloni.md |
| path, directorio, pasta | QR-Paths-Locais.md |
| backup, rota backup, destino | QR-Backups.md |
| sync, syncthing, rsync | QR-Sync-Ficheiros.md |
| script, claudedev | QR-Scripts.md |
| credencial, password, api key | QR-Credenciais.md |
| rank math, seo wp-cli | QR-RankMath-WP-CLI.md |
| capa, cover, podcast imagem | QR-Cover-Generator.md |
| alurin, desktop, laptop | QR-Alurin-Desktop.md |

### 2. Como funciona X / Como fazer Y (referencia tecnica)

**Sinais:** "como funciona", "como configurar", "como fazer", "melhores praticas", "tutorial", "deep dive"

**Fontes (paralelo — consolidar):**
1. **Hub Knowledge-Base** — `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Knowledge-Base/*.md` (preferir ficheiro local se existir match directo)
2. **NotebookLM** — max 2 notebooks por query (routing por tema abaixo)
3. **Hub Manuais** — `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/Manuais/**/*.md`
4. **Context7** — `resolve-library-id` → `query-docs` (para frameworks/bibliotecas com docs oficiais)
5. **CC memory cross-projecto** — `Grep` em `~/.claude/projects/*/memory/*.md`
6. **Supabase** — `search_memories(query, threshold=0.5, limit=5)` [graceful se indisponivel]

**Prioridade por tipo de tema:**
- Framework/biblioteca com docs oficiais (Next.js, React, Laravel...) → **KB local primeiro** + **Context7** + NLM
- Stack interna (CWP, Perfex, n8n...) → **NLM primeiro** (fonte mais densa para estes) + KB
- Conceito generico (design patterns, boas praticas...) → **NLM primeiro**

**NLM routing por tema (top 15):**

| Tema | Notebook | ID |
|------|----------|----|
| Claude Code, skills, hooks, plugins | Claude Code | `2876d1fe-5cea-4d98-8140-b0e1a81c6bc4` |
| CWP, servidor, hosting, virtualhost | CWP | `0ded7bd6-69b3-4c76-b327-452396bf7ea7` |
| WordPress, WP-CLI, temas, config | WordPress Config CLI | `fb2f26bd-8cb0-4d4c-bafc-4f1ebb51c51d` |
| Elementor, widgets, templates | WordPress e Elementor | `5be0d1a6-00f2-4cd9-b835-978cb7721601` |
| Seguranca WP, malware, hardening | Ciberseguranca WordPress | `5f60adfd-2435-4725-8c12-9c11c5f51d75` |
| Perfex/Desk CRM, modulos, hooks | Perfex CRM | `df4688bb-c2c0-4aba-98c1-38c3b50a353c` |
| n8n, automacoes, workflows | n8n | `f2c809b8-1cb5-4dd0-aa7e-be2cfb6704d1` |
| Marketing digital, SEO, ads, funil | Marketing Digital PT | `4c595973-ba10-420a-a3bf-e4389e424ad3` |
| AI agents, orquestracao, MCPs | AI Agents e Orquestracao | `bc480d68-5835-415e-82bc-4583f36b8c29` |
| Proxmox, VMs, clustering, HA | Proxmox | `276ccdde-6b95-42a3-ad96-4e64d64c8d52` |
| Design, branding, visual, automacao | Design Profissional | `b568b13b-0eed-48c9-b513-5c5b7ec0b102` |
| UI/UX, WCAG, acessibilidade | UI/UX Design | `081ca512-8279-4850-b2b9-dff090267482` |
| Gestao operacoes, KPIs, agencia | Gestao Operacoes | `f9dc59c2-718b-4b12-bd06-095d4bfa3e34` |
| Remotion, video programatico | Remotion | `f2b75baa-1ab1-48d3-8f7c-a6a9e516934c` |
| Obsidian, vault, Claude workflow | Obsidian + Claude | `ebee9fe1-78fd-4f85-8938-f19f3ea32131` |
| Programacao, padroes, api design | Programacao | `24947ffa-0019-448a-a340-2f4a275d2eb1` |
| Copywriting, persuasao, texto | Copywriting e Persuasao | `7b8fec17-d34f-4e3f-a8c6-8231e51f6323` |
| Video, producao, youtube | Producao de Video e Youtube | `058a896e-6c9a-4e51-ae7d-9adb2738bc5f` |
| WooCommerce, loja, produtos | Documentacao WooCommerce | `bd06acff-4b9d-44aa-b3f7-60434bbd6b49` |

> Inventario completo 65 notebooks: `~/.claude/projects/-media-ealmeida-Dados-Hub/memory/notebooklm-inventory.md`

**Hub KB: ficheiros locais densos (usar quando match directo):**

| Keywords | Ficheiro KB |
|----------|-------------|
| next.js, app router, server components | `Next.js 14_15 App Router Deep Dive.md` |
| php, laravel | `PHP 8+ e Laravel 11_12_ Pesquisa Profunda.md` |
| core web vitals, ga4, performance | `Core Web Vitals, GA4, Performance Web.md` |
| n8n, automacao | `Base-Conhecimento-n8n.md` |
| perfex crm, modulos | `Base-Conhecimento-Perfex-CRM.md` |
| remotion, video codigo | `Base-Conhecimento-Remotion-Video.md` |
| ui, ux, design systems | `Base-Conhecimento-UI-UX-Design-Systems.md` |
| tipografia, cor, web design | `Base-Conhecimento-Web-Design-Tipografia-Cor.md` |
| youtube, video producao | `Base-Conhecimento-Video-YouTube.md` |
| openrouter, modelos ai | `OpenRouter-Matrix-v1.1.md` |
| postfix, email security | `Postfix Email Security Best Practices.md` |
| wcag, acessibilidade | `Relatório Acessibilidade Web WCAG 2.2.md` |
| gestao, operacoes, agencia | `Gestao-Operacoes-Agencias-Marketing-Tecnologia.md` |

**Context7 para docs oficiais:** usar `resolve-library-id` → `query-docs` quando a pergunta e sobre uma biblioteca/framework com documentacao oficial actualizada (Next.js, React, Tailwind, Laravel, etc). Context7 tem docs mais frescos que NLM.

### 3. API / implementacao (endpoint, payload, autenticacao)

**Sinais:** "endpoint", "API de", "payload", "autenticacao", "integrar com"

**Fontes (sequencial — Read directo do ficheiro):**

| Keywords | Ficheiro em `Hub/06-Operacoes/Documentacao/APIs/` |
|----------|----------------------------------------------------|
| perfex, desk crm api | Perfex-CRM-API.md |
| cwp api, cwp endpoint | CWP-API.md |
| whatsms, sms api | WhatSMS-API.md + WhatSMS-Admin-API.md |
| paperclip api | Paperclip-API.md |
| dify api | Dify-API.md |
| bookstack api | BookStack-API.md |
| mcp desenvolvimento | MCP-Dev-Manual.md |

Se API nao listada → NLM notebook relevante + Context7.

### 4. Processo / procedimento (como fazemos X internamente)

**Sinais:** "procedimento", "como fazemos", "PROC", "workflow interno", "passo-a-passo"

**Fontes:**
1. `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/**/*.md` (38 PROCs)
2. `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/Manuais/**/*.md`

**Departamentos PROC:**

| Tema | Pasta |
|------|-------|
| Comercial, CRM, catalogo | D1-Comercial/ |
| Suporte, tickets | D2-Suporte/ |
| Contabilidade, facturas | D3-Contabilidade/ |
| RH | D4-RH/ |
| Design | D5-Design/ |
| Marketing, conteudo | D6-Marketing/ |
| Tecnologia, MCP, Claude, infra | D7-Tecnologia/ |
| Multi-departamental | Cross-Departamental/ |

### 5. Troubleshooting (erro, problema, nao funciona)

**Sinais:** "erro", "nao funciona", "problema com", "fix para", "troubleshoot"

**Fontes (paralelo):**
1. `Grep` em `/media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/Troubleshooting/*.md`
2. CC memory cross-projecto — `Grep` em `~/.claude/projects/*/memory/*.md`
3. Supabase — `search_memories(query, threshold=0.5, limit=5)` [graceful]
4. NLM notebook relevante (contexto tecnico)

### 6. Estado actual (quem, quando, quanto, aberto/fechado)

**Sinais:** nome de cliente, "#" + numero, "tarefas abertas", "horas", "facturas", "tickets"

**Fontes:** Directo ao **Desk CRM** via MCP:
- `get_tasks`, `get_projects`, `get_tickets`, `get_customers`
- `get_timesheets`, `get_invoices`, `get_estimates`

**NLM e Hub NAO entram** — nao veem estado vivo.

### 7. Decisao / historico (porque fizemos X, quando decidimos Y)

**Sinais:** "decisao", "porque fizemos", "historico de", "quando decidimos", "ultima vez que"

**Fontes (paralelo):**
1. **Supabase** — `search_memories(query, threshold=0.5, limit=8)` [graceful]
2. **CC memory cross-projecto** — `Grep` em `~/.claude/projects/*/memory/*.md`
3. **Desk CRM discussions** — `get_discussion_comments` (#31 worklogs, #32 reflexoes, #33 accoes)
4. **Git log** — `git log --oneline --grep="keyword"` nos repos relevantes

### 8. Codigo / projecto (o que mudou, como esta o repo)

**Sinais:** "changelog", "ultimo commit", "o que mudou em", "estado do repo"

**Fontes:**
1. `Read` CHANGELOG.md do projecto
2. `git log` do repo
3. CC memory do projecto especifico

---

## Classificador de pergunta (heuristica)

| Sinal | Tipo |
|-------|------|
| ID, path, porta, comando concreto | **1. Facto rapido** |
| "como funciona", "como configurar", "melhores praticas" | **2. Referencia tecnica** |
| "endpoint", "API", "payload" | **3. API** |
| "procedimento", "PROC", "como fazemos internamente" | **4. Processo** |
| "erro", "nao funciona", "problema" | **5. Troubleshooting** |
| Cliente, tarefa #N, ticket, factura, horas | **6. Estado actual** |
| "decisao", "porque", "historico", "ultima vez" | **7. Decisao/historico** |
| "changelog", "commit", "repo" | **8. Codigo** |
| **Ambiguo** | **Perguntar ao utilizador** |

---

## Formato de resposta

```markdown
## [pergunta]

**[Fonte 1]:** [excerto] _(origem especifica)_
**[Fonte 2]:** [excerto] _(origem especifica)_

**Sintese:** [consolidacao em 2-3 frases citando as fontes mais fortes]
```

Origens possiveis: `QR:ficheiro`, `NLM:notebook`, `KB:ficheiro`, `API:ficheiro`, `PROC:codigo`, `Manual:ficheiro`, `Troubleshooting:ficheiro`, `memory/projecto:ficheiro`, `Supabase:id`, `Desk CRM:task #N`, `Git:commit`

**Regra:** nunca responder sem citar fonte. Se 0 fontes, dizer explicitamente.

---

## Comandos

| Comando | Uso |
|---------|-----|
| `/knowledge [pergunta]` | Router automatico por tipo |
| `/kb [pergunta]` | Alias curto |
| `/kb-save [conteudo]` | Guardar na fonte adequada (ver abaixo) |
| `/kb-gaps` | Listar lacunas detectadas em Supabase |

---

## Gravar conhecimento (/kb-save)

| Tipo | Destino | Tool |
|------|---------|------|
| Decisao / solucao tecnica / workaround | Supabase | `save_memory` com tags `[tipo, dominio, projecto?, data]` |
| Feedback / regra estavel | CC memory | `Write` em `~/.claude/projects/*/memory/` |
| Procedimento operacional | Hub PROCs | `Write` PROC-*.md |
| Referencia rapida (ID, path) | Hub QR | `Edit` QR-*.md |
| Conhecimento externo | NotebookLM | `source_add` no notebook adequado |

---

## Deteccao de lacunas

Quando 0 hits uteis em todas as fontes consultadas para o tipo:

```javascript
mcp__memory-supabase__save_memory({
  content: `LACUNA: "${query}" — tipo ${tipo}, 0 hits`,
  tags: ["lacuna-kb", tipo, dominio]
});
```

Sugerir accao: criar PROC, actualizar QR, adicionar fonte a NLM, guardar em Supabase.

---

## Regras operacionais

1. **Classificar primeiro, consultar depois.** Nao despejar todas as fontes para todas as perguntas.
2. **Paralelismo obrigatorio** dentro de cada tipo quando ha multiplas fontes.
3. **Grep cross-projecto obrigatorio** para tipos 2, 5, 7 — `~/.claude/projects/*/memory/*.md`.
4. **Nunca responder sem citar fonte.**
5. **Max 2 notebooks NLM** por query (performance).
6. **Supabase sempre graceful** — se indisponivel ou 0 resultados, continuar com outras fontes.
7. **Estado presente = Desk CRM directo** — nunca NLM/Hub para tarefas/facturas/tickets.
8. **PT-PT sempre.**

---

## Anti-patterns

- Consultar NLM para "quantas tarefas abertas tem o projecto X" (estado vivo → Desk CRM)
- Fazer grep generico em `Hub/**/*.md` quando a pergunta e claramente sobre um QR especifico
- Consultar Supabase como unica fonte (usar como complemento, nao alicerce)
- Classificar "como funciona o nosso router /knowledge" como referencia externa (e interno → CC memory + Hub)
- Ignorar CC memory cross-projecto (harness so carrega cwd)
- Disparar 5 fontes para um facto rapido que esta num QR (sequencial, parar ao hit)

---

## Referencias

- `~/.claude/plans/atomic-fluttering-flame.md` — plano RAG-System completo
- `~/.claude/projects/-media-ealmeida-Dados-Hub/memory/feedback_knowledge-router-arquitectura.md` — decisao arquitectural
- `~/.claude/projects/-media-ealmeida-Dados-Hub/memory/notebooklm-inventory.md` — inventario 65 notebooks NLM

---

## Healing log

```jsonl
{"date":"2026-04-08","issue":"v2.0.0 tratava NotebookLM como fonte primaria para tudo","fix":"v2.1.0 router Familia A/B — NotebookLM so para externo","source":"user"}
{"date":"2026-04-08","issue":"v2.1.0 assumia FastMCP file-based (11 tools lightrag_*)","fix":"v2.1.1 restaurado LightRAG-HKU 17 tools","source":"user"}
{"date":"2026-04-13","issue":"LightRAG com 0 docs, servico sem utilidade","fix":"v2.2.0 removido LightRAG da Familia A","source":"user"}
{"date":"2026-04-08","issue":"memoria CC fragmentada por projecto","fix":"grep cross-projecto obrigatorio","source":"user"}
{"date":"2026-04-13","issue":"Supabase degradado (stats/paginacao/embeddings raw)","fix":"MCP reparado — stats, paginacao e sanitize embeddings corrigidos. 6 registos com credentials eliminados","source":"fase-2"}
{"date":"2026-04-13","issue":"v2.2.0 modelo A/B subestimava Hub e NLM para queries operacionais","fix":"v3.0.0 router por tipo (8 rotas), Hub granular (QR/KB/APIs/Manuais/PROCs/Troubleshooting), NLM referencia tecnica primaria, Supabase complementar","source":"plano RAG-System"}
{"date":"2026-04-13","issue":"v3.0.0 nao tinha routing para frameworks (Next.js foi ao notebook errado), KB local subutilizado","fix":"v3.1.0 prioridade por tipo de tema (KB local > Context7 > NLM para frameworks), 13 ficheiros KB mapeados, 4 notebooks NLM adicionados, Context7 como fonte para docs oficiais","source":"testes fase 5"}
```

---

**v3.1.0** | 13-04-2026 | KB local mapeado (13 ficheiros), Context7 para docs oficiais, prioridade por tipo de tema, 19 notebooks NLM