Bundle Format Reference¶

An OKF bundle is a directory of plain Markdown files with YAML frontmatter, generated by okf generate. Every file describes one Concept — a class, function, module, dependency, or other unit extracted from your codebase.

Directory Layout¶

A generated bundle is a flat directory of Markdown files that mirrors the source tree. Here's a real example from a multi-language codebase:

okf_bundle/
│
├── index.md                  # Bundle metadata (auto-generated)
├── SUMMARY.md                # Agent-facing index (regenerate via `okf summarize`)
├── log.md                    # Generation log (one entry per run)
│
├── python/
│   ├── index.md              # Module concept for python/ dir
│   ├── easy/
│   │   ├── index.md          # Module concept for python/easy/ dir
│   │   ├── utils.md          # Module concept: utils.py
│   │   ├── utils/
│   │   │   ├── index.md      # Module concept for utils/ subdir (if nested)
│   │   │   ├── slugify.md    # Function: slugify
│   │   │   └── chunk_list.md # Function: chunk_list
│   │   ├── models.md         # Module concept: models.py
│   │   └── validator.md      # Module concept: validator.py (new in v2)
│   └── easy_v2/              # Second version of the same project
│       └── ...
│
├── rust/
│   ├── index.md
│   ├── easy/
│   │   └── ...
│   └── complex/
│       └── ...
│
│   ... (one directory per language/source root)
│
└── _dependencies/             # All dependency concepts live here
    ├── index.md
    ├── pip/
    │   ├── index.md
    │   ├── requests.md        # Dependency: requests (from requirements.txt)
    │   └── click.md           # Dependency: click
    ├── npm/
    │   ├── index.md
    │   ├── express.md         # Dependency: express (from package.json)
    │   └── ...
    ├── cargo/
    │   ├── index.md
    │   ├── serde.md           # Dependency: serde (from Cargo.toml)
    │   └── ...
    └── go/                    # One subdir per ecosystem found
        └── ...

File-by-file breakdown¶

File	Purpose
`index.md`	Bundle root metadata — `type: Index`, `title`, `description`, `okf_version`, `timestamp`, `source_root`
`SUMMARY.md`	Consolidated table of contents grouped by language/domain with concept counts per type. Frontmatter includes `git_branch`, `git_repo`
`log.md`	Audit trail: each `okf generate` run appends a log entry with timestamp, concept count, and source directory
`{path}/{module}.md`	Module concept for a source file. Mirrors the relative path of the file in the source tree
`{path}/{module}/{concept}.md`	One file per function, class, method, or other symbol. The `{concept}` is a sanitized version of the symbol name
`_dependencies/{ecosystem}/{name}.md`	One file per dependency package, organized by ecosystem (`pip`, `npm`, `cargo`, `go`, `maven`, etc.)

Key rules¶

Source concepts mirror the relative path of the file they were extracted from, under the bundle root. If your source has src/utils/helpers.py, the concept files go under src/utils/helpers/.
index.md files act as module/container concepts for directories. They are auto-generated and should not be hand-edited.
_dependencies/ is a reserved directory. All dependency concepts go here, organized by ecosystem (pip/, npm/, cargo/, etc.), one file per package.
SUMMARY.md is auto-generated — do not hand-edit. Regenerate with okf summarize after any manual bundle edits.
log.md tracks generation history and is purely informational.

Concept Frontmatter¶

Every concept file starts with YAML frontmatter. Only these fields appear in the frontmatter:

---
okf_version: "0.2"
type: Function
title: slugify
description: Convert arbitrary text into a URL-safe slug.
resource: utils.py
tags:
  - lang:python
  - type:Function
  - module:utils
timestamp: 2026-07-01T10:22:03Z
language: python
concept_id: python/easy/utils/slugify
status: active
---

Field	Required	Description
`okf_version`	yes	Schema version (`"0.2"`)
`type`	yes	Concept kind — see Concept Types
`title`	yes	Concept name (`slugify`, `User`, `click`)
`description`	no	Short description (first line of docstring or enriched)
`resource`	yes	Source file path relative to repo root
`tags`	yes	Structured tags — see Tag Reference
`timestamp`	yes	ISO 8601 generation timestamp
`language`	yes	Source language (extracted from tags)
`concept_id`	yes	Unique concept path (relative to bundle root, no extension)
`status`	no	`active`, `deprecated`, or `experimental`

Everything else (signature, docstring, params, relationships, methods, source) goes in the Markdown body under ## headings.

Concept Types¶

`type`	Source	Body format
`Index`	Bundle metadata (index.md, SUMMARY.md)	Standard
`Module`	A file or logical directory	Standard
`Function`	A function, method, or constructor	Standard + Signature, Parameters, Returns, Calls
`Class`	A class, struct, trait, or equivalent	Standard + Inheritance, Fields, Methods
`Dependency`	An external package from a manifest file	Dependency table + Used By
`Interface`	Interfaces, protocols, or abstract types	Standard + Methods
`Enum`	Enumeration types	Standard + Methods (as enum cases)
`Variable`	Module-level variable declarations	Standard + Signature
`Constant`	Module-level constants	Standard + Signature
`Table`	SQL tables	Standard + Fields
`Trigger`	SQL triggers	Standard
`Type`	Type aliases	Standard

Tag Reference¶

Tags are flat strings in key:value form:

Prefix	Meaning	Example
`lang:`	Source language	`lang:python`, `lang:rust`
`type:`	Concept type	`type:Function`, `type:Class`
`module:`	Owning module	`module:utils`
`ecosystem:`	Dependency ecosystem	`ecosystem:pip`
`version:`	Dependency version	`version:==8.1.7`
`manifest:`	Source manifest	`manifest:requirements.txt`
`git:`	Git metadata	`git:branch:main`

Body Sections¶

After the frontmatter, the markdown body can include any of these ## sections, depending on what the scanner + linker extracted:

Section	Appears for	Description
`## Signature`	Functions, methods	Full signature in language-native syntax
`## Docstring`	Any	Verbatim docstring or enriched description
`## Type Parameters`	Generics	`[T]`, `[T, U extends Comparable]`
`## Inheritance`	Classes	Base classes, interfaces implemented
`## Decorators`	Any	`@decorator`, `#[derive]`, `[Attribute]`
`## Visibility`	Functions, classes	`public`, `private`, `protected`
`## Fields`	Classes, structs	Named fields with types and visibility
`## Parameters`	Functions	Table of parameter name, type, default
`## Returns`	Functions	Return type annotation
`## Methods`	Classes	List of method names
`## Source`	Any	Line range in source file
`## Relationships`	Any	Typed table of related/called/called-by edges — see Relationships
`## Usage Example`	Any	From deep enrichment pass
`## Design Pattern`	Any	From LLM enrichment
`## Deprecation`	Any	Detected deprecation notices
`## Side Effects`	Any	From deep enrichment
`## Security`	Any	AI-estimated risk patterns
`## Complexity`	Any	AI-estimated complexity

Dependency Concepts¶

Dependency concepts have their own body format — a table instead of sections:

Field	Description
Ecosystem	Package ecosystem (`pip`, `npm`, `cargo`, etc.)
Version constraint	Version spec as declared
Source manifest	Filename the dependency was parsed from
Dev dependency	`yes` or `no`
Used by	Number of modules importing this dep

Followed by a ## Used By section listing dependent modules.

Relationships¶

All typed edges (related, calls, called_by, inherits) appear in a single ## Relationships table:

## Relationships

| Type | Target |
|------|--------|
| related | [slugify](/utils/slugify.md) |
| calls | [requests.get](/_dependencies/pip/requests.md) |
| called_by | [main.run_pipeline](/_dependencies/_modules/main.md) |
| related (AI) | [chunk_list](/utils/chunk_list.md) |

Relationship types: related, related (AI), calls, called_by, inherits, implements. All target paths are relative to the bundle root.

Migration: v0.1 bundles used separate ## Related, ## Calls, ## Called By sections. Run okf migrate v0.1-to-v0.2 <bundle_dir> to convert.

Minimal Valid Example¶

---
type: Function
title: add_numbers
description: Adds two integers.
resource: math_utils.py
tags:
  - lang:python
  - type:Function
  - module:math_utils
timestamp: 2026-07-01T09:00:00Z
---

# add_numbers

Adds two integers and returns the sum.

## Signature
```python
def add_numbers(a: int, b: int) -> int

Parameters¶

Name	Type	Default
`a`	`int`	`—`
`b`	`int`	`—`

Returns¶

int

## Versioning

This schema targets **OKF v0.2**. Every concept file contains `okf_version: "0.2"` in frontmatter.

### Why v0.2?

The bump from v0.1 to v0.2 formalizes the schema for downstream tooling:

| What | v0.1 | v0.2 | Why |
|------|------|------|-----|
| Schema version | Only in index.md | Every concept file | Tools can validate format without reading root |
| Concept identity | Implicit (file path) | Explicit `concept_id` field | Graph DB import, dedup across bundles |
| Language | In tags only (`lang:python`) | Dedicated `language` field | One less parse step for consumers |
| Status | Not tracked | `status: active\|deprecated\|experimental` | Enables deprecation-aware tools |
| Relationship edges | 4 separate `##` sections (Related, Calls, Called By, Related AI) | Single `## Relationships` table with typed rows | Queryable by edge type, easier to parse, extensible to new types |

### Migrating from v0.1

```bash
okf migrate v0.1-to-v0.2 ./path/to/bundle

Run --dry-run first to preview changes. The migration: - Adds okf_version, concept_id, language to every concept frontmatter - Merges ## Related, ## Calls, ## Called By, ## Related (AI-suggested) into a single ## Relationships table - Is idempotent: running it again on a v0.2 bundle is a no-op

Breaking changes between versions are called out in the Changelog.