Documentação do COGO

O COGO são três faces sobre uma só lógica: um visualizador web para todos, um servidor MCP para os seus agentes, e uma CLI para usuários avançados — tudo o mesmo binário Go único.

Face	Para quem	Como
Visualizador web	todos	cogo serve -http :8080 → navegador (Vault · Frescor · Pack · Grafo · Revisão · Guard · Veracidade)
MCP	seu agente (Claude, Codex, Cursor, Gemini…)	cogo serve (stdio) ou /mcp via HTTP — ferramentas: pack search open capture verify archive restore remove guard xray
CLI	usuários avançados	cogo add · pack · search · stale · verify · lint · agents

Como a cor é computada

confidence = min( evidence , freshness , weakest dependency , contradiction )

Uma nota é verde só quando nada a puxa para baixo: evidência observada, uma verificação que passou, fresca, todas as suas dependências verdes e nenhuma contradição. Cada cor carrega o seu color_reason, para você sempre poder auditar por que ela terminou daquele jeito.

• A evidência define o teto: observada (um log, um comando, um teste, um arquivo) pode chegar ao verde; relatada ou inferida trava no amarelo; sem evidência significa vermelho.
• O frescor decai por tipo: um comando dura 30 dias; uma decisão de arquitetura, 180.
• Editar uma nota muda a cor — esse é o ponto. O visualizador recomputa a cor ao vivo enquanto você digita: adicione evidência observada e ela fica mais verde; mude a afirmação e ela volta a “precisa de reverificação”; pressione verify (“eu verifiquei”) e ela fica verde.

Anatomia de uma nota

---
id: fisherboy-redis-hostname
type: bug                 # decision|bug|runbook|architecture|constraint|command|mistake
project: fisherboy
evidence:
  - kind: direct_log      # observed → can reach green
    ref: "api log 2026-06-27T14:03Z: connect OK to redis:6379"
check:
  test: "read the worker's effective env; probe connectivity to fisherboy-redis:6379"
  status: not_run         # passed | failed | not_run
last_verified: 2026-06-27
depends_on: [fisherboy-redis-topology]
# ---- computed by COGO · do not edit ----
confidence: yellow
color_reason: "observed evidence but the check has not passed"
---

## Claim
The worker probably fails because it can't resolve Redis's internal hostname.

O vault em Markdown é a única fonte da verdade: portátil, diffável, e sobrevive à ferramenta. Todo o resto é um cliente fino ou um cache reconstruível.

O visualizador web

As abas: Vault (suas notas, cada uma com sua cor), Frescor (o que está expirando, com um botão de revalidar), Pack (montar as notas de um tema em um bloco de contexto colorido para colar em uma IA), Grafo (como as notas se relacionam), Revisão (links quebrados, notas expiradas, contradições), Guard e Veracidade.

Tudo o que é operacional vive no menu kebab do visualizador — sem terminal: Conexões MCP (emitir/revogar tokens nomeados por app, com expiração e um modo somente leitura), Lixeira (restaurar ou apagar para sempre), Auditoria MCP (quem chamou qual ferramenta, quando, de qual IP), Raízes de evidência (contra qual pasta a evidência de cada projeto é resolvida), Exportar (backup) (o vault inteiro como um zip, sem segredos), Instruções para agentes (gerar o AGENTS.md/CLAUDE.md que ensina o protocolo ao seu agente) e Configurações · Modelo de IA.

Guard, passo a passo

O Guard responde a uma pergunta: “este turno do modelo está me empurrando?”

1. Declare seu mandato (uma vez): seu objetivo e suas linhas vermelhas (“não peço demissão sem outra oferta assinada”). Ele é armazenado no vault. Sem um mandato, manipulação e persuasão legítima são indistinguíveis — o COGO então só nomeia técnicas, sem veredito.
2. Cole o turno (e a conversa anterior, uma mensagem por linha: U: você, M: o modelo) → uma radiografia colorida: verde — sem sinais; amarelo — persuasão presente, ou ela toca a sua linha vermelha; vermelho — há mecânica, ou há recibos.
3. Recibos são o superpoder: como o COGO vê a transcrição, quando o modelo nega o que disse (“eu nunca te disse para pedir demissão”) o COGO encontra o turno em que ele DE FATO disse e mostra as duas citações, lado a lado. O gaslighting deixa de ser a sua palavra contra a dele.
4. Cada tática detectada chega com suas perguntas críticas e sua contramedida — o motor não censura o modelo: ele inocula você. Ele mostra; você decide.

A ontologia por trás: 108 técnicas de manipulação destiladas de seis disciplinas ofensivas — persuasão (Cialdini, Kahneman), interrogatório policial e militar (técnica Reid, Army FM 2-22.3, Scharff), negociação (Harvard, Voss), coerção e reforma do pensamento (Lifton, Biderman), manipulação emocional (gaslighting, DARVO, FOG) e retórica/propaganda (Frankfurt, Grice, Walton) — cada uma com sua fonte real, como ela aparece em um chat, e sua contramedida.

A regra de ferro

Nenhum modelo dita “você está sendo manipulado”. Os dentes são determinísticos (marcadores, recibos, trajetória); os modelos apenas propõem — e cada proposta é verificada contra o texto literal ou descartada. Com um modelo conectado, aparecem dois níveis opcionais: propostas estruturais (padrões que nenhum dicionário vê) e o steelman adversarial — outro modelo argumentando deliberadamente o lado que o turno não te mostrou. O quadro teórico está em docs/fundamento-teorico.md.

Veracidade: sólido, ou fumaça?

O gêmeo do Guard. Onde o Guard pergunta “está me empurrando?”, a aba Veracidade (ferramenta MCP xray) pergunta “esta resposta se sustenta?”. Cole a resposta de um modelo e o COGO a radiografa frase por frase, deterministicamente, sem nenhum modelo: ele mede o compromisso (hesitado ou fortemente afirmado), a evidência (observada, relatada, ou nenhuma) e se é falseável (uma opinião vestida de fato). Uma afirmação forte e sem base sai vermelha; uma sólida com evidência observada, melhor. Documento de design: docs/motor-veracidad.md.

A CLI

cogo init                 # create a vault
cogo add nota.md          # validate, compute the color, store (stdin if no file)
cogo pack "redis"         # build a colored context for a topic (degrades red)
cogo search "worker"      # list: color · id · summary (no bodies)
cogo stale                # what is expired or about to expire
cogo verify <id>          # "I checked it": revalidate and re-color
cogo lint                 # broken links, expired notes, contradictions (if a model is set)
cogo agents --claude      # generate the CLAUDE.md/AGENTS.md that teaches an agent the protocol
cogo serve -http :8080    # web viewer + MCP server over HTTP
cogo serve                # MCP server over stdio

Acessórios opcionais (desativados por padrão)

O COGO é 100% determinístico e standalone sem nada disto. Cada acessório é habilitado por variável de ambiente e nunca toca o núcleo:

Acessório	Habilitado com	Para
Modelo de IA (OpenRouter, Ollama, DeepSeek…)	COGO_LLM_BASE_URL + COGO_LLM_MODEL (ou Configurações na GUI)	detectar contradições entre notas + os níveis opcionais do Guard
Juiz forte independente	COGO_LLM_STRONG_BASE_URL + COGO_LLM_STRONG_MODEL	para que o steelman do Guard não compartilhe o cérebro com o proponente
Limpeza via Anonimal	ANONIMAL_URL	manter segredos/PII fora do vault
Login Lockatus (OIDC)	AUTH_MODE=federado	federar com a Suíte Escriba

Nota

O detalhe completo vive no repositório: o manual para iniciantes, o guia de deploy completo (cada variável, backup, hardening) e os documentos de design dos motores de veracidade e de autonomia.

Ver no GitHub