v0.2.0

okfctl targets OKF v0.2. New bundles are created at okf_version: 0.2, and v0.1 bundles remain readable — v0.2's two breaking renames (timestamp → generated.at, body # Citations → frontmatter sources) are read with a v0.1 fallback, per spec §12's best-effort consumption rule.

Spec v0.2 support

• Provenance — reads the v0.2 generated / verified / sources families, falling back to the v0.1 forms when a bundle declares the older version.
• Freshness — resolves through generated.at rather than filesystem modified/created, so a regenerated node reports its real age.
• Migration — okf migrate provides a two-phase v0.1 → v0.2 upgrade path: a mechanical pass, plus a judgment queue for the calls a tool should not make alone. The okf-migrate-plan skill ships alongside it.
• Section citations — spec §-numbering shifted between v0.1 (11 sections) and v0.2 (13); stale citations throughout the codebase are corrected.

Search

• Passage-level indexing — sub-node passages are indexed and returned as snippets, so a hit points at the paragraph rather than the file. Retrieval quality on the real corpus improved 0.545 → 0.909, at a measured ~12x index size.
• Query scoping — filter semantic queries by path, type, and tag, with optional recency decay.
• Tokenizer — a model2vec directory containing tokenizer.json is accepted, matching what the docs already promised.

Lint and analysis

• --json — machine-readable findings for CI and downstream tooling.
• Prose-only scanning — cross-reference and time-marker detection no longer reads link URLs as prose, eliminating a class of false missing-xref and time-sensitive findings. Both inline [text](url) and reference-style [ref]: url links are excluded.
• Title-as-home-node — a node whose title leads with a term is credited as that term's home, closing a coverage-gap false positive.
• Broken internal links — gated as defects when they look like defects.
• Vendored and derived directories — skipped during the bundle walk.
• Drift opt-out — a bulk mechanical commit can declare itself as such and skip the git-drift check.

New in this release

• okfctl-api — an HTTP API plugin over a bundle, serving /stats and /graph. Walking skeleton; the ADR describing its shape ships with it.
• Bulk index promotion — promote directory-as-concept index.md nodes in bulk.

Documentation

ADRs are introduced and the PRD is reconciled to shipped reality. AGENTS.md pins spec conformance as the working contract for the repo.