Seus docs já são o bundle: /okf migrate

Todo formato de conhecimento pede a mesma coisa no dia 0: reescreva o que você tem. Você já escreveu os docs. Eles estão numa pasta docs/, ou num export de wiki, ou numa pilha de ADRs que alguém manteve honesta por três anos. O formato quer conceitos, frontmatter, um índice, um log. Aí a adoção vira um projeto de migração, e projeto de migração perde para a sprint.

A okf 1.7.0 traz o /okf migrate para a agent skill, e ele pega o outro lado dessa troca. Seus docs viram o bundle, e nenhuma palavra deles muda.

O verbo que reescrevia os seus docs

Até agora a skill tinha uma porta de entrada, o produce, e o produce destila. É o trabalho dele: ler código, docs, ou o que só existe na cabeça das pessoas, e escrever conceitos a partir disso. Aponte para uma wiki e ele faz exatamente o que promete, que é resumir.

Essa era a porta errada para o caso mais comum. Aponte um destilador para uma documentação que já é o conhecimento e você recebe de volta uma paráfrase das suas próprias palavras. Os docs não eram matéria-prima. Eles eram a coisa. Nós entregamos um verbo que os tratava como entrada, e a correção não é um prompt melhor: é uma segunda porta, com outro contrato.

O migrate mantém cada palavra

/okf migrate docs/

É o passo inteiro. A skill lê o seu diretório, escreve frontmatter em cada arquivo, adiciona os arquivos reservados que o OKF espera, e para. O contrato que ela cobra de si mesma é exato: cada conceito, com o bloco de frontmatter removido de volta, é byte a byte idêntico ao arquivo de origem. Não "essencialmente preservado". Idêntico, como um teste que pode falhar.

Tudo que o migrate pode tocar é aditivo. Ele adiciona um type (o único campo que o OKF exige), um título e uma descrição tirados do cabeçalho e da frase de propósito que você já escreveu, um timestamp da própria data do arquivo quando ela existe. Adiciona um index.md raiz e um log.md. O corpo abaixo do frontmatter é território proibido.

O validador é a lista de trabalho

Migração costuma significar alguém lendo cada arquivo e decidindo o que fazer com ele. Aqui o executável já sabe. O okf validate enumera exatamente os arquivos que ainda não são OKF legal, porque frontmatter faltando é erro duro de conformidade no §9:

$ okf validate docs
OKF v0.1 conformance — docs
  concepts: 3   index.md: 0   log.md: 0
  ✗ ERROR  architecture.md: missing YAML frontmatter
  ✗ ERROR  ops/runbook.md: missing YAML frontmatter
  ✗ ERROR  setup.md: missing YAML frontmatter
  ✗ non-conformant (3 error(s))

Essa lista é o plano de migração, e o trabalho acaba quando ela reporta zero. O agente não está chutando escopo nem greppando por candidatos; ele trabalha uma lista que a ferramenta produziu e a roda de novo para saber quando parar. O julgamento fica onde deve estar, em escolher um vocabulário pequeno de type e decidir quais arquivos merecem uma tag. A contabilidade fica com a CLI.

Aponte qualquer verbo para uma pasta que ainda não é bundle e a skill oferece essa mesma porta sozinha, em vez de te arrastar pelos erros.

Os seus links já eram o grafo

Aqui está a parte que paga o exercício inteiro. O OKF nunca pede que você declare um grafo. Arquivos são nós, e links Markdown comuns são arestas. O que significa que toda vez que alguém escreveu veja o [runbook](ops/runbook.md) nos últimos três anos, essa pessoa estava desenhando uma aresta sem saber.

O migrate não cria esses links. Ele os torna legíveis. O grafo que você tem no dia 0 é o que o seu time já desenhou, um link por vez, de graça. O frontmatter entra, e um diretório que você vinha mantendo na mão vira algo que dá para servir, buscar e percorrer.

O okf lint ainda ranqueia os hubs para você: os documentos para os quais todo mundo linka e que ninguém nunca marcou como importantes. Esse ranking vale a leitura justamente porque ninguém o escreveu. Ele caiu do jeito como o seu time realmente busca as coisas, o que faz dele uma descrição dos seus docs, e não uma decisão sobre eles.

Dia 1: os outros três verbos compõem

O migrate é a rampa de entrada, não o destino. Uma vez que o bundle existe, o resto da skill tem com o que trabalhar, e é aqui que o exercício do dia 0 começa a pagar aluguel.

O search responde perguntas em vez de ler tudo. A recuperação vai pelo mapa, depois pelo localizador, depois só pelos corpos vencedores, então responder "por que escolhemos essa fila?" custa uma fração de um despejo de docs. Os seus docs sempre foram grepáveis. Respondíveis, não.

O lint transforma ausência em lista de trabalho. Um link apontando para um conceito que ninguém escreveu não é link quebrado no OKF; é demanda, ranqueada por quantos conceitos pediram por ele. A migração traz esse backlog à tona no dia 1, a partir dos links que você já tinha.

Agora o produce tem trabalho de verdade. Não reescrever o que existe, e sim preencher os buracos que o grafo acabou de expor, a partir do código ou das pessoas que nunca escreveram aquilo. É o verbo fazendo o que ele faz bem, apontado para matéria-prima em vez de prosa pronta.

O maintain evita o apodrecimento. Quando o código anda, o bundle anda junto, e o agente escreve de volta o que aprendeu enquanto consumia. Esse ciclo é a diferença inteira entre documentação e folclore.

O que a migração não compra

O migrate torna os seus docs OKF legal e navegáveis. Não os torna verdadeiros. Um conceito que estava errado antes agora é um conceito errado com frontmatter arrumado, e nenhuma validação vai dizer o contrário, porque conformidade e correção são perguntas diferentes de propósito.

Ele também se recusa a arrumar no caminho. Se um arquivo é na verdade dois conceitos vestindo um nome só, o migrate sinaliza e segue, em vez de dividir pelas suas costas; isso é decisão de curate, sua, depois. A única coisa pior que docs em que ninguém confia é docs em que ninguém confia e que foram silenciosamente rearranjados.

O que a migração compra é a capacidade de enxergar: o que linka para o quê, o que está raso, o que está velho, o que todo mundo referencia e ninguém escreveu. Isso está disponível no dia 0, a partir dos docs que você já tem, pelo custo de um comando.