@solidgraph-io/okf-tools

CLI + library for Open Knowledge Format (OKF) knowledge bundles: conformance checking, progressive-disclosure indexes and a cross-link codemod. Config-driven — zero assumptions about your repo layout.

What is OKF?

Open Knowledge Format (v0.1, published by Google Cloud) is a vendor-neutral spec for representing knowledge as a directory tree of Markdown files with YAML frontmatter — written by humans, generated by agents, consumed by both:

• A bundle is a directory tree of .md files; a concept is one .md (its ID is the path without .md).
• Frontmatter has one REQUIRED field, type; title/description/tags/ timestamp are recommended; extra keys are allowed.
• Cross-links are normal Markdown links between concepts (bundle-absolute preferred: /specs/x.md). One link = one relation.
• Reserved files: index.md (per-directory catalog for progressive disclosure) and log.md (chronological history). The root index.md declares okf_version.
• Permissive consumption: consumers must not reject a bundle over missing optional fields, unknown types, extra keys or broken links.

Install

pnpm add -D @solidgraph-io/okf-tools   # or npm i -D / yarn add -D

CLI

okf check [bundleRoot] [--config PATH]            conformance (exit ≠ 0 on hard violations)
okf index [bundleRoot] [--config PATH] [--check]  generate / verify per-directory indexes
okf link  [bundleRoot] [--config PATH] [--check]  cross-link codemod (idempotent)

• okf check — validates the bundle. Hard (exit 1): root index.md with okf_version, parseable frontmatter, non-empty type. Warnings (exit 0): type outside the taxonomy, broken bundle-relative links (links inside code fences/inline code are examples and are ignored), missing sub-indexes, unexpected okf_version.
• okf index — writes an index.md catalog into every non-empty subdirectory (* [Title](file.md) - description, from frontmatter) and maintains a managed block in the root index.md. Deterministic output; --check exits 1 if any index is stale (wire it in CI).
• okf link — rewrites the first prose mention of each configured ID (e.g. SPEC-QA-001, ADR-0014) per document into a bundle-absolute link. Never touches frontmatter, code fences, inline code, existing links, headings, self-references, reserved or generated files. Unresolvable refs stay in prose and are reported. Idempotent. --check is warning-only.

Typical wiring in a consumer repo:

// package.json
"scripts": {
  "okf:check": "okf check",
  "okf:index": "okf index",
  "okf:link": "okf link"
}

Configuration — okf.config.json

Looked up in the cwd (or passed with --config). Paths in the config resolve relative to the config file. Everything is optional; defaults shown:

{
  "bundleRoot": "docs",           // where the bundle lives
  "okfVersion": "0.1",            // expected okf_version (mismatch = warning)
  "taxonomy": [                    // valid `type` values (outside = warning)
    "Spec", "ADR", "Prompt", "Architecture", "Methodology",
    "Plan", "Runbook", "Index", "Reference"
  ],
  "reserved": ["index.md", "log.md"],   // never concepts, never rewritten
  "generated": ["traceability.md"],     // okf link never rewrites these
  "idRules": [                          // how prose IDs resolve to files
    { "pattern": "SPEC-[A-Z][A-Z0-9]*(?:-[A-Z][A-Z0-9]*)*-\\d+", "dir": "specs" },
    { "pattern": "ADR-\\d{4}", "dir": "adr",
      "filePattern": "^(\\d{4})-", "idTemplate": "ADR-$1" }
  ]
}

An idRule maps prose mentions to files: pattern matches the ID in prose, dir is the bundle-relative directory holding the targets. By default the ID is pattern matched at the start of the filename; with filePattern + idTemplate the ID is built from filename captures (e.g. 0014-design-gate.md → ADR-0014).

Library

Everything the CLI does is exported:

import {
  checkBundle, // conformance → { errors, warnings, concepts }
  buildIndexes, applyIndexes, checkIndexes,
  applyLinks, checkLinks, buildIdMap, processDoc,
  parseFrontmatter, maskCodeZones, maskInlineCode,
  DEFAULT_CONFIG, loadConfig, resolveBundleRoot,
} from '@solidgraph-io/okf-tools';

const result = checkBundle('/path/to/docs', { ...DEFAULT_CONFIG, taxonomy: ['Note'] });

Example

A minimal bundle lives in test/fixtures/bundle with its okf.config.json:

okf check --config test/fixtures/okf.config.json
# [okf] 2 concept(s) checked — 0 error(s), 0 warning(s)
# [okf] OK — bundle is OKF-conformant.

Development

pnpm install
pnpm build      # tsc → dist/
pnpm test       # vitest

Releasing is documented in PUBLISHING.md.

License

MIT © 2026 SolidGraph Solutions LLC