# OKF Store Format Contract

audience: AI coding agents first. Imperative, BLUF.

Source of truth for this contract: [docs/design.txt](/tmp/wt-harness-nongated-okf-T1/docs/design.txt).
Do NOT invent alternate OKF shapes. Use this file when creating or updating store content.

## Scope

This contract governs TWO artifacts only:

1. every concept document stored in the OKF tree
2. every parent-directory `index.md` entry that points to that document

If either artifact violates this contract, the store is malformed.

## Navigation contract

- Start discovery at the root `index.md`.
- Read one-sentence summaries before opening deeper files.
- Move down the tree one directory at a time via the local `index.md`.
- Before reading a full document body, inspect its YAML frontmatter first.
- Use `type` and `tags` to decide whether the document is relevant.

## Concept file contract

Every concept file MUST represent exactly one minimal topic. Do NOT mix unrelated concepts in one file.

Every new concept file MUST begin with THIS frontmatter block shape:

```yaml
---
type: <type>
title: <title>
description: <one-sentence description>
tags:
  - <tag>
---
```

Rules:

- `type` is REQUIRED. Omit it and the file is invalid.
- `title`, `description`, and `tags` are OPTIONAL by source policy, but this contract keeps the full block
  shape verbatim so agents have one stable template to write.
- The frontmatter block MUST be the first bytes in the file.
- `description`, when present, MUST stay to one sentence.
- `tags`, when present, MUST be a YAML list.

## Parent index contract

Immediately after creating a concept file, update the parent directory's `index.md`.

Each child entry MUST use THIS line shape verbatim:

```md
- [<label>](<path>) - <one-sentence summary>
```

Rules:

- Keep exactly one markdown link on the line.
- The summary MUST be one sentence.
- The line MUST live in the direct parent directory's `index.md`, not only at the root.
- Add the line immediately when the file is created; do NOT defer index maintenance.

## Invalid shapes — reject

DO NOT use these variants:

```md
[<label>](<path>)
```

```md
- [<label>](<path>)
```

```md
- <label>: [<path>](<path>) - <summary>
```

They fail the contract because they omit the one-sentence summary or change the required line shape.

## Agent rule

When an agent creates or edits OKF content, it MUST:

1. write one-concept-per-file content
2. add the frontmatter block at file start
3. update the direct parent `index.md` with the required line shape in the same change
4. use frontmatter-first filtering during later retrieval