rokf

Create, inspect, and maintain Open Knowledge Format (OKF) knowledge bundles.

rokf is a CLI tool that helps people and agents author, verify, and maintain portable knowledge bundles — directories of markdown documents with structured YAML frontmatter.

Installation

cargo install --path .

Or build from source:

cargo build --release
# binary at target/release/rokf

Usage

Verify a concept document or bundle

rokf check path/to/concept.md
rokf check path/to/bundle-root
rokf check                       # discover Bundle Root from current directory
rokf check -                     # read one Concept Document from stdin
rokf check --output json path/to/concept.md
rokf check --fix path/to/concept.md

rokf check reads a single Concept Document or traverses an explicit Bundle Root and reports findings against the OKF specification:

• OKF001 — Concept Document frontmatter must be present and parseable YAML.
• OKF002 — Concept Document frontmatter must include a non-empty type field.
• OKF101 — Concept Document frontmatter should include a description field.
• OKF102 — Concept Document tags should be sorted.
• OKF200 — Reserved index.md files must not contain frontmatter (only the Root Index File may contain frontmatter).
• OKF201 — Reserved log.md files must not contain frontmatter.
• OKF202 — Root index.md frontmatter must be parseable YAML.
• OKF203 — Root index.md declares an unknown okf_version (warning; verified with best effort).
• OKF204 — Index File entry is missing a markdown link (suggestion).
• OKF301 — Log File date heading must use ISO 8601 date format.
• OKF302 — Log File dates should be ordered newest first (warning).
• OKF400 — Bundle Verification found a Broken Link between Concept Documents (warning).
• OKF500 — Index File does not reflect the current Bundle Hierarchy (warning).

By default, rokf check exits 1 for Error or Warning Findings. Use --failure-threshold error, --failure-threshold warning, or --failure-threshold suggestion to choose the minimum Severity that fails the workflow without changing conformance reporting.

rokf check --fix applies safe Fixes for Fixable Findings. The initial Fix sorts inline tags without changing Producer-defined Fields or Body content. With stdin (rokf check --fix -), rokf writes the fixed document to stdout rather than mutating a file.

rokf check --output json emits Structured Output with conformance, health, workflow status, and stable Finding fields for agent and automation workflows.

Configure verification

When checking a Bundle Root, rokf reads rokf.yml from that root if present. You can also pass an explicit file:

rokf check --config path/to/rokf.yml path/to/bundle-root

Supported MVP fields:

failure_threshold: error
rule_set: default       # default | conformance
suppressions:
  - OKF101
exclusions:
  - drafts/

Suppressions silence selected Rule Findings while keeping content in Verification Scope. Exclusions remove matching bundle-relative paths from Verification Scope. The conformance rule set reports only Error Findings.

Format OKF Documents

rokf format path/to/concept.md
rokf format path/to/bundle-root
rokf format --check path/to/concept.md
rokf format --check path/to/bundle-root
rokf format -

Formatting trims trailing whitespace and ensures a final newline without changing semantic content. Directory targets recurse over markdown files. --check reports formatting drift without mutating files.

Create Document Templates

rokf template concept --type "BigQuery Table" path/to/concept.md
rokf template index path/to/index.md
rokf template log path/to/log.md

Templates create well-shaped starting OKF Documents and refuse to overwrite existing files. Concept Types are producer-defined; rokf does not use a type registry or invent Descriptions, Citations, or Body content.

Maintain Index Files

rokf index --check path/to/bundle-root
rokf index --fix path/to/bundle-root
rokf index path/to/bundle-root

Index Maintenance keeps index.md files aligned with the current Bundle Hierarchy. --check reports drift without writing changes. --fix, or omitting both mode flags, writes missing or stale Index Files. Generated entries are concise and use Concept title and description fields when present.

General help

rokf --help
rokf --version

What is OKF?

OKF is an open, human- and agent-friendly format for representing knowledge — the metadata, context, and curated insight that surrounds data and systems. It's designed to be authored by people, generated by agents, exchanged across organizations, and consumed by both.

A knowledge bundle is a directory of markdown files with YAML frontmatter. No schema registry, no central authority, no required tooling. If you can cat a file, you can read OKF; if you can git clone a repo, you can ship it.

Read the full specification: SPEC.md

Development

Prerequisites

• Rust stable (install via rustup)
• just — command runner (brew install just on macOS)

Quick dev loop

After every code change, check a demo Bundle Root or Concept Document with fuzzy matching:

just check demos         # checks the demo hierarchy
just check star-wars     # matches the Star Wars demo bundle
just check rex           # matches captain-rex.md
just check phase         # matches phase-ii-armor.md
just check 501           # matches 501st-legion.md
just format rex          # formats the matching demo Concept Document

Run against all top-level demo bundles to sanity-check before pushing:

just check-all

Watch mode — re-checks a demo Bundle Root or Concept Document automatically every time you save a source file:

cargo install cargo-watch   # first time only
just watch demos

Quality checks

cargo fmt --check   # formatting
cargo clippy --all-targets --all-features -- -D warnings   # linting
cargo test --all-targets --all-features   # tests

Git hooks

git config core.hooksPath .githooks

The pre-commit hook runs cargo fmt --check and cargo clippy on staged changes.

Releases

make release-patch   # bump 1.0.0 → 1.0.1
make release-minor   # bump 1.0.0 → 1.1.0
make release-major   # bump 1.0.0 → 2.0.0

Release targets bump Cargo.toml and Cargo.lock, then run quality gates (fmt, clippy, test). They do not publish to crates.io or create GitHub releases — those steps are manual.

Project structure

rokf/
├── src/
│   ├── main.rs           # Entry point
│   ├── lib.rs            # Module declarations
│   ├── cli.rs            # CLI definition (clap)
│   └── verification.rs   # Verification engine
├── tests/                # Integration tests
├── docs/                 # Agent documentation
├── SPEC.md               # OKF specification
├── CONTEXT.md            # Domain vocabulary
└── Cargo.toml