OKF bundle

Abstract

okf/ is an Open Knowledge Format v0.2 bundle. It is the compiled map of this repo: one concept per source directory and per doc, with imports already linked. Agents read okf/index.md and then one concept instead of searching the tree.

Refresh

The pre-commit hook (.githooks/, installed by bun install) runs the pipeline against the git index and stages the generated bundle into the commit. Unstaged edits, including unstaged edits to curated playbooks, are not part of that commit's bundle.

bun run okf:enrich    # draft, link, and lint from the working tree
bun run okf:check     # fail if the committed bundle would change
bun run okf:lint      # conformance errors and producer warnings
bun run okf:query chart drawings
bun run okf:context src/chart

A directory path resolves to that concept. A file path resolves to the deepest directory concept that contains it. Query terms match path segments and the file names listed on a concept, so ui does not match builtins, and drawings.ts finds the directory that contains it. AGENTS.md is gitignored and is not part of this bundle. The shared reading guide is okf/playbooks/read-this-first.md.

OKF_SKIP=1 skips the hook refresh. CI runs okf:check, so a commit that bypasses the hook still cannot merge a stale bundle.

Generated concepts (okf_lock: generated) are replaced when their sources change. Curated playbooks (okf_lock: human) are kept. Put hand-written knowledge in okf/playbooks/ with that lock. The draft records exports, imports, and the first non-license comment. It does not call a model.

Layout