The developer toolkit for Open Knowledge Format (OKF) bundles.

okfx validates, lints, formats, graphs, diffs, packages, indexes, and serves OKF bundles to humans, CI systems, and AI agents. Its default command is okf, and its packages live under the @okfx/* namespace.

Think of it as:

ESLint + Prettier + ripgrep + graph inspector + package verifier + MCP gateway for Markdown-based knowledge bundles.

okfx does not try to redefine the OKF standard or replace a data catalog. It gives teams an engineering workflow around OKF bundles:

author → validate → lint → format → graph → review → diff → pack → index → serve to agents

• What is an OKF bundle?
• Features
• Quick start
• Commands
• Configuration
• Diagnostics model
• MCP server
• GitHub Action
• Adapters (import / export)
• Editor integration
• Architecture
• Repository layout
• Development
• Project status
• Contributing
• License

Open Knowledge Format is an intentionally lightweight format for exchanging knowledge context between humans, tools, catalogs, and agents. A bundle is just a directory tree:

knowledge/
  index.md                 # reserved: navigable entrypoint
  log.md                   # reserved: change log
  metrics/
    weekly_active_users.md # a concept
  tables/
    user_events.md         # a concept
  okfx.config.ts           # okfx configuration (optional)

The core conventions:

• A bundle is a directory of Markdown files.
• A concept is a Markdown file with a YAML frontmatter block.
• The file path is the concept identity (e.g. metrics/weekly_active_users).
• Markdown links express relationships between concepts.
• index.md and log.md are reserved filenames.
• type is the single most important required frontmatter field.

A minimal concept:

---
type: Metric
title: Weekly Active Users
description: Number of unique users active in the last 7 days.
resource: https://docs.example.com/metrics/wau
tags:
  - analytics
  - engagement
timestamp: 2026-07-07T00:00:00Z
---

# Weekly Active Users

Weekly Active Users measures unique users who performed a qualifying event in the last 7 days.

## Source Tables

- [User Events](../tables/user_events.md)

Design principles: local-first (no network, no telemetry, no LLM calls by default), deterministic (stable sorting, hashes, diagnostics, and IDs for reliable CI and diffs), and spec-compatible but opinionated (a clear split between spec errors, lint warnings, and doctor advice).

• Node.js >= 20
• pnpm 11.8.0 (for local development of this repo)

pnpm add -g @okfx/cli
# or run without installing
pnpm dlx @okfx/cli --help

# scaffold a starter bundle (templates: minimal, data-platform, api-catalog, metrics)
okf init ./knowledge --template data-platform

# hard conformance check
okf validate ./knowledge

# quality, graph, style, and security rules
okf lint ./knowledge

# agent-readiness score and production checks
okf doctor ./knowledge

# build the concept graph
okf graph ./knowledge --format json --out graph.json

Example okf doctor output:

OKF Doctor

Bundle:
  root: /path/to/knowledge
  concepts: 2
  links: 2
  broken links: 0
  orphan concepts: 0
  cycles: 0
  failOn: error

Agent readiness:
  score: 94/100
  errors: 0
  warnings: 0
  advice: 2

All commands accept a bundle root (default .). Full behavior and exit codes are documented in docs/commands/reference.md.

okfx loads the first config file it finds in the bundle root: okfx.config.ts, .mts, .mjs, .js, .cjs, or .json. Full reference: docs/config/reference.md.

import { defineConfig } from "@okfx/core";

export default defineConfig({
  okfVersion: "0.1",

  include: ["**/*.md"],
  exclude: ["node_modules/**", ".git/**", ".okfx/**", "dist/**"],

  presets: ["recommended", "agent-ready"],

  rules: {
    "spec/missing-type": "error",
    "hygiene/missing-description": "warning",
    "graph/broken-internal-link": "warning",
    "graph/orphan-concept": "advice",
    "agent/metric-missing-source": "warning",
    "security/suspicious-secret": "error"
  },

  // fail the command when a diagnostic reaches this severity
  failOn: "error",

  frontmatter: {
    keyOrder: ["type", "title", "description", "resource", "tags", "timestamp"]
  },

  // restrict allowed resource hosts (no network requests are ever made)
  resourcePolicy: {
    allowHosts: ["docs.example.com", "github.com", "cloud.google.com"]
  },

  mcp: {
    readonly: true,
    exposeDiagnostics: true,
    exposeGraph: true
  }
});

• @okfx/preset-recommended — balanced defaults (spec errors, common hygiene warnings, broken-link warnings, light agent advice).
• @okfx/preset-strict — CI-oriented; promotes many warnings to errors and sets failOn: "warning".
• @okfx/preset-agent-ready — agent-oriented; checks summaries, backlinks, metric source links, owners, and usage sections.

Presets may be referenced by short name (recommended) or full package name (@okfx/preset-recommended).

okfx cleanly separates three questions:

Every diagnostic has a stable code (<category>/<rule-name>), a severity, a message, and an optional path/location and fix. Categories: spec, hygiene, graph, style, agent, security, plugin. The full built-in rule set is documented in docs/rules/catalog.md.

Severities: error (must fix), warning (should review), advice (optional improvement), info (informational).

Exit codes:

@okfx/mcp exposes an OKF bundle to AI agents over the Model Context Protocol. The server is read-only, local-only, and makes no network or LLM calls by default. Full details: docs/mcp/server.md.

# start a stdio MCP server for a bundle
okf mcp ./knowledge

# inspect the configuration without starting the transport
okf mcp ./knowledge --describe

Resources: okf://bundle/current, okf://graph/current, okf://diagnostics/current, okf://concept/{id}.

Tools: okf_list_bundles, okf_search_concepts, okf_get_concept, okf_get_neighbors, okf_get_backlinks, okf_get_graph, okf_validate_bundle, okf_lint_bundle, okf_explain_diff, okf_get_diagnostics.

Prompts: review_okf_changes, draft_okf_concept, improve_agent_readiness, explain_metric_context, trace_table_to_metric.

Example MCP client entry:

{
  "mcpServers": {
    "okf": {
      "command": "okf",
      "args": ["mcp", "./knowledge"]
    }
  }
}

@okfx/github-action provides a CI quality gate that validates, lints, graphs, and doctors a bundle, then writes a job summary and (optionally) a PR comment.

name: OKF
on:
  pull_request:
  push:
    branches: [main]

jobs:
  okf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: okfx/okfx/packages/github-action@v0
        with:
          cli-version: "0.1.0"
          bundle: ./knowledge
          lint-format: json
          graph-out: okf-graph.json
          summary: "true"
          pr-comment: "true"

okf lint --format sarif output can also be uploaded to GitHub code scanning.

Adapters produce reviewable file changes — they never silently mutate a bundle. The recommended workflow is import → format → lint → review → commit. See docs/adapters/producers.md.

Producer adapters (okf import <adapter> --input <file.json>):

• @okfx/adapter-markdown
• @okfx/adapter-openapi
• @okfx/adapter-dbt
• @okfx/adapter-datahub
• @okfx/adapter-bigquery

Consumer adapters (okf export <target>):

• @okfx/adapter-static-site — export a self-contained static site.

okf import dbt --input ./target/manifest.json --out ./knowledge --dry-run
okf import dbt --input ./target/manifest.json --out ./knowledge --write
okf fmt ./knowledge && okf lint ./knowledge

@okfx/vscode is a VS Code extension that surfaces inline diagnostics, format-on-save, frontmatter and concept-link completion, go-to-concept, a graph preview, a doctor panel, a backlinks panel, and quick fixes for common missing-frontmatter diagnostics.

okfx is a hybrid Rust core + TypeScript ecosystem designed around a stable JSON intermediate representation (IR). See docs/architecture/overview.md.

┌───────────────────────────────────────────────────────────┐
│                     User interfaces                        │
│   CLI (okf)   VS Code   GitHub Action   MCP server         │
└───────────────────────────────────────────────────────────┘
                            │
┌───────────────────────────────────────────────────────────┐
│                   TypeScript ecosystem                     │
│  @okfx/core  @okfx/cli  @okfx/mcp  @okfx/plugin-api        │
│  @okfx/adapter-*  @okfx/preset-*  @okfx/github-action      │
└───────────────────────────────────────────────────────────┘
                            │  JSON IR over N-API / WASM
┌───────────────────────────────────────────────────────────┐
│                        Rust core                           │
│  okfx_parser  okfx_resolver  okfx_rules  okfx_fmt          │
│  okfx_graph  okfx_index  okfx_pack  okfx_fs  okfx_cache    │
└───────────────────────────────────────────────────────────┘
                            │
┌───────────────────────────────────────────────────────────┐
│         Knowledge bundle (Markdown + YAML + links)         │
└───────────────────────────────────────────────────────────┘

• @okfx/core owns the deterministic TypeScript engines and the JSON IR (BundleIR, ConceptIR, LinkIR, DiagnosticIR, GraphIR, …). It is the default runtime today.
• The Rust crates provide opt-in accelerated parsing and formatting through N-API or WASM, plus a standalone okfx binary. The regular Core/CLI paths remain on the deterministic TypeScript implementation; async *Accelerated helpers probe native, then WASM, then TypeScript. No Rust toolchain is required to use okfx.
• Plugins and adapters exchange only the stable JSON IR — never internal Rust structs.

This is a pnpm + Cargo monorepo.

okfx/
  crates/        Rust core crates and native/WASM/CLI bindings
  packages/      TypeScript packages published under @okfx/*
  examples/      Runnable example bundles
  fixtures/      Golden-file and case fixtures for tests
  fuzz/          cargo-fuzz targets for the parser and resolver
  npm/           npm distribution shells for native/WASM binaries
  docs/          Documentation (itself an OKF-style bundle)

# install workspace dependencies
pnpm install

# build all TypeScript packages (also makes the CLI executable)
pnpm build

# type-check the workspace
pnpm typecheck

# run the TypeScript test suite (vitest)
pnpm test

# validate, lint, and format-check this repository's OKF content
pnpm check:okf

Rust workspace:

# enforce rustfmt and Clippy
pnpm check:rust

# test all crates
cargo test --workspace

# build the WASM fallback
cargo build -p okfx_wasm --target wasm32-unknown-unknown

# build the standalone binary
cargo build -p okfx_cli --release

CI (.github/workflows/ci.yml) runs the TypeScript build, typecheck, tests, dependency audit, repository OKF checks, rustfmt, Clippy, the full Rust test suite, and WASM/standalone builds on every push and PR. Release verification applies the same gates.

See docs/testing/strategy.md for the full verification strategy and CONTRIBUTING.md to get started.

This repository currently includes the planned TypeScript, Rust, agent, adapter, packaging, and index surfaces. Future releases should focus on compatibility hardening, performance, and public API stability rather than filling missing command surfaces.

Versioning is semver; 0.x APIs are unstable and may change between minor releases.

Contributions are welcome. Please read CONTRIBUTING.md for the development workflow, monorepo conventions, and how to add rules, adapters, and plugins. This project uses Conventional Commits (e.g. feat(graph): …, fix(cli): …, docs: …).

MIT © okfx