Files

T

Frank bfd6a6340e docs(okf): the work log is one file at the bundle root, and an entry is a lesson not a manifest

The spec listed `log.md` as a reserved name and the maintenance page said every bundle
"has a `log.md`" — neither said there is only one, so a subdirectory could invent its own
and look compliant. Which is how the sprawl Frank banned started: with fifty logs the
entry is never where the next reader looks, and every copy re-dates the same event.

The maintenance page also taught the wrong format: "one line per change with file path",
exampled as `/docs/ghostty.md — Updated keybind table`, i.e. a manifest duplicating git,
with absolute paths that kb-lint cannot resolve because OKF links are relative. Replaced
with the law this bundle already runs: what changed plus the durable lesson, a few lines,
relative links, laws and incidents rather than bookkeeping.

2026-10-20 21:49:16 -07:00

6.0 KiB

Raw Blame History

type, title, description, resource, tags, verified, timestamp

type

title

description

resource

Open Knowledge Format (OKF) v0.1

OKF is the answer to "everyone has knowledge, but nobody speaks the same language." Every agent, catalog, wiki, and metadata store represents knowledge differently — and every agent builder is reinventing the context-assembly wheel.

OKF v0.1 formalizes the "LLM wiki" pattern into a portable, interoperable format. The entire specification is simple enough to fit on a single page:

A directory of markdown files with YAML frontmatter.

That's it. No schema registry. No central authority. No SDK. No runtime. If you can cat a file, you can read OKF. If you can git clone a repo, you can ship it.

What's in a Bundle?

An OKF knowledge bundle is a directory tree. Every concept is one file. The file path is the concept's identity.

my-bundle/
├── index.md                      # Optional directory listing
├── log.md                        # The bundle's ONE update history — root only
├── concept-one.md                # A concept at the root level
└── subdirectory/
    ├── index.md                  # Optional subdirectory listing
    ├── concept-two.md            # A concept in a subdirectory
    └── another-concept.md        # Another concept

Reserved filenames (MUST NOT use for concepts):

Filename	Purpose
`index.md`	Directory listing for progressive disclosure
`log.md`	Chronological update history — exactly one, at the bundle root

One work log per bundle. log.md is reserved, and it is reserved for a single file: the bundle root's. A subdirectory never keeps its own change log — a bundle that logs in fifty places has no log, because the entry is never where the next reader looks and every copy re-dates the same event. scripts/kb-lint.sh reports any log.md that is not the root's.

Anatomy of a Concept Document

---
type: <Type name>                  # REQUIRED
title: <Optional display name>
description: <Optional one-line summary>
resource: <Optional canonical URI>
tags: [<tag>, <tag>, …]            # Optional
timestamp: <ISO 8601 datetime>     # Optional
---

Required Fields

Field	Required?	What it does
`type`	Yes	Identifies the kind of concept. Used for routing, filtering, presentation.
`title`	No	Human-readable display name.
`description`	No	Single-sentence summary. Used by index generators, search snippets, previews.
`resource`	No	URI identifying the underlying asset.
`tags`	No	YAML list for cross-cutting categorization.
`timestamp`	No	ISO 8601 datetime of last meaningful change.

Index Files — Progressive Disclosure

An index.md in any directory lets a human or agent see what's available:

# Sales Tables

* [Orders](tables/orders.md) - One row per completed customer order.
* [Customers](tables/customers.md) - Customer account information.

Rules: No frontmatter. Relative paths. One section per heading. Entries include description from linked concept's frontmatter.

Log Files — Change History

# Directory Update Log

## 2026-05-22
* **Update**: Added new reference for [Customer Metrics](/tables/customer-metrics.md).
* **Creation**: Established the [Dataplex Playbook](/playbooks/dataplex.md).

Date headings MUST use YYYY-MM-DD
Entries grouped newest-first
Leading bold word is a convention, not a requirement

Cross-linking

Absolute (bundle-relative) links — RECOMMENDED:

See the [customers table](/tables/customers.md) for the join key.

Relative links:

See the [neighboring concept](./other.md).

Consumers MUST tolerate broken links.

Conformance Rules

A bundle is conformant with OKF v0.1 if and only if:

Every non-reserved .md file contains a parseable YAML frontmatter block.
Every frontmatter block contains a non-empty type field.
Every reserved filename follows the structure described here when present.

Everything else is soft guidance. Consumers MUST NOT reject a bundle because of missing optional fields, unknown types, or broken links.

Common Mistakes

❌ Forgetting the type field — this is the only strictly required field
❌ Using type: file or type: document — be specific: type: BigQuery Table, type: API Endpoint
❌ Putting frontmatter in index.md — index files are directory listings, not concepts
❌ Using relative links for concepts in different directories — use absolute paths
❌ Writing one giant index.md that lists everything — use index.md at multiple levels
❌ Skipping # Citations for factual claims — cite external sources under # Citations

6.0 KiB Raw Blame History