okf-cli-0.2.0.0: help/okf.md

OPEN KNOWLEDGE FORMAT (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 is meant to be authored by people, generated by agents, exchanged across
organizations, and consumed by both.

The format is intentionally minimal -- a directory of Markdown files with YAML
frontmatter. There is no schema registry, no central authority, and no
required tooling. If you can "cat" a file you can read OKF; if you can
"git clone" a repo you can ship it.

WHY IT LOOKS THIS WAY

  OKF standardizes only the small set of conventions needed to make a
  knowledge corpus self-describing. It aims to be:

    Readable    by humans, without tooling.
    Parseable   by agents, without bespoke SDKs.
    Diffable    in version control.
    Portable    across tools, organizations, and time.

CORE IDEAS

  Bundle      A self-contained directory tree of knowledge documents -- the
              unit of distribution (a git repo, a tarball, or a subdirectory).
  Concept     A single unit of knowledge, written as one Markdown document. It
              may describe a tangible asset (a table, an API) or an abstract
              idea (a metric, a business process).
  Concept ID  The concept file's bundle-relative path with the .md suffix
              removed, e.g. tables/orders.md -> tables/orders.

  A concept document is YAML frontmatter (metadata) followed by a Markdown body
  (free-form knowledge). Only the frontmatter "type" field is required:

    ---
    type: PostgreSQL Table
    title: Orders
    description: One row per completed customer order.
    ---

    # Orders

    Orders join to [Customers](/tables/customers.md).

WHAT THE okf TOOL DOES

  validate    Check frontmatter conformance and, as an authoring aid, that
              links between concepts resolve and log.md files are structured.
  index       Generate progressive-disclosure index.md files per directory.
  log         Preview log.md files, check stale concepts, and append entries.
  graph       Extract a JSON node/edge graph from links between concepts.
  show        Print one concept's metadata and body.

STANDALONE BY DESIGN

  The okf CLI works on plain files only. It does not require Mori, Mina, an
  LLM, PostgreSQL, or network access. It tracks Google's Open Knowledge Format
  v0.1 specification (the knowledge-catalog okf SPEC.md).

SEE ALSO

  okf help format       Bundle layout, concept IDs, frontmatter, and links.
  okf help validation   What "conformant" means and how the tool checks it.
  okf help profiles     Checking a bundle against house conventions.

  The full user guide lives under docs/user/ in the okf repository.