@rafinery/okf

Toolkit for the Open Knowledge Format (OKF v0.1) — markdown + YAML frontmatter bundles that humans and agents read without SDKs. Zero dependencies, pure functions, Node ≥ 18.

OKF is the interchange floor; the rafa contract is the strict ceiling on top of it. This package is the shared format machinery — the gate CLI (@rafinery/cli), the OKF emitter, the platform, and tests all parse/generate/validate through here so knowledge files are handled identically everywhere.

| Module | What it does | |---|---| | frontmatter | strict frontmatter parser (contract §0 grammar — a strict YAML subset; reports, never coerces) | | concept | split/join/stamp concept documents — stamps only append missing keys, authored values are never rewritten | | links | [[wikilink]] → bundle-relative markdown link transpile · link extraction/resolution for the checker's WARN lane | | citations | render the frontmatter cites: DSL as a generated # Citations section (sha-pinned GitHub URLs when the repo is known) | | indexes | OKF §6 index.md builders — progressive disclosure from the bundle root | | validate | bundle conformance walker (OKF §9): every non-reserved .md has frontmatter + non-empty type; exemptions are explicit and surfaced | | generate | newConcept(…) — mint a conformant-by-construction concept file (powers rafa okf new and the rafa-okf skill) | | profile-rafa | the rafa bundle profile: file-class registry, OKF type names, derived-stamp builders, documented exemptions |

Design law inherited from the gate: no assumed values. A stamp is derived from authored data or real history, or it is omitted; the validator reports, never fixes; the generator refuses to invent what it cannot know.