OKF Bundle Manager: Machine Discoverability no WordPress

“Como a gente entrega o conhecimento de um site WordPress para agentes de IA sem obrigar cada máquina a separar conteúdo, menu, widget, script e comentário do editor?” Essa pergunta definiu o projeto do plugin OKF Bundle Manager.

Nós precisávamos de um método consistente, confiável e eficiente para gerar um bundle OKF (pacote organizado de conhecimento) em ecossistemas WordPress, sem colocar uma API dinâmica no caminho de cada leitura e sem disputar qual página seria a “fonte oficial” (entre diversos outros imbróglios).

O Open Knowledge Format (OKF), é um projeto iniciado pela Google Cloud. Você pode saber mais diretamente da fonte, clicando aqui. O foco é basicamente organizar informações em formato markdown que possam ser fácilmente identificadas e consumidas por sistemas que operam com Inteligência Artificial.

Foi justamente após conhecer o OKF e pensar sobre como poderíamos prover dados para máquinas de forma mais fácil e organizada possível, que projetamos, codamos, testamos e validamos o plugin dentro da infraestrutura real do site.

Reforçando: Estamos aqui falando exclusivamente de instalações em WordPress.

Chamamos essa frente de machine discoverability optimization (otimização da descoberta por máquinas).

O foco é melhorar a forma como agentes, fetchers (sistemas que buscam um recurso sob demanda) e crawlers (robôs de rastreamento) encontram uma representação limpa do conteúdo.

Trabalhamos para reduzir o custo (esforço) de processamento de dados.

Então vem comigo e vamos detalhar como o Plugin OKF Bundle Manager funciona no nosso WordPress!

NOTA TÉCNICA: Todas as informações contidas aqui retratam a minha experiência e o meu método de trabalho, você é o total responsável por alterações no seu site ou no site de seus clientes. Nos responsabilizamos exclusivamente em parcerias formalizadas por contratos. Em dúvida, visite o Aviso Legal.

O que é o OKF Bundle Manager

O OKF Bundle Manager é um plugin proprietário para WordPress que compila o conteúdo público do site em um bundle Open Knowledge Format v0.2. Cada recurso vira um arquivo Markdown com frontmatter YAML (cabeçalho estruturado), URL da fonte HTML, descrição, data de geração e estado do documento.

O bundle fica disponível em nosso índice OKF v0.2. Ele reúne um mapa de páginas e artigos, seguido pelos arquivos individuais que uma máquina pode buscar somente quando precisar de mais contexto.

Essa entrega conversa diretamente com a prontidão para agentes: uma máquina precisa encontrar o conteúdo certo, entender qual fonte é canônica e receber uma representação que não dependa da interface visual feita para pessoas.

Por que o Bundle é Estático

Uma página HTML serve ao visitante, isto é, ela carrega navegação, identidade visual, CSS, componentes, scripts e outros elementos importantes para a experiência humana, mas que podem virar ruído (fricção) quando um agente de IA quer apenas o conteúdo limpo editorial.

Poderíamos entregar esse conteúdo com foco em máquinas por uma API REST dinâmica (interface que processa uma resposta a cada requisição). O problema é que cada nova consulta acionaria PHP e, dependendo da rota, banco de dados.

Em hospedagens compartilhadas (realidade da maioria das PMEs no Brasil – nossos clientes), colocar processamento de origem em toda leitura automatizada não é o método mais eficiente, e poderíamos comprometer o funcionamento da infraestrutura.

Outro caminho possível seria publicar um arquivo /pagina.md ao lado de cada URL HTML ou redirecionar o visitante para Markdown. Mas, nós recusamos essa arquitetura porque ela cria uma segunda URL concorrendo com a fonte humana e complica a governança do canonical.

Logo, a decisão foi simples: o WordPress escreve e o agente lê o arquivo. O trabalho de compilação acontece quando existe uma mudança editorial, não a cada acesso ao bundle.

Como o Plugin Funciona

O fluxo do nosso plugin OKF Bundle Manager mantém controle humano antes da escala. Ele começa com diagnóstico, passa por um piloto comparável e só então libera o processamento em lote.

Dentre os recursos do plugin, temos:

1. Diagnóstico: o plugin confere requisitos, diretórios, extensões PHP e condições de publicação. Um semáforo vermelho bloqueia piloto e lote.
2. Piloto: um conteúdo é convertido primeiro. O painel apresenta HTML e Markdown para uma confirmação humana antes de ampliar a execução.
3. Lote: o inventário elegível é compilado de forma cadenciada, com limite operacional e registro de status por ID.
4. Manutenção: ao salvar um post, o plugin recompila somente aquele ID. Rascunho ou lixeira remove o arquivo correspondente. Um cron semanal verifica diferenças.
5. Publicação: os arquivos ficam em uploads/okf/ e são servidos em URLs públicas sob /okf/.
6. Discovery: a sinalização só aparece quando o bundle está saudável e o site permite indexação pública.

Parser do Conteúdo Útil

A fonte primária que define a base do conteúdo markdown é o post_content cru do WordPress. Quando (se) o corpo útil fica abaixo do limite mínimo, o plugin pode consultar o HTML canônico da mesma página e restringir a leitura a <main> ou <article>.

Então, o parser (extrator e conversor) remove comentários Gutenberg, shortcodes, navegação, scripts, estilos e iframes; preservando títulos, parágrafos, listas, links, ênfases, citações, código e texto alternativo de imagens.

A saída, como já mencionei, é Markdown UTF-8, sem ler opções do tema nem JSON interno de page builder.

Compilador OKF v0.2

Cada página ou artigo recebe frontmatter com o tipo do recurso, título, descrição, URL pública e referência explícita ao HTML canônico. Este é um recorte do contrato:

---
type: Article
title: "Título do conteúdo"
resource: https://felipecferreira.com.br/slug/
generated: { by: process:okf-bridge, at: 2026-08-28T21:00:00Z }
status: stable
sources:
  - id: canonical-html
    resource: https://felipecferreira.com.br/slug/
---

O índice separa Pages, Articles e Concepts. Um hash SHA-256 evita reescrever arquivo idêntico, reduzindo trabalho desnecessário no disco e no cache.

Entrega, Headers e Discovery

Os arquivos são entregues como text/markdown. O servidor também comunica como cada recurso deve ser interpretado:

A descoberta usa mais de uma placa. O robots.txt informa o caminho permitido, o llms.txt aponta para o índice e o HTML publica rel="alternate" type="text/markdown". Essa relação aponta para o bundle, não para um arquivo Markdown inventado a partir de cada slug.

Essa redundância também encontra apoio em observação de mercado. Num censo de acessos publicado pela DEJAN AI, o bundle OKF recebeu 2.841 requisições no conjunto total, contra 157 do llms.txt. Entre agentes da OpenAI, foram 11 acessos ao bundle, sendo seis do ChatGPT-User, e nenhum ao llms.txt.

O próprio levantamento delimita o resultado: são requisições registradas no servidor, não citações nem aparições em respostas. Para nós, o aprendizado é usar sinais complementares e medir cada um pelo trabalho que realmente executa.

Painel OKF BM

No wp-admin, o menu OKF BM abre o OKF Bundle Manager. As abas Diagnóstico, Piloto, Lote, Descoberta e Infra L2 (L2 vem da nossa padronização com foco em sistemas, para saber mais, clique aqui) mostram o estado do processo sem oferta comercial na interface e sem esconder falhas atrás de uma execução automática.

A tela de plugins também oferece o atalho Abrir painel. Esta própria documentação será a página pública associada ao plugin, enquanto a operação permanece restrita a administradores.

Três Camadas, Três Trabalhos

O OKF Bundle Manager não substitui tudo o que o site já faz para máquinas, nem substitui qualquer trabalho sério de SEO!

Nós separamos integração, descoberta e conhecimento para evitar que um componente acumule responsabilidades incompatíveis.

O plugin vive entre a aplicação e a entrega estática. Dentro do nosso Protocolo L0 a L7, o WordPress compila na camada de aplicação (L4), enquanto o servidor entrega os arquivos na camada de origem e edge (borda da rede, L2).

O HTML Continua Canônico

O bundle é uma via de leitura para máquinas, não um novo permalink editorial.

Quando alguém recebe uma citação ou decide visitar a fonte, a referência deve continuar levando para a página HTML.

• Canonical: a URL HTML aparece no YAML e no header HTTP do Markdown.
• Noindex: os arquivos OKF não devem ocupar espaço no índice de busca (importantíssimo).
• Sitemap: o Yoast continua listando apenas as fontes humanas no sitemap XML.
• Sem Redirect: não criamos um 301 de /pagina.md quando o slug HTML muda, porque essa URL irmã não faz parte do contrato.

O Yoast também permanece responsável pelo canonical, pelo Open Graph e pelo grafo de JSON-LD para SEO, GEO e AEO.

O OKF acrescenta uma representação para agentes sem tomar o lugar dessas estruturas.

Projetado, Codado, Testado e Validado por Nós

Nós não encontramos no wordpress.org um compilador OKF v0.2 com o contrato que esta arquitetura WordPress precisava: silo independente do tema, arquivos estáticos, confirmação humana, proteção contra duplicidade e trava de piloto para hospedagem compartilhada.

Isso não significa que nenhum plugin do mercado trabalhe Markdown ou descoberta para IA.

Significa apenas que este conjunto de decisões precisava ser tratado como sistema, não como um snippet colado no tema nem como uma rota dinâmica reprocessada a cada acesso.

Então precisávamos colocar a mão na massa, passando por:

1. Projeto: especificação de execução no próprio repositório do plugin, com limites, critérios de aceite e rollback.
2. Código: módulos separados para diagnóstico, parser, compiler, lote, hooks, headers, discovery e administração.
3. Teste: regressões puras no Docker local, homologação em staging privado e validação posterior no live.
4. Entrada no Live: discovery ligada no site público somente depois de o índice responder corretamente. O staging permanece sem anunciar o bundle.

Na validação de 28 de agosto de 2026, o índice público reuniu 120 itens, sendo 14 páginas e 106 artigos. O lote do acervo restante terminou com zero erros, o GET /okf/index.md respondeu 200 e os headers de noindex e canonical atravessaram a infraestrutura até a resposta pública.

Esses são dados do nosso próprio site, não números de cliente!

Eles comprovam a operação do bundle nesta infraestrutura. Não comprovam citação em ChatGPT, Perplexity ou qualquer outro motor generativo.

Infraestrutura em Operação

O OKF Bundle Manager não foi validado num WordPress vazio de demonstração. Ele roda no site público, em conjunto com cache de origem, proxy no edge, SEO técnico e outros componentes que continuam donos de suas próprias responsabilidades.

Hoje, a origem entrega cache e o Cloudflare repassa corretamente X-Robots-Tag e Link. O caminho /okf/ ainda aparece como DYNAMIC no edge.

Ligar uma Cache Rule é uma decisão opcional de infraestrutura, não requisito escondido do plugin.

O que o Plugin Não é

O nome técnico não pode esconder os limites do produto. O OKF Bundle Manager:

• não substitui o HTML, o sitemap XML, o JSON-LD, o robots.txt ou o llms.txt;
• não promete ranking, citação, resposta de IA ou crescimento de tráfego;
• não cria uma versão .md concorrente para cada slug humano;
• não publica conteúdo privado, protegido por senha, rascunho ou marcado como noindex pelo Yoast;
• não é um ZIP público, um plugin gratuito nem um listing do wordpress.org.

Ele é uma peça da nossa abordagem de machine discoverability optimization. Cloudflare, SEO e GEO, política de crawlers, API REST e governança editorial continuam existindo fora dele.

Estado do Produto e Disponibilidade

A versão atual é a 0.1.0. O plugin está ativo no live e a discovery pública foi ligada em 28 de agosto de 2026. O hardening (endurecimento e observação em produção) permanece em execução até 4 de setembro de 2026, com acompanhamento de erros PHP e comportamento do bundle.

Por isso, não tratamos o código como pronto e congelado. O parser, a operação de cache e o manual de infraestrutura continuam recebendo ajustes controlados.

Novas versões serão registradas em changelog.

O OKF Bundle Manager é proprietário, não está disponível para download público e não pode ser instalado hoje em um site de terceiro. Talvez exista uma distribuição pública ou gratuita no futuro, mas não há promessa nem data.

Quando um projeto exige esse tipo de arquitetura, o plugin entra como parte do método e da infraestrutura que avaliamos em uma parceria de consultoria, não como produto isolado que resolve sozinho a descoberta por máquinas.

Referências

DEJAN AI: censo de acessos a robots.txt, llms.txt e OKF.

llms.txt: proposta de arquivo para descoberta e orientação de agentes.

Felipe C Ferreira: índice público OKF v0.2, arquivo llms.txt, política pública de crawlers.