Your docs are already the bundle: /okf migrate

Every knowledge format asks the same thing on day 0: rewrite what you have. You already wrote the docs. They are sitting in a docs/ folder, or a wiki export, or a pile of ADRs someone kept honest for three years. The format wants concepts, frontmatter, an index, a log. So adoption turns into a migration project, and migration projects lose to the sprint.

okf 1.7.0 adds /okf migrate to the agent skill, and it takes the other side of that trade. Your docs become the bundle, and not one word of them changes.

The verb that rewrote your docs

Until now the skill had one door in, produce, and produce distills. That is its job: read code, docs, or what lives only in people's heads, and author concepts out of them. Point it at a wiki and it does exactly what it says, which is summarize.

That was the wrong door for the commonest case. Aim a distiller at documentation that is already the knowledge and you get a paraphrase of your own words back. The docs were not raw material. They were the thing. We shipped a verb that treated them as input, and the fix is not a better prompt: it is a second door with a different contract.

migrate keeps every word

/okf migrate docs/

That is the whole step. The skill reads your directory, writes frontmatter onto each file, adds the reserved files OKF expects, and stops. The contract it holds itself to is exact: every concept, with its frontmatter block stripped back off, is byte-identical to the file it came from. Not "substantially preserved." Identical, as a check that can fail.

Everything migrate is allowed to touch is additive. It adds a type (the one field OKF requires), a title and description pulled from the heading and purpose line you already wrote, a timestamp from the file's own date when it carries one. It adds a root index.md and a log.md. The body below the frontmatter is off limits.

The validator is the worklist

Migration usually means someone reading every file and deciding what to do with it. Here the executable already knows. okf validate enumerates exactly the files that are not yet legal OKF, because missing frontmatter is a hard conformance error under §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))

That list is the migration plan, and the pass is done when it reports zero. The agent is not guessing at scope or grepping for candidates; it works a list the tool produced and re-runs it to know when to stop. Judgment stays where it belongs, on choosing a small type vocabulary and deciding which files are worth a tag. The bookkeeping stays with the CLI.

Point any verb at a folder that is not a bundle yet and the skill offers the same door on its own, rather than marching you through the errors.

Your links were already the graph

Here is the part that pays for the whole exercise. OKF never asks you to declare a graph. Files are nodes, and plain Markdown links are edges. Which means every time someone wrote see the [runbook](ops/runbook.md) in the last three years, they were drawing an edge and did not know it.

Migrate does not create those links. It makes them legible. The graph you get on day 0 is the one your team already drew, one link at a time, for free. Frontmatter lands, and a directory you have been maintaining by hand becomes something you can serve, search, and walk.

okf lint will even rank the hubs: the documents everyone links to and nobody ever marked as important. That ranking is worth reading precisely because no one authored it. It fell out of how your team actually reaches for things, which makes it a description of your docs rather than a decision about them.

Day 1: the other three verbs compound

Migrate is the on-ramp, not the destination. Once the bundle exists, the rest of the skill has something to work with, and this is where the day-0 exercise starts paying rent.

search answers questions instead of reading everything. Retrieval goes map, then finder, then only the winning bodies, so answering "why did we pick this queue?" costs a fraction of a docs dump. Your docs were always searchable with grep. They were not answerable.

lint turns absence into a worklist. A link pointing at a concept nobody wrote is not a broken link in OKF; it is demand, ranked by how many concepts asked for it. Migration surfaces that backlog on day 1, out of the links you already had.

Now produce has a real job. Not rewriting what exists, but filling the holes the graph just exposed, from the code or from the people who never wrote it down. This is the verb doing what it is good at, aimed at raw material instead of finished prose.

maintain keeps it from rotting. When the code moves, the bundle moves with it, and the agent writes back what it learned while consuming. That loop is the entire difference between documentation and folklore.

What migration does not buy you

Migrate makes your docs legal OKF and navigable. It does not make them true. A concept that was wrong before is now a wrong concept with tidy frontmatter, and no amount of validation will say otherwise, because conformance and correctness are different questions on purpose.

It also refuses to tidy as it goes. If a file is really two concepts wearing one filename, migrate flags it and moves on rather than splitting it behind your back; that is a curate decision, made by you, later. The one thing worse than docs nobody trusts is docs nobody trusts that got silently rearranged.

What migration buys is the ability to see: what links to what, what is thin, what is stale, what everyone references and nobody wrote. That is available on day 0, from the docs you already have, for the cost of one command.