How It Works

DATA_DIR/
├── repo/                 git working tree (source of truth)
│   ├── .gitattributes    union merge for index.md / log.md
│   ├── payments-api/     one project = one OKF bundle
│   │   ├── index.md      generated by ok-fine (okf_version: "0.2")
│   │   ├── log.md        update log, newest first
│   │   ├── overview.md   type: Project
│   │   └── tables/
│   │       ├── index.md
│   │       └── orders.md
│   └── …
├── home/                 HOME for git/ssh child processes (container)
├── ok-fine.lock          held by the local CLI process (npm package only)
└── tmp/                  archive import staging

• A project is any top-level directory whose name matches ^[a-z0-9][a-z0-9-]{0,62}$.
• A concept ID is the bundle-relative path without .md, e.g. tables/orders.
• ok-fine owns every index.md. They are regenerated after each write, import, and sync; manual edits are overwritten. log.md exists only at the project root and is appended to on every change.
• Concepts under proposals/ that carry a proposal key (the former proposal layout) are moved to decisions/ at startup, after syncs that pull changes, and on import.
• The server is a single process with an in-memory catalog and search index, rebuilt from disk at startup. Writes are serialized; run one replica per data volume.

Concepts

---
type: BigQuery Table
title: Customer Orders
description: One row per completed customer order across all channels.
tags: [sales, orders]
sources:
  - { id: schema-doc, resource: https://wiki.example.com/orders }
generated: { by: claude-code/claude-opus-4-5, at: 2026-10-05T12:00:00Z }
---

# Schema

One row per order.[^schema-doc] Joined with [customers](/tables/customers.md) on `customer_id`.

Links

• Intra-bundle links: Standard OKF bundle-absolute or relative links, e.g. [customers](/tables/customers.md) or [orders](orders.md). Targets must end in .md.
• Cross-project links: Use the okf://<project>/<id> URI scheme (optionally with trailing .md and #fragment), e.g. [tier](okf://org/glossary/tier) or [sla](okf://org/policies/sla#p1). Cross-project links are an ok-fine extension that other OKF readers ignore safely. The server indexes inbound links across projects, resolves them in read_concept and the web UI, and warns on missing targets during linting (without rejecting the write).

Only type is required. Unknown frontmatter keys and unknown types are preserved. The server manages two keys:

• generated is stamped on every write with the writing actor and time.
• verified changes only through verify_concept; values sent to write_concept are ignored and reported in ignoredKeys.

Actors

Every write names an actor following the OKF convention:

Form	Example	Use
<producer>/<version>	claude-code/claude-opus-4-5	agents and tools
human:<id>	human:alice@example.com	a person; <id> is their git email and must equal the caller's token identity
process:<id>	process:nightly-import	automated jobs

The actor becomes the git commit author name. Commits by human:<email> actors use that email as the author email; all other actors use ok-fine@localhost. The token's subject and client ID are recorded in an Okf-Principal commit trailer.

Trust tiers

Tier	Meaning
proposed	carries the proposal frontmatter key (work not yet in the mainline); takes precedence over verified
unverified	no verified entries
machine-confirmed	verified only by agents/processes
human-reviewed	verified by at least one human: actor