migrate: OKFy existing docs in place

When to use it

• A directory already holds Markdown documentation and you want it to become a bundle: a docs/ folder, a wiki export, a pile of ADRs.
• "Convert these docs", "migrate this folder", "OKFy our documentation" all route here.
• Any verb pointed at a directory that is not a bundle yet (Markdown files, but no root index.md carrying okf_version) suggests this one rather than working through the conformance errors.

The boundary with produce is the whole reason migrate exists. Produce distills sources into new concepts, which is right for code, wikis you want condensed, and knowledge that lives only in people's heads. Migrate is for documents that already are the knowledge: they survive as the concepts themselves. Turn the docs you already have into a bundle walks a real migration.

What the agent does

The rule that governs every step: bodies are sacred. Migrate never rewrites, reorders, or summarizes a body. Besides prepending frontmatter, the only edit it may make is repointing a relative link that a file move broke.

1. Inventory from the validator, not by eyeballing. okf validate <dir> --json enumerates every file missing frontmatter or type, and every malformed reserved file. That list is the worklist, and the pass is done when it reports zero.
2. Prepend frontmatter; leave the body alone. A small type vocabulary derived from what the documents are (reusing before minting, checked with okf types), title and description from each document's own heading and purpose line, timestamp from the document's own date when it carries one, and tags only where they connect concepts that type and directory do not already group.
3. Keep the topology. The directory tree is already domain knowledge, so it stays. One file is one concept by default. When a file shows split signals (two types fighting for the frontmatter, two audiences), the agent flags it for a later curate pass instead of splitting it now.
4. Add the reserved files. A root index.md whose frontmatter carries only okf_version: "0.1", a nested index.md per directory, and a log.md with a dated Creation entry naming where the documents came from.
5. Check the links. The relative links already in your documents are the graph's edges. The agent verifies they resolve inside the bundle and repoints only what a move broke. Links pointing outside the bundle are tolerated by the spec and stay as they are.
6. Close out, then prove it. The usual gate (validate clean, lint, loose, tag review, index re-check), plus the promise migrate makes: each concept, with its frontmatter block stripped back off, is byte-identical to the source document.

Try it

In Claude Code with the okf plugin, run /okf:gem migrate docs/, or ask the skill in plain words:

Turn the docs/ folder into an OKF bundle. Keep the bodies exactly as they are.

Pitfalls

• Migration makes docs legal, not true. A concept that was wrong before is now a wrong concept with tidy frontmatter. Conformance and correctness are different questions; lint will tell you what is thin, stale, or uncited, and only you can tell what is false.
• Do not restructure while migrating. Splits, renames, and retyping belong to a later curate or maintain pass. Rearranging documents in the same breath that converts them makes the diff unreviewable.
• A new type per file makes type meaningless. The temptation is worse here than in produce, because the documents arrive in every shape at once. Derive a small vocabulary from what they are, then reuse it.
• The missing concepts are a feature. Links pointing at documents nobody wrote show up in lint's backlog, ranked by demand. That is the day-1 worklist for produce, not a defect in the migration.