# 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:

```yaml
---
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](#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](#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](#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:

```markdown
## 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

```markdown
---
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](../changelog.md).
