okf-cli-0.5.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 resolve and log.md files are well structured.
  index         Generate progressive-disclosure index.md files per directory.
  log           Preview log.md files, check stale concepts, append entries.
  graph         Extract a JSON node/edge graph from links between concepts.
  show          Print one concept's metadata and body.
  trust         Report each concept's trust tier, status, and staleness.
  sources       List the provenance each concept records.
  computations  List the attested computations a bundle declares.
  id            Allocate and list profile-declared document IDs.
  profile       List and inspect profiles published by a registry.
  config        Show and manage okf configuration.
  kit           Install and manage agent skills and subagents.
  assist        Launch an interactive agent session with installed okf skills.
  completions   Generate a shell completion script.

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.2 specification (the knowledge-catalog okf SPEC.md).

  It reads a v0.1 bundle unchanged. A bundle that declares nothing is read
  with v0.1 fallbacks and is never penalized for it; declaring
  okf_version: "0.2" in the root index.md opts into the stricter reading.

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.
  okf help index         Generated index.md files and the version declaration.
  okf help log           log.md upkeep and the two staleness checks.
  okf help graph         The concept graph and what becomes an edge.
  okf help trust         Trust tiers, staleness, and recorded provenance.
  okf help computations  Listing and printing attested computations.
  okf help ids           Profile-declared document IDs such as ADR-7.
  okf help interactive   Picking a bundle and concept with fzf.
  okf help config        Config files, defaults, and agent settings.
  okf help kit           Installing and publishing agent skills and subagents.
  okf help agents        Installing agent skills and launching assist.

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