inkeep/open-knowledge

OpenKnowledge — orientação para agentes

OpenKnowledge (OK) é uma plataforma de colaboração markdown-CRDT exposta via MCP. Esta habilidade é a fonte única de orientação para agentes OK. Cada regra abaixo é OBRIGATÓRIA, a menos que indicado de outra forma. A profundidade está em references/*.md — um nível de profundidade; carregue uma referência quando sua tarefa surgir.

A versão da habilidade acompanha @inkeep/open-knowledge-server. cat ~/.ok/skill-state.yml mostra o que está instalado. ok seed precisa de @inkeep/open-knowledge >= 0.4.0; se ele gerar erro unknown command, execute npm install -g @inkeep/open-knowledge.

Configuração (ainda não conectado?). Se as ferramentas mcp__open-knowledge__* não estiverem disponíveis no seu cliente, este projeto não está configurado nesta máquina — consulte references/setup.md para a escada de implantação (aprovar .mcp.json → CLI ok start → aplicativo de desktop opcional) e o guia de início rápido canônico.

Resumo — o caso 90%

1. Leituras: exec("cat …") para um documento, exec("ls -A …") para um diretório (padrões de pasta + menu de modelos), exec("grep …") para busca literal, search para recuperação ranqueada. Read / Grep nativos apenas em código-fonte (.ts / .py / …), nunca em .md / .mdx no escopo.
2. Escritas: write({ document: { path, content } }) para um documento novo ou substituição completa; edit({ document: { path, find, replace } }) para uma busca/substituição no corpo; edit({ document: { path, frontmatter } }) para um merge-patch no frontmatter (null exclui uma chave). delete({ document }) remove, move({ from, to }) move/renomeia. A busca/substituição no corpo é apenas no corpo. Passe um summary de uma linha (≤80 caracteres, resultado visível ao usuário) em cada escrita de conteúdo.
3. Visualização: toda resposta de leitura/escrita traz um previewUrl apenas com a rota (/#/<doc>, sem host:porta). Abra o navegador uma vez no início da sessão. Não use preview_screenshot para confirmar edições — a resposta da ferramenta é a confirmação. Contrato completo de multi-host: references/preview.md.
4. Guias de fluxo de trabalho: workflow({ kind: 'ingest' | 'research' | 'consolidate' | 'discover' }) retorna um guia procedural, não dados. Use-o quando o trabalho se encaixar na camada.
5. Perguntas diretas: uma pergunta de negócio simples ("quais clientes…", "o que decidimos sobre…") roteia para search / exec + uma resposta no chat com citações — nenhuma palavra-chave "research" necessária. Persista apenas quando for durável + multi-documento + já não coberto, e ofereça primeiro. Consulte references/corpus-qa.md.
6. Criar ou melhorar uma habilidade ("escrever/fazer uma habilidade", "melhorar esta habilidade", "transformar isto em uma habilidade"): PARE e invoque a habilidade open-knowledge-write-skill — ela é responsável pela escolha do escopo (projeto vs global), pelo contrato SKILL.md, avaliação e instalação; não improvise a partir desta habilidade. Crie através do destino skill (write({ skill })), nunca um documento .ok/skills/… bruto. Nunca leia, diffe ou edite as projeções instaladas em .claude/skills/ · .cursor/skills/ · .codex/skills/ · .opencode/skills/ · .agents/skills/ — install as gera e as sobrescreve na próxima sincronização; elas NÃO são fonte da verdade.

Índice de ferramentas — 19 ferramentas (roteador; as descrições das ferramentas MCP carregam o contrato completo de cada ferramenta)

• Leituras — exec (principal; cat/ls/grep/find/head/tail/wc/sort/uniq/cut somente leitura + enriquecimento de frontmatter/backlinks/histórico; um comando ou um pipe, não um shell), search (BM25 ranqueado + recenticidade), history (versões de um documento), links (kind: backlinks|forward|dead|orphans|hubs|suggest, ou um array para uma auditoria em uma chamada), skills (encontrar + ler habilidades: omita name para LISTAR todas as habilidades entre Projeto + Global, passe name para LER uma — endereçada por name+scope, NUNCA por caminho), config (configuração resolvida), palette (formulários de criação nativos em markdown + iniciadores de html preview + tokens de tema; palette({ components }) para schemas JSX), preview_url (URL de visualização do navegador sob demanda), share_link (link de compartilhamento baseado em GitHub; somente leitura, erro quando não há remoto GitHub).
• Escritas — quatro verbos CRUD nativos, polimórficos sobre document / folder / template / skill / asset (passe EXATAMENTE UM destino, aninhado sob sua chave de endereço): write (criar/sobrescrever; write({ skill: { name, description, body, scope? } }) cria uma habilidade → .ok/skills/<name>/SKILL.md, um Rascunho até install), edit (busca/substituição no corpo OU merge-patch no frontmatter; sem asset), delete (remover), move (mover/renomear, reescreve referenciadores; uma habilidade também aceita scope/toScope para mover Projeto↔Global — o histórico é redefinido, re-install). A saída espelha a chave de destino da entrada; o envelope de visualização (previewUrl, warning) permanece no nível superior. Mais install (a etapa de Rascunho → Instalado para uma skill — projeta-a em seus editores; execute após write({ skill })), checkpoint (versão nomeada), e restore_version (reverter). O frontmatter de uma pasta é de formato aberto e apenas para si (NÃO cascateia); modelos são com o que novos documentos começam. Criando/melhorando uma habilidade? invoque open-knowledge-write-skill (Resumo #6), não improvise.
• Conflitos — conflicts (kind: list|content), resolve_conflict (escrever uma resolução + commit; destrutivo). Consulte references/conflict-resolution.md.
• Fluxo de trabalho — workflow (kind: ingest|research|consolidate|discover; guias processuais, não dados). Consulte references/workflow-guides.md.

Autocorreção em uso incorreto: restrições que o JSON Schema não pode expressar ("exatamente um destino", "find precisa de um replace", corpo-XOR-frontmatter) retornam isError: true com uma forma corretiva de uma linha. Leia-a e tente novamente com essa forma; não adivinhe.

Ferramentas NÃO no MCP OK (do seu host): preview_start, preview_screenshot, WebFetch, WebSearch, Read / Grep / Glob / Edit nativos. A regra STOP rege quais você pode usar em markdown no escopo.

PARE — ferramentas nativas em .md / .mdx no escopo

Roteie toda leitura e escrita de markdown no escopo através das ferramentas MCP do OK — nunca use as ferramentas de arquivo nativas do seu host. Edit / sed / Write direto em markdown no escopo ignora o CRDT e perde a atribuição do agente no repositório sombra; leituras nativas pulam frontmatter, backlinks, atividade do repositório sombra e histórico git do projeto que o OK retorna para cada arquivo correspondente. Quando este espaço de trabalho tiver o OpenKnowledge MCP configurado, não use ferramentas de arquivo nativas em caminhos markdown dentro do diretório de conteúdo. A proibição cobre toda racionalização comum:

• Read / Grep / Glob nativos em .md / .mdx no escopo — o caso original.
• Bash ls / Bash find / Bash cat em diretórios contendo markdown no escopo — use exec("ls -A …") / exec("find … -name '*.md'") / exec("cat …"). Nativos retornam apenas nomes; exec retorna frontmatter, contagens de backlinks e atividade recente. -A mostra entradas ocultas (.ok/, .okignore) sem o ruído ./...
• Padrões Glob que visam markdown (**/*.md, specs/**, reports/**, docs/**) — use exec com find ou exec("ls -A <dir>").
• Despachar o subagente Explore / uso geral para exploração pesada de markdown — subagentes usam ferramentas nativas internamente e ignoram OK. Faça exploração de markdown você mesmo via exec / search. Subagentes permanecem apropriados para exploração de código-fonte.
• Read / Grep nativos em markdown no escopo dentro de .ok/ — .ok/ está no escopo; trate seus .md / .mdx como qualquer outro arquivo KB.
• ls / cat / find em .ok/skills/ para descobrir ou ler uma habilidade — .ok/skills/ é estado interno opaco; habilidades são endereçadas por name+scope, não por caminho. Use a ferramenta skills (omita name para listar entre Projeto + Global, passe name para ler uma); nunca navegue por caminhos .ok/skills/....

Visibilidade da ferramenta MCP — não ver exec NÃO é a saída de emergência. A fiação MCP varia por cliente (Claude Code, Cursor, Codex, Windsurf, VS Code). Os rótulos do servidor são definidos pelo usuário; as ferramentas podem não aparecer como símbolos de nível superior chamados exec. Se o OpenKnowledge estiver registrado como um servidor MCP aqui, roteie leituras de markdown através de seu exec / search via invocação MCP documentada do seu cliente (incluindo qualquer fluxo genérico de "chamar ferramenta MCP"). O registro é o teste, não a visibilidade de símbolo de nível superior.

Sua lista inicial de ferramentas NÃO é exaustiva — execute a descoberta de ferramentas antes de concluir que o MCP está faltando. Alguns clientes (notadamente Codex) diferem ferramentas MCP atrás de uma etapa lazy de tool_search / descoberta de ferramentas, então mcp__open-knowledge__* está ausente do conjunto inicial de ferramentas e só aparece após você pesquisar por ele. Ausência da lista visível significa "ainda não descobri", NÃO "não está registrado". Se você não vir as ferramentas, seu primeiro movimento é executar a descoberta de ferramentas / tool_search do seu cliente para open-knowledge (ou exec / search / write) — não infira indisponibilidade a partir da lista inicial.

Saída de emergência. Read / Grep / Glob nativos em .md / .mdx são permitidos apenas quando, após executar a descoberta de ferramentas (acima), nenhum servidor OpenKnowledge MCP estiver registrado para este projeto, ou imediatamente após você realmente ter invocado uma chamada MCP e ela ter falhado — então inicie uma frase visível ao usuário com OpenKnowledge MCP indisponível:. "Não registrado" é uma conclusão que você só pode alcançar após a descoberta de ferramentas ter retornado vazia — nunca a partir da lista inicial de ferramentas sozinha. Nunca use a saída porque você pulou o caminho MCP do seu cliente, não viu exec como uma ferramenta de nível superior, não executou descoberta de ferramentas, ou racionalizou que a habilidade não era necessária.

Código-fonte e arquivos não-markdown (.ts, .py, package.json, …): Read / Grep / Glob nativos sempre.

Leituras — exemplos

• Ler um arquivo: exec("cat <path>.md") — conteúdo + enriquecimento completo.
• Listar um diretório: exec("ls -A <dir>") — frontmatter por filho, contagens recursivas de markdown, documento mais recentemente atualizado por subdiretório, title/description/tags da própria pasta + templates_available. Prefira -A em vez de ls simples.
• Busca literal: exec("grep -rn <termo> <dir> | head -5") — correspondências + enriquecimento nos arquivos correspondentes.
• Busca ranqueada: search({ query }) — boost de título + BM25 no corpo + recenticidade; use ao escolher o melhor documento, não ao listar toda ocorrência.

Escrita

Chame write / edit assim que tiver conteúdo (roteie através do MCP conforme a regra STOP).

Persista incrementalmente — a base de conhecimento É seu checkpoint (OBRIGATÓRIO). Em qualquer tarefa de várias etapas ou longa — uma varredura de pesquisa, uma síntese de múltiplas fontes, um lote de documentos — escreva o trabalho concluído no KB à medida que finalizar cada unidade: por seção, por fonte, por documento. Nunca segure descobertas finalizadas apenas em seu contexto esperando por uma única escrita final no final. Um limite de taxa, travamento ou compactação de contexto no meio da tarefa descarta tudo que ainda não foi escrito; o trabalho já persistido sobrevive, e você retoma lendo o documento de volta. Crie o documento de destino cedo (esqueleto + frontmatter), então edit cada seção à medida que ela se consolida.

Passe um summary em cada escrita de conteúdo (RECOMENDADO) — uma nota de mudança de uma linha (≤80 caracteres) visível ao usuário que se torna a entrada da linha do tempo. Recorra a estrutura visual (Callout, mermaid, tabela, html preview) onde ela transmite o ponto melhor que prosa; chame palette enquanto rascunha. Avisos de escrita, criação MDX, mecânica de exclusão/movimentação e criação visual: references/writing.md + references/components-and-visuals.md + references/media-and-assets.md.

Fundamentação — toda afirmação factual precisa de uma fonte (OBRIGATÓRIO)

Documentos da base de conhecimento são artefatos factuais. Cada afirmação deve ser rastreável, e a fonte tem que viver dentro da base de conhecimento, não flutuar na web pública.

• A base de conhecimento é fonte da verdade — circuito fechado. Fontes externas não são citadas para a web ao vivo; elas são trazidas via ingest, então citadas localmente. Uma URL [fonte](https://...) nua dentro de um documento KB não é uma citação finalizada — é um TODO que diz "esta fonte ainda precisa ser ingerida." A cadeia só funciona se cada folha for um documento local.
• Toda afirmação factual DEVE citar sua fonte no ponto da afirmação. Nenhuma especulação sem fonte.
• Fontes web para documentos KB → busque a página (host WebFetch / WebSearch), então ingest-a como um documento local, então cite o caminho local: [nome da fonte](./caminho/para/fonte.md) (o documento local carrega a URL em source_url:). Inline [fonte](URL) é uma conveniência de chat, não uma do KB.
• Contagens auto-buscadas. Quando VOCÊ buscou uma URL para fundamentar uma afirmação que vai para o KB, essa busca aciona ingest exatamente como um compartilhamento de usuário — não rebaixe para citação inline de URL porque a busca foi iniciada pelo agente.
• Referências cruzadas internas → link markdown padrão para o documento OK com a afirmação autoritativa; esse documento deve citar suas próprias fontes (cadeias terminam em documentos locais preservados).
• Se você não tiver evidência: execute uma busca na web e ingest-a, OU marque inline (TODO: precisa de fonte), OU não escreva a afirmação. Não fabrique. Especulação sem fonte apodrece em conhecimento tribal não rastreável.

Vinculação — links markdown padrão (OBRIGATÓRIO)

Vincule toda frase nominal que nomeia outro documento — [texto](./caminho/relativo.md) — e vincule liberalmente. Todo link deve resolver para um documento que exista quando você terminar (uma referência direta na mesma passagem que você cria depois na passagem é aceitável; para uma que genuinamente não existirá, deixe a menção como prosa simples + uma tarefa rastreada). Nunca use crase em um link (`[texto](./foo.md)` é um bug) e nunca use HTML <a>. Leia brokenLinks em toda resposta de write/edit: [] significa que todos os links resolvem; uma lista populada nomeia cada href quebrado + reason (no-such-doc / no-such-file / unresolvable) — corrija-os em um edit subsequente. links({ kind: "dead" }) é a auditoria de estado final autoritativa (o sublinhado vermelho do editor é tolerante a slugs e mente, então confie na ferramenta). Fontes web externas NÃO são links inline no corpo (consulte Fundamentação). Conjunto completo de regras + nota legada [[Page]]: references/linking.md.

Pastas, frontmatter, modelos

Todo .md / .mdx precisa de frontmatter YAML — title + description obrigatórios, tags recomendado. Dois mecanismos de pasta opt-in, aninhados: frontmatter de pasta (<pasta>/.ok/frontmatter.yml — propriedades de formato aberto da própria pasta; apenas para si, NÃO cascateia para filhos) e modelos de pasta (<pasta>/.ok/templates/ — arquivos .md / .mdx usados como ponto de partida ao criar documentos dentro daquela pasta). Ferramenta de paleta para tokens de tema. Detalhes completos: references/folders-and-templates.md.

Nomenclatura de documentos — sem espaços, sem slugs, sem extensão

• Nomeie documentos como caminho/relativo/do-documento.md: caminho relativo à raiz do OK, sem extensão no nome do documento, hífens entre palavras, sem barras finais. O documento minha-coisa.md é endereçado como minha-coisa.
• Caminhos de pasta são a parte do diretório de um caminho de documento. Criar um documento em pesquisa/bigquery/analise-de-logs cria implicitamente as pastas pesquisa/ e pesquisa/bigquery/, cada uma com seu próprio frontmatter de pasta.

Estado da habilidade & cache

Para cada habilidade carregada no contexto, isso é automaticamente manipulado, mas você pode verificar/esvaziar manualmente. A ferramenta history mostra o que você fez. restore_version reverte em cache também.

Compartilhamento — GitHub Issues como backbone

Um link de compartilhamento OK é um link GitHub Issue que o servidor do destinatário entende. Veja references/sharing.md para o contrato completo.

---

Permanece em references/* — não repita aqui: references/setup.md · references/preview.md · references/writing.md · references/components-and-visuals.md · references/media-and-assets.md · references/linking.md · references/folders-and-templates.md · references/corpus-qa.md · references/workflow-guides.md · references/conflict-resolution.md · references/sharing.md.