# Converting Sources to OKF

Guides for transforming existing knowledge into conformant OKF bundles.

---

## From Notion Export

Notion exports as markdown with properties in YAML-like format.

### Steps

1. **Export** from Notion as Markdown & CSV
2. **Clean filenames** — remove UUID suffixes (`Page Name abc123def.md` → `page-name.md`)
3. **Map properties to frontmatter:**

| Notion Property | OKF Field |
|-----------------|-----------|
| Type (select) | `type` (required) |
| Name | `title` |
| Tags (multi-select) | `tags` |
| Last Edited | `timestamp` |
| URL | `resource` |

4. **Convert links** — Notion uses `[Page Name](Page%20Name%20abc123def.md)`. Convert to clean relative paths: `[Page Name](./page-name.md)`
5. **Remove Notion artifacts** — empty toggle blocks, breadcrumb headers, cover image references
6. **Add missing `type` field** — if Notion had no "Type" property, ask the user what type to assign

### Edge cases

- Notion databases: each row becomes a concept. Database title becomes the directory name.
- Nested pages: respect the hierarchy. Child pages go in subdirectories.
- Inline databases: flatten into a list in the parent concept's body.
- Notion formulas/rollups: drop them — they don't translate to static markdown.

---

## From Obsidian Vault

Obsidian vaults are already close to OKF. Main differences: wikilinks and potentially missing `type` field.

### Steps

1. **Convert wikilinks to standard links:**
   - `[[Note Name]]` → `[Note Name](./note-name.md)`
   - `[[Note Name|Display Text]]` → `[Display Text](./note-name.md)`
   - `[[Note Name#Heading]]` → `[Note Name](./note-name.md#heading)`

2. **Ensure `type` field exists** in every frontmatter block. Common mappings:

| Obsidian pattern | Suggested OKF type |
|------------------|--------------------|
| Daily notes | `Log` |
| MOC / index note | Convert to `index.md` (reserved file) |
| Permanent notes | `Reference` |
| Literature notes | `Reference` |
| Project notes | `Playbook` or domain-specific |

3. **Convert tags:**
   - Inline `#tag` → move to frontmatter `tags: [tag]`
   - Nested `#parent/child` → flatten to `tags: [parent, child]` or keep as `parent/child`

4. **Handle embeds:**
   - `![[Note]]` — convert to a regular link or inline the content
   - `![[image.png]]` — keep as standard markdown image `![](./image.png)`

5. **Remove Obsidian-specific syntax:**
   - `%%comments%%` → remove
   - `> [!callout]` → convert to blockquote or heading
   - Dataview queries → remove (dynamic, not portable)

### What to keep as-is

- Standard markdown formatting (headings, lists, tables, code blocks)
- Existing YAML frontmatter (just add `type` if missing)
- Standard markdown links (already OKF-compatible)
- Mermaid diagrams (standard markdown fenced blocks)

---

## From CSV / Spreadsheet

Each row becomes one concept document.

### Steps

1. **Identify column mapping:**

| Column role | Maps to |
|-------------|---------|
| Primary identifier / name | Filename (slugified) |
| Category / kind | `type` field |
| Short description | `description` field |
| Tags / labels | `tags` field |
| URL / link | `resource` field |
| Last modified date | `timestamp` field |
| All other columns | Body content (as table or sections) |

2. **Generate one `.md` per row:**

```markdown
---
type: {category_column}
title: {name_column}
description: {description_column}
tags: [{tag1}, {tag2}]
timestamp: {date_column}T00:00:00Z
---

# {name_column}

| Field | Value |
|-------|-------|
| Column3 | {value} |
| Column4 | {value} |
```

3. **Generate index.md** from the full list:

```markdown
# {Sheet Name}

- [{row1_name}](./{row1_slug}.md) - {row1_description}
- [{row2_name}](./{row2_slug}.md) - {row2_description}
```

4. **Generate log.md** with creation entry:

```markdown
# Update Log

## {today_iso8601}
- **Creation**: Generated {N} concepts from spreadsheet import.
```

### Edge cases

- Empty cells: omit the field entirely (don't write empty strings)
- Multi-value cells (comma-separated): parse into YAML list for `tags`
- Very long text cells: put in body as a section, not in frontmatter
- Duplicate names: append a disambiguator (e.g., `widget-v1.md`, `widget-v2.md`)

# OKF Bundle Examples (v0.2)

Complete, conformant bundles demonstrating v0.2 features: provenance (`sources`), trust (`generated`, `verified`), lifecycle (`status`, `stale_after`), and Attested Computations.

---

## 1. Finance Analytics with Attested Computations

A financial reporting bundle with sanctioned, verifiable calculations.

```
finance/
├── index.md
├── log.md
├── metrics/
│   ├── index.md
│   └── income-statement.md
├── computations/
│   ├── index.md
│   ├── revenue.md
│   └── gross-profit.md
└── references/
    ├── skills/
    │   └── run-on-bq.md
    └── attesters/
        └── sql-equality.py
```

### index.md (bundle root)

```markdown
---
okf_version: "0.2"
---

# Finance Analytics Bundle

Knowledge base for financial reporting and KPIs.

- [Metrics](./metrics/) - Business KPIs and financial statements
- [Computations](./computations/) - Sanctioned calculations (attestable)
- [References](./references/) - Skills and attesters for execution
```

### metrics/income-statement.md

```markdown
---
type: Metric
title: Income statement (fiscal year)
description: Headline income-statement figures for a fiscal year.
tags: [finance, income-statement, kpi]
status: stable
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
stale_after: 2026-12-31T00:00:00Z
sources:
  - id: fpa-handbook
    resource: https://wiki.acme/finance/fpa-handbook
    title: FP&A reporting handbook
    author: team:finance-fpa
    last_modified: 2026-03-15T00:00:00Z
---

# Definition

The income statement reports [revenue](../computations/revenue.md) and
[gross profit](../computations/gross-profit.md) for a fiscal year, per the 
FP&A reporting handbook.[^fpa-handbook]

Each figure is produced by a sanctioned, attestable computation; this 
concept only narrates them.

## Key Figures

| Figure | Computation | Status |
|--------|-------------|--------|
| Revenue | [revenue.md](../computations/revenue.md) | Human-verified |
| Gross Profit | [gross-profit.md](../computations/gross-profit.md) | Machine-confirmed |

[^fpa-handbook]: FP&A reporting handbook
```

### computations/revenue.md (Attested Computation)

```markdown
---
type: Attested Computation
title: Revenue for fiscal year
description: Recognized revenue for a fiscal year, per Finance's definition.
tags: [finance, revenue]
status: stable
runtime: bigquery
parameters:
  - { name: year, type: integer, required: true }
executor:
  resource: /references/skills/run-on-bq.md
  receipt: [job_id, executed_sql, result]
attester:
  resource: /references/attesters/sql-equality.py
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-28T14:00:00Z }
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
stale_after: 2026-12-31T00:00:00Z
sources:
  - id: rev-policy
    resource: https://wiki.acme/finance/revenue-recognition
    title: Revenue recognition policy
    author: team:finance-fpa
    last_modified: 2026-04-02T00:00:00Z
  - id: exec-rev-dash
    resource: dashboards/exec-revenue
    title: Executive revenue dashboard
    author: team:finance-fpa
    usage_count: 5000
    last_modified: 2026-06-18T00:00:00Z
usage_window: { from: 2026-06-01T00:00:00Z, to: 2026-06-30T00:00:00Z }
---

# Computation

```sql
SELECT SUM(amount) AS revenue
FROM finance.recognized_revenue
WHERE fiscal_year = @year
```

Recognized revenue per the recognition policy,[^rev-policy] corroborated by
the executive revenue dashboard.[^exec-rev-dash]

# Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `year` | integer | Yes | Fiscal year (e.g., 2026) |

# Usage

```python
# Agent fills parameters only, never edits computation
result = executor.run(year=2026)
verdict = attester.verify(result.receipt)
```

[^rev-policy]: Revenue recognition policy
[^exec-rev-dash]: Executive revenue dashboard
```

### computations/gross-profit.md (Attested Computation - dbt)

```markdown
---
type: Attested Computation
title: Gross profit for fiscal year
description: Gross profit by segment for a fiscal year, per the cost-allocation standard.
tags: [finance, profit]
status: stable
runtime: dbt
parameters:
  - { name: year, type: integer, required: true }
  - { name: segment, type: string, required: true }
executor:
  resource: /references/skills/run-dbt.md
  receipt: [run_id, compiled_sql, result]
attester:
  resource: /references/attesters/dbt-binding.py
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-14T14:00:00Z }
verified: { by: process:finance-nightly, at: 2026-06-12T08:00:00Z }
stale_after: 2026-06-15T00:00:00Z
sources:
  - id: cost-alloc
    resource: https://wiki.acme/finance/cost-allocation
    title: Cost allocation standard
    author: team:finance-fpa
---

# Computation

```sql
SELECT gross_profit
FROM {{ ref('fct_income_statement') }}
WHERE fiscal_year = {{ var('year') }}
  AND segment = {{ var('segment') }}
```

Gross profit by segment per the cost-allocation standard.[^cost-alloc]

[^cost-alloc]: Cost allocation standard
```

---

## 2. E-commerce Analytics (v0.2)

```
ecommerce/
├── index.md
├── tables/
│   ├── index.md
│   ├── orders.md
│   └── customers.md
└── metrics/
    ├── index.md
    └── gross-revenue.md
```

### tables/orders.md

```markdown
---
type: BigQuery Table
title: Orders
description: One row per completed customer order across all channels.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
status: stable
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-05-28T14:30:00Z }
verified:
  - { by: human:data-steward, at: 2026-05-30T10:00:00Z }
  - { by: process:schema-validator, at: 2026-06-01T02:00:00Z }
sources:
  - id: bq-schema
    resource: https://cloud.google.com/bigquery/docs/schemas
    title: BigQuery schema documentation
    author: team:google-cloud-docs
  - id: internal-erd
    resource: /references/sales-erd.md
    title: Sales domain ERD
    author: human:data-architect
    last_modified: 2026-04-15T00:00:00Z
---

# Schema

| Column | Type | Description |
|--------|------|-------------|
| `order_id` | STRING | Globally unique order identifier |
| `customer_id` | STRING | FK to [customers](./customers.md) |
| `total_usd` | NUMERIC | Order total in US dollars |
| `placed_at` | TIMESTAMP | When the customer submitted the order |
| `channel` | STRING | Acquisition channel (web, mobile, pos) |

# Joins

- Join with [customers](./customers.md) on `customer_id`
- Referenced by [gross revenue](/metrics/gross-revenue.md) metric

# Data Quality

- Validated nightly by `process:schema-validator`
- `order_id` uniqueness enforced at ingestion

[^bq-schema]: BigQuery schema documentation
```

### tables/customers.md

```markdown
---
type: BigQuery Table
title: Customers
description: One row per registered customer with profile and lifetime data.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=customers
tags: [sales, customers, pii]
status: stable
generated: { by: human:data-engineer, at: 2026-05-28T14:30:00Z }
verified: { by: human:data-steward, at: 2026-05-30T10:00:00Z }
sources:
  - id: internal-erd
    resource: /references/sales-erd.md
    title: Sales domain ERD
---

# Schema

| Column | Type | Description |
|--------|------|-------------|
| `customer_id` | STRING | Primary key |
| `email` | STRING | Customer email (hashed in prod) |
| `created_at` | TIMESTAMP | Registration date |
| `ltv_usd` | NUMERIC | Lifetime value in USD |

# Joins

- Referenced by [orders](./orders.md) on `customer_id`

# Privacy Note

PII fields are hashed in production. See [internal ERD](/references/sales-erd.md) 
for the full privacy classification.[^internal-erd]

[^internal-erd]: Sales domain ERD
```

### metrics/gross-revenue.md

```markdown
---
type: Metric
title: Gross Revenue
description: Total revenue before refunds and discounts.
tags: [revenue, finance, kpi]
status: stable
generated: { by: human:analyst, at: 2026-05-28T14:30:00Z }
verified: { by: human:finance-lead, at: 2026-06-01T09:00:00Z }
stale_after: 2026-12-31T00:00:00Z
sources:
  - id: gaap-rev
    resource: https://www.fasb.org/revenue-recognition
    title: GAAP Revenue Recognition Standard
    author: org:fasb
---

# Definition

Sum of `total_usd` from [orders](/tables/orders.md) for a given period.[^gaap-rev]
Does not subtract refunds — see Net Revenue for that.

# SQL

```sql
SELECT DATE_TRUNC(placed_at, MONTH) as month,
       SUM(total_usd) as gross_revenue
FROM `acme.sales.orders`
GROUP BY 1
```

# Related

- Source table: [orders](/tables/orders.md)
- Counterpart: Net Revenue (gross minus refunds)

[^gaap-rev]: GAAP Revenue Recognition Standard
```

---

## 3. SaaS Incident Playbooks (v0.2)

```
incidents/
├── index.md
├── alerts/
│   ├── index.md
│   ├── api-latency-p99.md
│   └── db-connections.md
└── runbooks/
    ├── index.md
    └── escalate-incident.md
```

### alerts/api-latency-p99.md

```markdown
---
type: Alert
title: API Latency P99 > 2s
description: Fires when 99th percentile API latency exceeds 2 seconds for 5 minutes.
tags: [api, latency, critical]
status: stable
generated: { by: human:sre-lead, at: 2026-06-01T09:00:00Z }
verified: { by: human:oncall-rotation, at: 2026-06-15T14:00:00Z }
stale_after: 2026-09-01T00:00:00Z
sources:
  - id: sla-doc
    resource: https://wiki.internal/sla/api-latency
    title: API Latency SLA Definition
    author: team:platform-eng
    last_modified: 2026-03-01T00:00:00Z
---

# Trigger Condition

```promql
histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) > 2
```

# Impact

Users experience timeouts. Downstream services may cascade-fail.

# Response

1. Check [DB connections alert](./db-connections.md) — often the root cause
2. Follow [escalation runbook](/runbooks/escalate-incident.md) if not resolved in 10 min
3. Check deployment log for recent changes

# SLA Context

Per the SLA definition,[^sla-doc] P99 latency must stay under 2s during 
business hours. Violations trigger PagerDuty.

[^sla-doc]: API Latency SLA Definition
```

### runbooks/escalate-incident.md

```markdown
---
type: Runbook
title: Escalate Incident
description: Steps to escalate when on-call cannot resolve within SLA.
tags: [oncall, incident, escalation]
status: stable
generated: { by: human:sre-manager, at: 2026-06-01T09:00:00Z }
verified:
  - { by: human:oncall-rotation, at: 2026-06-10T14:00:00Z }
  - { by: process:runbook-tester, at: 2026-06-12T02:00:00Z }
sources:
  - id: incident-policy
    resource: https://wiki.internal/incident-management-policy
    title: Incident Management Policy
    author: team:engineering-leadership
---

# When to Escalate

Per the incident management policy:[^incident-policy]

- Alert not resolved within 10 minutes
- Customer-facing impact confirmed
- Multiple alerts firing simultaneously

# Steps

1. Post in #incidents Slack channel with alert link
2. Page the secondary on-call (PagerDuty)
3. If P1: page Engineering Manager
4. Start incident document from template
5. Update status page if customer-facing

# Contacts

| Role | Who | Method |
|------|-----|--------|
| Secondary on-call | Rotation | PagerDuty |
| Eng Manager | @manager | Slack DM |
| Infra lead | @infra-lead | Slack DM |

[^incident-policy]: Incident Management Policy
```

---

## 4. API Documentation (v0.2)

```
api/
├── index.md
├── auth/
│   ├── index.md
│   └── oauth2-flow.md
├── endpoints/
│   ├── index.md
│   └── create-order.md
└── policies/
    ├── index.md
    └── rate-limits.md
```

### endpoints/create-order.md

```markdown
---
type: API Endpoint
title: Create Order
description: Creates a new order for an authenticated customer.
resource: https://api.acme.com/v2/orders
tags: [orders, write, v2]
status: stable
generated: { by: openapi-importer/1.0, at: 2026-05-20T10:00:00Z }
verified: { by: human:api-owner, at: 2026-05-25T14:00:00Z }
stale_after: 2026-11-20T00:00:00Z
sources:
  - id: openapi-spec
    resource: /references/openapi.yaml
    title: OpenAPI Specification v2
    author: team:api-platform
    last_modified: 2026-05-18T00:00:00Z
---

# POST /v2/orders

Creates a new order. Requires [OAuth2 authentication](/auth/oauth2-flow.md).

# Request

```json
{
  "customer_id": "cust_abc123",
  "items": [{"sku": "WIDGET-01", "quantity": 2}],
  "idempotency_key": "unique-request-id"
}
```

# Response (201 Created)

```json
{
  "order_id": "ord_xyz789",
  "status": "pending",
  "total_usd": 49.98,
  "created_at": "2026-05-20T10:30:00Z"
}
```

# Errors

| Code | Meaning |
|------|---------|
| 400 | Invalid request body |
| 401 | Missing or invalid auth token |
| 409 | Duplicate idempotency_key |
| 429 | [Rate limit](/policies/rate-limits.md) exceeded |

# Rate Limits

Subject to [rate limiting](/policies/rate-limits.md). See `X-RateLimit-*` headers.

[^openapi-spec]: OpenAPI Specification v2
```

### policies/rate-limits.md

```markdown
---
type: Policy
title: Rate Limits
description: Per-plan rate limits for all API endpoints.
tags: [policy, rate-limit, api]
status: stable
generated: { by: human:api-product-manager, at: 2026-05-20T10:00:00Z }
verified: { by: human:engineering-lead, at: 2026-05-22T16:00:00Z }
sources:
  - id: pricing-page
    resource: https://acme.com/pricing
    title: Pricing Page
    author: team:marketing
    usage_count: 50000
    last_modified: 2026-04-01T00:00:00Z
usage_window: { from: 2026-05-01T00:00:00Z, to: 2026-05-31T00:00:00Z }
---

# Limits by Plan

| Plan | Requests/min | Burst |
|------|-------------|-------|
| Free | 60 | 10 |
| Pro | 600 | 100 |
| Enterprise | 6000 | 1000 |

Plan limits are defined on our [pricing page].[^pricing-page]

# Response Headers

Every response includes:
- `X-RateLimit-Limit`: max requests per window
- `X-RateLimit-Remaining`: requests left in window
- `X-RateLimit-Reset`: Unix timestamp of window reset

# When Exceeded

Returns `429 Too Many Requests`. Retry after `X-RateLimit-Reset`.
Applies to all endpoints including [create order](/endpoints/create-order.md).

[^pricing-page]: Pricing Page
```

---

## 5. Minimal Bundle (v0.2 Conformant)

The absolute minimum for conformance — just `type` is required:

```
minimal/
└── concept.md
```

### concept.md

```markdown
---
type: Note
---

This is a minimal conformant OKF v0.2 document.
```

---

## Trust Tier Examples

### Unverified (no `verified` key)

```yaml
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T10:00:00Z }
# No verified key = unverified
```

### Machine-confirmed (non-human verifier)

```yaml
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T10:00:00Z }
verified: { by: process:schema-validator, at: 2026-06-21T02:00:00Z }
```

### Human-reviewed (human verifier)

```yaml
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T10:00:00Z }
verified:
  - { by: process:schema-validator, at: 2026-06-21T02:00:00Z }
  - { by: human:domain-expert, at: 2026-06-22T14:00:00Z }
```

---

## Lifecycle Examples

### Draft concept

```yaml
status: draft
generated: { by: human:author, at: 2026-06-20T10:00:00Z }
# No verified, no stale_after — work in progress
```

### Stable with expiration

```yaml
status: stable
generated: { by: human:author, at: 2026-06-20T10:00:00Z }
verified: { by: human:reviewer, at: 2026-06-25T14:00:00Z }
stale_after: 2026-12-31T00:00:00Z
```

### Deprecated

```yaml
status: deprecated
generated: { by: human:author, at: 2026-01-15T10:00:00Z }
# Kept for links and history, no longer current
```

# Open Knowledge Format (OKF)

**Version 0.1 — Draft**

OKF is an open, human- and agent-friendly format for representing
*knowledge* — the metadata, context, and curated insight that surrounds
data and systems. It is designed to be authored by people, generated by
agents, exchanged across organizations, and consumed by both.

The format is intentionally minimal: a directory of markdown files with
YAML frontmatter. There is no schema registry, no central authority, and
no required tooling. If you can `cat` a file, you can read OKF; if you
can `git clone` a repo, you can ship it.

---

## 1. Motivation

The space of knowledge representation for AI agents is evolving quickly,
and many incompatible conventions are emerging. OKF takes the position
that knowledge is best represented in commonly accessible, established
formats that are:

- **Readable** by humans without tooling.
- **Parseable** by agents without bespoke SDKs.
- **Diffable** in version control.
- **Portable** across tools, organizations, and time.

The format is minimally opinionated. It standardizes only the small set
of structural conventions needed to make a knowledge corpus
*self-describing* — anything beyond that is left to the producer.

### Goals

1. Define a universal format that **enrichment agents** can write into.
2. Inform how **consumption agents** should read and traverse it.
3. Facilitate **exchange** of knowledge across systems and organizations.
4. Standardize the small number of **required** fields that must be
   present for content to be meaningfully consumed.

### Non-goals

- Defining a fixed taxonomy of concept types.
- Prescribing storage, serving, or query infrastructure.
- Replacing domain-specific schemas (Avro, Protobuf, OpenAPI, etc.) —
  OKF *references* them; it does not subsume them.

---

## 2. Terminology

- **Knowledge Bundle** — A self-contained, hierarchical collection of
  knowledge documents. The unit of distribution.
- **Concept** — A single unit of knowledge within a bundle. Represented
  as one markdown document. May describe a tangible asset (a table, an
  API), an abstract idea (a metric, a business process), or anything in
  between.
- **Concept ID** — The path of the concept's file within the bundle,
  with the `.md` suffix removed. For example, `tables/users.md` has
  concept ID `tables/users`.
- **Frontmatter** — YAML metadata block delimited by `---` at the top of
  a markdown file.
- **Body** — Everything in the file after the frontmatter.
- **Link** — A standard markdown link from one concept to another, used
  to express relationships beyond the implicit parent/child hierarchy.
- **Citation** — A link from a concept to an external source that
  supports a claim in the body.

---

## 3. Bundle Structure

A bundle is a directory tree of markdown files. The directory structure
is independent of the domain — producers organize concepts however makes
sense for the knowledge being captured.

```
path/to/bundle/
├── index.md                      # Optional. Directory listing for progressive disclosure.
├── log.md                        # Optional. Chronological history of updates.
├── <concept>.md                  # A concept at the bundle root.
└── <subdirectory>/               # Subdirectories organize concepts into groups.
    ├── index.md
    ├── <concept>.md
    └── <subdirectory>/
        └── …
```

A bundle MAY be distributed as:

- A git repository (recommended — provides history, attribution, diffs).
- A tarball or zip archive of the directory.
- A subdirectory within a larger repository.

### 3.1 Reserved filenames

The following filenames have defined meaning at any level of the
hierarchy and MUST NOT be used for concept documents:

| Filename     | Purpose                                                |
|--------------|--------------------------------------------------------|
| `index.md`   | Directory listing. See §6.                             |
| `log.md`     | Update history. See §7.                                |

All other `.md` files are concept documents.

Tags themselves remain a first-class concept — see the `tags`
frontmatter field in §4.1. OKF does not specify a separate file format
for aggregating documents by tag; producers that want a tag-browsing
view can synthesize one at consumption time by scanning frontmatter.

---

## 4. Concept Documents

Every concept is a UTF-8 markdown file. It has two parts:

1. A **YAML frontmatter block**, delimited by `---` on its own line at
   the start of the file and a closing `---` on its own line.
2. A **markdown body**, containing free-form content.

### 4.1 Frontmatter

```yaml
---
type: <Type name>                  # REQUIRED
title: <Optional display name>
description: <Optional one-line summary>
resource: <Optional canonical URI for the underlying asset>
tags: [<tag>, <tag>, …]            # Optional
timestamp: <ISO 8601 datetime>     # Optional last-modified time
# … other producer-defined key/value pairs
---
```

**Required:**

- `type` — A short string identifying the kind of concept. Consumers
  use this for routing, filtering, and presentation. Example values:
  `BigQuery Table`, `BigQuery Dataset`, `API Endpoint`, `Metric`,
  `Playbook`, `Reference`.

  Type values are **not** registered centrally. Producers SHOULD pick
  values that are descriptive and self-explanatory; consumers MUST
  tolerate unknown types gracefully (typically by treating them as
  generic concepts).

**Recommended (in priority order):**

- `title` — Human-readable display name. If omitted, consumers MAY
  derive a title from the filename.
- `description` — A single sentence summarizing the concept. Used by
  `index.md` generators, search snippets, and previews.
- `resource` — A URI that uniquely identifies the underlying asset the
  concept describes. Absent for concepts that describe abstract ideas
  rather than physical resources.
- `tags` — A YAML list of short strings for cross-cutting categorization.
- `timestamp` — ISO 8601 datetime of last meaningful change.

**Extensions:** Producers MAY include any additional keys. Consumers
SHOULD preserve unknown keys when round-tripping and SHOULD NOT reject
documents with unrecognized fields.

### 4.2 Body

The body is standard markdown. Producers SHOULD favor structural
markdown — headings, lists, tables, fenced code blocks — over freeform
prose, since structure aids both human reading and agent retrieval.

There are no required body sections. The following section headings have
**conventional** meaning and SHOULD be used when applicable:

| Heading        | Purpose                                                |
|----------------|--------------------------------------------------------|
| `# Schema`     | Structured description of an asset's columns/fields.   |
| `# Examples`   | Concrete usage examples, often as fenced code blocks.  |
| `# Citations`  | External sources backing claims in the body. See §8.   |

### 4.3 Example: a concept bound to a resource

```markdown
---
type: BigQuery Table
title: Customer Orders
description: One row per completed customer order across all channels.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
timestamp: 2026-05-28T14:30:00Z
---

# Schema

| Column        | Type      | Description                              |
|---------------|-----------|------------------------------------------|
| `order_id`    | STRING    | Globally unique order identifier.        |
| `customer_id` | STRING    | Foreign key into [customers](/tables/customers.md). |
| `total_usd`   | NUMERIC   | Order total in US dollars.               |
| `placed_at`   | TIMESTAMP | When the customer submitted the order.   |

# Joins

Joined with [customers](/tables/customers.md) on `customer_id`.

# Citations

[1] [BigQuery table schema](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)
```

### 4.4 Example: a concept not bound to a resource

```markdown
---
type: Playbook
title: Incident response — data freshness alert
description: Steps to triage a freshness alert on the orders pipeline.
tags: [oncall, incident]
timestamp: 2026-04-12T09:00:00Z
---

# Trigger

A freshness alert fires when `orders` lags more than 30 minutes behind
its expected SLA. See the [orders table](/tables/orders.md).

# Steps

1. Check the [ingestion job dashboard](https://example.com/dash).
2. …
```

---

## 5. Cross-linking

Concepts MAY link to other concepts using standard markdown links. Two
forms are supported:

### 5.1 Absolute (bundle-relative) links

Begin with `/`, interpreted relative to the bundle root.

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

This is the **recommended** form because it is stable when documents are
moved within their subdirectory.

### 5.2 Relative links

Standard markdown relative paths.

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

### 5.3 Link semantics

A link from concept A to concept B asserts a *relationship*. The
specific kind of relationship (parent/child, references, joins-with,
depends-on, etc.) is conveyed by the surrounding prose, not by the link
itself. Consumers that build a graph view typically treat all links as
directed edges of an untyped relationship.

Consumers MUST tolerate broken links — a link whose target does not
exist in the bundle is not malformed; it may simply represent
not-yet-written knowledge.

---

## 6. Index Files

An `index.md` file MAY appear in any directory, including the bundle
root. It enumerates the directory's contents to support **progressive
disclosure** — letting a human or agent see what is available before
opening individual documents.

Index files contain no frontmatter. The body uses one or more sections,
each grouping concepts under a heading:

```markdown
# Section / Group Heading

* [Title 1](relative-url-1) - short description of item 1
* [Title 2](relative-url-2) - short description of item 2

# Another Section

* [Subdirectory](subdir/) - short description of the subdirectory
```

Entries SHOULD include the description from the linked concept's
frontmatter. Producers MAY generate `index.md` automatically; consumers
MAY synthesize one on the fly when none is present.

---

## 7. Log Files (optional)

A `log.md` file MAY appear at any level of the hierarchy to record the
history of changes to that scope. The format is a flat list of
date-grouped entries, newest first:

```markdown
# Directory Update Log

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

## 2026-05-15
* **Initialization**: Created foundational directory structure.
* **Update**: Added progressive-disclosure guidelines to the root [index](/index.md).
```

Date headings MUST use ISO 8601 `YYYY-MM-DD` form. Log entries are
prose; the leading bold word (`**Update**`, `**Creation**`,
`**Deprecation**`, etc.) is a convention, not a requirement.

---

## 8. Citations

When a concept's body makes claims sourced from external material,
those sources SHOULD be listed under a `# Citations` heading at the
bottom of the document, numbered:

```markdown
# Citations

[1] [BigQuery public dataset announcement](https://cloud.google.com/blog/products/data-analytics/...)
[2] [Internal data quality runbook](https://wiki.acme.internal/data/quality)
```

Citation links MAY be absolute URLs, bundle-relative paths, or paths
into a `references/` subdirectory that mirrors external material as
first-class OKF concepts.

---

## 9. Conformance

A bundle is **conformant** with OKF v0.1 if:

1. Every non-reserved `.md` file in the tree contains a parseable YAML
   frontmatter block.
2. Every frontmatter block contains a non-empty `type` field.
3. Every reserved filename (`index.md`, `log.md`) follows the structure
   described in §6 and §7 respectively when present.

Consumers SHOULD treat all other constraints as soft guidance. In
particular, consumers MUST NOT reject a bundle because of:

- Missing optional frontmatter fields.
- Unknown `type` values.
- Unknown additional frontmatter keys.
- Broken cross-links.
- Missing `index.md` files.

This permissive consumption model is intentional: OKF is meant to
remain useful as bundles grow, get refactored, and are partially
generated by agents.

---

## 10. Relationship to other formats

OKF is intentionally close to several established patterns:

- **LLM "wiki" repositories** that use markdown + frontmatter as
  agent-readable knowledge bases.
- **Personal knowledge tools** like Obsidian and Notion, which use
  hierarchical markdown with cross-links.
- **"Metadata as code"** approaches that store catalog metadata
  alongside source code rather than in a separate registry.

OKF differs primarily in being **specified** — pinning down the small
set of rules needed for interoperability without dictating tooling.

---

## 11. Versioning

This document specifies OKF version **0.1**. Future revisions will be
versioned in the form `<major>.<minor>`:

- A **minor** version bump introduces backward-compatible additions
  (new optional fields, new conventional section headings).
- A **major** version bump may make breaking changes (renaming required
  fields, changing reserved filenames).

Bundles MAY declare the OKF version they target by including
`okf_version: "0.1"` in a bundle-root `index.md` frontmatter block (the
only place frontmatter is permitted in an `index.md`). Consumers that
do not understand the declared version SHOULD attempt best-effort
consumption rather than refusing the bundle.

---

## Appendix A — Minimal example bundle

```
my_bundle/
├── index.md
├── datasets/
│   ├── index.md
│   └── sales.md
└── tables/
    ├── index.md
    ├── orders.md
    └── customers.md
```

`datasets/sales.md`:

```markdown
---
type: BigQuery Dataset
title: Sales
description: All sales-related tables for the retail business.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales
tags: [sales]
timestamp: 2026-05-28T00:00:00Z
---

The sales dataset contains transactional tables, including
[orders](/tables/orders.md) and [customers](/tables/customers.md).
```

`tables/orders.md`:

```markdown
---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders]
timestamp: 2026-05-28T00:00:00Z
---

# Schema

| Column        | Type      | Description                  |
|---------------|-----------|------------------------------|
| `order_id`    | STRING    | Unique order identifier.     |
| `customer_id` | STRING    | FK to [customers](/tables/customers.md). |
| `total_usd`   | NUMERIC   | Order total in USD.          |

Part of the [sales dataset](/datasets/sales.md).
```

# Open Knowledge Format (OKF)

**Version 0.2**

OKF is an open, human- and agent-friendly format for representing
*knowledge*: the metadata, context, and curated insight that surrounds
data and systems. It is designed to be authored by people, generated by
agents, exchanged across organizations, and consumed by both.

The format is intentionally minimal: a directory of markdown files with
YAML frontmatter. There is no schema registry, no central authority, and
no required tooling. If you can `cat` a file, you can read OKF; if you
can `git clone` a repo, you can ship it.

This document is self-contained: it specifies everything needed to
produce and consume OKF v0.2. A summary of what changed from v0.1 is in
§13.

---

## 1. Motivation

The space of knowledge representation for AI agents is evolving quickly,
and many incompatible conventions are emerging. OKF takes the position
that knowledge is best represented in commonly accessible, established
formats that are:

- **Readable** by humans without tooling.
- **Parseable** by agents without bespoke SDKs.
- **Diffable** in version control.
- **Portable** across tools, organizations, and time.

Increasingly, a knowledge corpus is not authored once and then read: it
is **continuously written and maintained by agents**. When most concepts 
are machine-generated, a consumer needs answers that a plain 
markdown-plus-frontmatter convention does not make first-class:

1. What was this created from, and how was it verified? (**provenance**)
2. How much should I trust it? (**trust**)
3. Is it still true? (**freshness**)
4. Is it the current version? (**lifecycle**)
5. Was this number produced the way we said it must be? (**attestation**)

OKF v0.2 makes provenance, trust, lifecycle, and attestation first-class
while keeping the format minimally opinionated. The format is minimally 
opinionated. It standardizes only the small set of structural conventions 
needed to make a knowledge corpus self-describing — anything beyond that
is left to the producer.

### Goals

1. Define a universal format that **producers** (people, agents, export
   pipelines) can write into.
2. Inform how **consumers** (agents, UIs, search indexes, deterministic
   code) should read and traverse it.
3. Facilitate **exchange** of knowledge across systems and organizations.
4. Standardize the small set of frontmatter fields that make an
   agent-maintained corpus **trustable**, without prescribing any runtime.

### Non-goals

- Defining a fixed taxonomy of concept types.
- Prescribing storage, serving, or query infrastructure.
- Replacing domain-specific schemas (Avro, Protobuf, OpenAPI, and so on).
  OKF *references* them; it does not subsume them.
- Specifying a packaging or invocation standard for the code an executor
  or attester points at. OKF fixes the interface, not the packaging.

---

## 2. Terminology

- **Knowledge Bundle** (or **bundle**): A self-contained, hierarchical
  collection of knowledge documents. The unit of distribution.
- **Concept**: A single unit of knowledge within a bundle, represented as
  one markdown document. It may describe a tangible asset (a table, an
  API), an abstract idea (a metric, a business process), or anything in
  between.
- **Concept ID**: The path of the concept's file within the bundle, with
  the `.md` suffix removed.
- **Frontmatter**: A YAML metadata block delimited by `---` at the top of
  a markdown file.
- **Body**: Everything in the file after the frontmatter.
- **Link**: A standard markdown link from one concept to another, used to
  express relationships beyond the implicit parent/child hierarchy.
- **Source**: A material a concept derives from, external or internal to
  the bundle, recorded in the `sources` frontmatter field.
- **Provenance**: The set of sources a concept derives from.
- **Credibility signal**: An objective, per-source fact (`author`,
  `usage_count`, `last_modified`) used to infer trust; OKF records the
  signals, not a verdict (see §5.1).
- **Actor**: A string identifying who or what performed an action, using
  the convention `<producer>/<version>` for agents, `human:<id>` for
  people, and `process:<id>` for automated processes (see §7).
- **Trust tier**: A level derived from a concept's `verified` field:
  unverified, machine-confirmed, or human-reviewed (see §5.3).
- **Attested Computation**: A concept (`type: Attested Computation`)
  carrying a sanctioned way to compute a value, so a consumer can confirm
  the value was produced by running it (see §10).
- **Executor**: Run instructions or code that executes a computation and
  returns a receipt (see §10.2).
- **Receipt**: The evidence a run returns, shaped by `executor.receipt`; a
  runtime artifact, not stored in the bundle (see §10).
- **Attester**: Deterministic (no-LLM) code that inspects a receipt and
  returns a verdict (see §10.2).

---

## 3. Bundle structure

A bundle is a directory tree of markdown files. The directory structure
is independent of the domain: producers organize concepts however makes
sense for the knowledge being captured.

```
path/to/bundle/
  index.md                      # Optional. Directory listing for progressive disclosure.
  log.md                        # Optional. Chronological history of updates.
  <concept>.md                  # A concept at the bundle root.
  <subdirectory>/               # Subdirectories organize concepts into groups.
    index.md
    <concept>.md
    <subdirectory>/
      ...
```

A bundle MAY be distributed as:

- A git repository (recommended, since it provides history, attribution,
  and diffs).
- A tarball or zip archive of the directory.
- A subdirectory within a larger repository.

### 3.1 Reserved filenames

The following filenames have defined meaning at any level of the
hierarchy and MUST NOT be used for concept documents:

| Filename   | Purpose                          |
|------------|----------------------------------|
| `index.md` | Directory listing. See §8.       |
| `log.md`   | Update history. See §9.          |

All other `.md` files are concept documents.

Tags remain a first-class concept through the `tags` frontmatter field
(§4.1). OKF does not specify a separate file format for aggregating
documents by tag; a consumer that wants a tag-browsing view can
synthesize one at consumption time by scanning frontmatter.

---

## 4. Concept documents

Every concept is a UTF-8 markdown file with two parts:

1. A **YAML frontmatter block**, delimited by `---` on its own line at the
   start of the file and a closing `---` on its own line.
2. A **markdown body**, containing free-form content.

### 4.1 Frontmatter

```yaml
---
type: <Type name>                  # REQUIRED
title: <Optional display name>
description: <Optional one-line summary>
resource: <Optional canonical URI for the underlying asset>
tags: [<tag>, <tag>, ...]          # Optional
# ... trust, lifecycle, provenance, and computation families (see §5, §10)
# ... other producer-defined key/value pairs
---
```

**Required:**

- `type`: A short string identifying the kind of concept. Consumers use it
  for routing, filtering, and presentation. Example values:
  `BigQuery Table`, `BigQuery Dataset`, `API Endpoint`, `Metric`,
  `Playbook`, `Reference`, `Attested Computation`.

  Type values are **not** registered centrally. Producers SHOULD pick
  values that are descriptive and self-explanatory; consumers MUST
  tolerate unknown types gracefully, typically by treating them as generic
  concepts.

`type` is the only always-required key; a concept carrying just `type` is
fully conformant (§11).

**Recommended:**

- `title`: Human-readable display name. If omitted, consumers MAY derive a
  title from the filename.
- `description`: A single sentence summarizing the concept. Used by
  `index.md` generators, search snippets, and previews.
- `resource`: A URI that uniquely identifies the underlying asset the
  concept describes. Absent for concepts that describe abstract ideas
  rather than physical resources.
- `tags`: A YAML list of short strings for cross-cutting categorization.

The optional **provenance**, **trust**, and **lifecycle** families (§5) and
the **computation** fields for Attested Computation concepts (§10) may also
appear.

**Extensions:** Producers MAY include any additional keys. Consumers
SHOULD preserve unknown keys when round-tripping and MUST NOT reject
documents with unrecognized fields.

### 4.2 Body

The body is standard markdown. Producers SHOULD favor structural markdown
(headings, lists, tables, fenced code blocks) over freeform prose, since
structure aids both human reading and agent retrieval.

There are no required body sections. The following headings have
**conventional** meaning and SHOULD be used when applicable:

| Heading         | Purpose                                                |
|-----------------|--------------------------------------------------------|
| `# Schema`      | Structured description of an asset's columns/fields.   |
| `# Examples`    | Concrete usage examples, often as fenced code blocks.  |
| `# Computation` | The sanctioned computation of an Attested Computation. See §10. |

Per-claim attribution to external sources uses markdown footnotes keyed to
`sources` entries rather than a body citations list (§5.1).

### 4.3 Example: a concept bound to a resource

```markdown
---
type: BigQuery Table
title: Customer Orders
description: One row per completed customer order across all channels.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-05-28T14:30:00Z }
---

# Schema

| Column        | Type      | Description                              |
|---------------|-----------|------------------------------------------|
| `order_id`    | STRING    | Globally unique order identifier.        |
| `customer_id` | STRING    | Foreign key into [customers](/tables/customers.md). |
| `total_usd`   | NUMERIC   | Order total in US dollars.               |
| `placed_at`   | TIMESTAMP | When the customer submitted the order.   |

# Joins

Joined with [customers](/tables/customers.md) on `customer_id`.
```

### 4.4 Example: a concept not bound to a resource

```markdown
---
type: Playbook
title: "Incident response: data freshness alert"
description: Steps to triage a freshness alert on the orders pipeline.
tags: [oncall, incident]
generated: { by: human:ahormati, at: 2026-04-12T09:00:00Z }
---

# Trigger

A freshness alert fires when `orders` lags more than 30 minutes behind its
expected SLA. See the [orders table](/tables/orders.md).

# Steps

1. Check the [ingestion job dashboard](https://example.com/dash).
2. ...
```

---

## 5. Provenance, trust, and lifecycle

These frontmatter families make "where did this come from," "how much
should I trust it," and "is it still current" answerable from frontmatter.
All are optional. Their absence carries meaning: an unverified concept is
distinguishable from a verified one, but is never rejected (§11).

Every timestamp-valued key in OKF is an ISO 8601 datetime with an explicit
UTC offset, for example `2026-06-30T14:00:00Z`.

### 5.1 Provenance: `sources`

`sources` records the materials a concept derives from, external or
internal to the bundle.

```yaml
sources:
  - id: ga4-schema
    resource: https://developers.google.com/analytics/bigquery/export-schema
    title: GA4 BigQuery Export schema
    author: team:ga4-docs
    usage_count: 5000
    last_modified: 2026-05-30T00:00:00Z
usage_window: { from: 2026-06-01T00:00:00Z, to: 2026-06-30T00:00:00Z }
```

Each `sources` entry:

- `resource`: REQUIRED within an entry. Names either a concrete artifact a
  consumer can follow (an absolute URL, a bundle-relative path, or a path
  into a `references/` subdirectory, §6) or a population or scope descriptor
  it cannot (for example `all queries in BigQuery project X`).
- `id`: Optional. A stable key used to attribute individual claims (see
  below). SHOULD be present when the body cites the source.
- `title`: Optional. Human-readable label for the source.
- The optional credibility signals `author`, `usage_count`, and
  `last_modified`, described next.

**Source credibility signals.** OKF records objective, per-source signals
so a consumer can judge how much to trust a concept by judging the sources
it was extracted from. It does not store a credibility score: a score is
subjective, unportable across consumers, and goes stale. Credibility is
*inferred* from the signals, the same way trust tiers are (§5.3), not
stored. Each signal is optional and lives on a `sources` entry:

- `author`: Who or what produced the source, in the actor convention (§7).
  An authority signal.
- `usage_count`: How often `resource` was exercised (dashboard views, query
  executions, page reads) over `usage_window`. An adoption and liveness
  signal. For a single artifact it is that artifact's own exercise count;
  for a scope descriptor it is the number of exercises within the scope that
  touch the concept.
- `last_modified`: When the source itself last changed. A recency signal,
  distinct from `generated.at` (§5.2), which records when the concept was
  written.
- `usage_window`: Written once as a sibling of `sources`, it frames every
  `usage_count` with a `{ from, to }` datetime range. A single entry MAY
  carry its own `usage_window` to override the shared one.

`usage_count` is a coarse signal. It is comparable at the
alive-versus-dead and order-of-magnitude level, and against a source's own
history over time, but not as a precise cross-kind ranking: a scheduled
query's executions and a human's deliberate dashboard views do not carry
equal weight. Consumers SHOULD read it as liveness and trend, not as a
score.

Lineage is expressed through links, not a dedicated field. When a
`resource` points at another OKF concept, the derivation edge already
exists in the bundle graph (§6), so a consumer MAY recurse into that
source's own `sources` and let credibility propagate. External leaf sources
carry only their intrinsic signals. Deeper lineage (an explicit external
`derived_from`, or data lineage) is out of scope for v0.2.

**Per-claim attribution.** To attribute a specific claim, use a markdown
footnote whose label is a `sources[].id`:

```markdown
The `events_` table is sharded daily as `events_YYYYMMDD`.[^ga4-schema]

[^ga4-schema]: GA4 BigQuery Export schema
```

The footnote label is the join key into `sources`; consumers resolve
attribution through the matching entry, not by parsing the footnote prose.
Labels are keyed rather than positional (`sources[0]`) because agents
constantly rewrite these documents: a positional index misattributes
silently the moment the list is reordered, whereas a stable `id` survives
reordering.

### 5.2 Trust: `generated` and `verified`

`generated` records how the current content was produced. `verified`
records who or what has confirmed the content against its sources or
`resource`. They are kept distinct because who *wrote* a concept need not
be who *confirmed* it.

```yaml
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
```

- `generated.by`: REQUIRED within `generated`. An actor (§7).
- `generated.at`: An ISO 8601 datetime marking the content's last
  meaningful change. Consumers use it to tell a recent edit from a stale
  fact.

```yaml
verified:
  - { by: human:ahormati, at: 2026-06-25T09:00:00Z }
  - { by: process:finance-nightly, at: 2026-06-26T02:00:00Z }
```

- `verified`: A list of verification events, each with `by` (an actor) and
  `at` (an ISO 8601 datetime). Multiple entries capture independent
  checks, for example a human sign-off plus a nightly process. "How
  recently" is the latest `at`.
- `verified` is independent of `generated.at`: content can change without
  re-confirmation, and facts can be re-confirmed without regeneration.
- A single verifier MAY be written as one `{ by, at }` mapping without the
  list dash. Consumers MUST treat a bare mapping as a one-element list:

```yaml
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
```

### 5.3 Trust tiers

Consumers derive a trust tier from `verified`, lowest to highest:

- No `verified` key => **unverified**.
- `verified` by non-`human:` actors only => **machine-confirmed**.
- `verified` by a `human:<id>` actor => **human-reviewed**.

A concept with no trust frontmatter is still consumable; consumers MUST
NOT reject it (§11). Trust tiers are advisory signals, not access control.

### 5.4 Lifecycle: `status`

```yaml
status: stable        # draft | stable | deprecated
```

- `draft`: not yet reviewed; possibly incomplete.
- `stable`: default; ready for consumption.
- `deprecated`: kept for links and history; no longer current.

Absent `status` => `stable`.

### 5.5 Lifecycle: `stale_after`

```yaml
stale_after: 2026-09-23T00:00:00Z   # content is stale on/after this instant
```

Optional. An absolute instant. A concept is stale when
`now >= stale_after`. An absolute instant, not a relative TTL, keeps the
staleness decision a plain comparison with no reference to when the
concept was read.

---

## 6. Cross-linking and paths

### 6.1 Links between concepts

Concepts MAY link to other concepts using standard markdown links. Two
forms are supported:

- **Absolute (bundle-relative):** begins with `/`, interpreted relative to
  the bundle root. This is the **recommended** form because it is stable
  when documents are moved within their subdirectory.

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

- **Relative:** a standard markdown relative path.

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

A link from concept A to concept B asserts a *relationship*. The specific
kind (parent/child, references, joins-with, depends-on) is conveyed by the
surrounding prose, not by the link itself. Consumers that build a graph
view typically treat all links as directed edges of an untyped
relationship.

Consumers MUST tolerate broken links: a link whose target does not exist
in the bundle is not malformed; it may simply represent not-yet-written
knowledge.

### 6.2 Path-valued fields

Several fields name a path or URI: `resource`, `sources[].resource`,
`computation`, `executor.resource`, and `attester.resource` (§10). A
`sources[].resource` may instead be a scope descriptor (§5.1), in which
case it is not a path. Each path-valued field accepts:

- an absolute URL (for example `https://...`),
- a bundle-relative path beginning with `/`, or
- a relative path (for example `../computations/revenue.md`).

### 6.3 The `references/` convention

A `references/` subdirectory conventionally mirrors external material, run
instructions, or code as first-class concepts within the bundle. Sources,
executors, and attesters commonly point into it (for example
`references/attesters/revenue.py`). It is a naming convention, not a
requirement.

---

## 7. Actor convention

Fields that record an identity (`generated.by`, `verified[].by`) use a
single actor convention:

- `<producer>/<version>` for agents and tools, for example
  `reference_agent/gemini-2.5-pro`.
- `human:<id>` for a person, for example `human:ahormati`.
- `process:<id>` for an automated process, for example
  `process:finance-nightly`.

Consumers that classify trust (§5.3) key off the `human:` prefix, so
producers MUST use it for hand-authored or human-confirmed content.

---

## 8. Index files

An `index.md` file MAY appear in any directory, including the bundle root.
It enumerates the directory's contents to support **progressive
disclosure**: letting a human or agent see what is available before
opening individual documents.

Index files contain no frontmatter, with one exception: a bundle-root
`index.md` MAY carry an `okf_version` key (§12). The body uses one or more
sections, each grouping concepts under a heading:

```markdown
# Section / Group Heading

* [Title 1](relative-url-1) - short description of item 1
* [Title 2](relative-url-2) - short description of item 2

# Another Section

* [Subdirectory](subdir/) - short description of the subdirectory
```

Entries SHOULD include the description from the linked concept's
frontmatter. Producers MAY generate `index.md` automatically; consumers
MAY synthesize one on the fly when none is present.

---

## 9. Log files

A `log.md` file MAY appear at any level of the hierarchy to record the
history of changes to that scope. The format is a flat list of
date-grouped entries, newest first:

```markdown
# Directory Update Log

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

## 2026-05-15
* **Initialization**: Created foundational directory structure.
```

Date headings MUST use ISO 8601 `YYYY-MM-DD` form. Log entries are prose;
the leading bold word (`**Update**`, `**Creation**`, `**Deprecation**`) is
a convention, not a requirement.

---

## 10. Attested computations concept

An Attested Computation concept carries not just what a value *means* but a
sanctioned way to *compute* it, so a consumer can confirm the agent ran the
blessed computation instead of improvising its own. Provenance (§5.1)
answers "where did this claim come from"; attestation answers "was this
number produced the way we said it must be." OKF records the computation
and the means to check it; it does not execute anything itself.

### 10.1 A computation is its own concept

A sanctioned computation is a standalone concept of
`type: Attested Computation`. A concept that needs the value (a `Metric`, a
`BigQuery Table`) links to it with a normal markdown link (§6). Three
properties motivate the standalone concept:

- **`runtime` defines what `parameters` mean.** A parameter is a SQL bind
  variable, a dbt var, or a Python argument depending on the runtime.
  Keeping `runtime` and `parameters` in one frontmatter makes the binding
  semantics self-evident.
- **One computation, many consumers.** The same computation can back a
  metric, a dashboard concept, and a report; as a concept it is referenced
  once and reused.
- **Trust state is per computation.** `verified`, `stale_after`, and a
  single `attester` describe one thing. Revenue, profit, and margin each
  verify and attest independently, which is three concepts, not three
  entries in one frontmatter.

### 10.2 Contract fields

The contract is the concept's top-level frontmatter. In addition to the
provenance, trust, and lifecycle families (§5), an Attested Computation
concept carries:

- `runtime`: REQUIRED for this type. The single field that says how to run
  the computation, and so how the executor and attester interpret it and
  what `parameters` mean. Example values: `bigquery`, `postgres`, `dbt`,
  `python`, `Looker`.
- `parameters`: A list of the typed, named holes the agent may fill. Each
  entry: `{ name, type, required }`. Binding semantics follow `runtime`.
- `computation`: Optional. A path (§6.2) to a file holding the
  computation, used instead of an inline body fence (see §10.3). Absent =>
  the body `# Computation` fence is the computation.
- `executor`: How the computation is run. `resource` names run
  instructions or code; a runner (an agent, or deterministic consumer
  code) follows it. `receipt` declares the fields a run must return, the
  evidence the attester inspects (for example a BigQuery `job_id` and the
  SQL the job actually executed).
- `attester`: The deterministic check. `resource` names code (no LLM) that
  takes a receipt and returns a verdict. It is meant to run consumer-side.

What sits behind a `resource` (a Skill, a script, a container) is a
packaging choice; OKF fixes the interface, not the packaging (§1).

```markdown
---
type: Attested Computation
title: Revenue for fiscal year
description: Recognized revenue for a fiscal year, per Finance's definition.
status: stable
runtime: bigquery
parameters:
  - { name: year, type: integer, required: true }
executor:
  resource: references/skills/run-on-bq.md
  receipt: [job_id, executed_sql, result]
attester:
  resource: references/attesters/revenue.py
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
stale_after: 2026-09-23T00:00:00Z
sources:
  - id: rev-policy
    resource: https://wiki.acme/finance/revenue-recognition
    title: Revenue recognition policy
---

# Computation

    SELECT SUM(amount) AS revenue
    FROM finance.recognized_revenue
    WHERE fiscal_year = @year

The computation binds only the declared `parameters`, per the recognition
policy.[^rev-policy]

[^rev-policy]: Revenue recognition policy
```

### 10.3 The computation

Provide the computation in one of two ways:

- **Inline:** a single fenced code block in the body under `# Computation`.
  Best for a short computation reviewed alongside the contract.
- **File:** set `computation` to a path (§6.2) and omit the body fence.
  Best for a long or generated computation, or one already kept as a real
  file shared with non-OKF tooling.

```yaml
runtime: bigquery
computation: references/computations/lib/revenue.sql
parameters:
  - { name: year, type: integer, required: true }
```

The agent MAY only supply *values* for the declared `parameters`; it MUST
NOT author or edit the computation. Binding `computation` with the
parameter values into the executable artifact is the consumer's job, and
the attester independently re-derives that same binding to compare against
what actually ran. Because the comparison is on the expanded, compiled
artifact the receipt carries (`executed_sql`, `compiled_sql`), a rewritten
query, a swapped computation file, or a mutated dependency fails the check.
A typed, parameter-only surface is what makes "did the sanctioned thing
run" a mechanical comparison rather than a judgement call.

### 10.4 Concepts that use a computation

A document is rarely a single computation. An income-statement overview
that discusses revenue, profit, and margin stays one readable concept and
links to one Attested Computation per figure:

```markdown
---
type: Metric
title: Revenue
description: Recognized revenue for a fiscal year.
tags: [finance, revenue]
status: stable
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
---

# Definition

Recognized revenue sums `amount` over rows booked to the fiscal year,
computed by [the revenue computation](../computations/revenue.md).
```

Because each computation is its own concept, revenue can be fresh while
profit is past its `stale_after`, and each attests on its own run.
Co-locating them is a directory choice (a `computations/` folder with an
`index.md`), not a frontmatter one.

### 10.5 How a consumer uses it (informative)

This subsection is informative, not normative. The runtime artifacts below
are **not** stored in the bundle.

1. **Discover** via `type: Attested Computation`, a frontmatter signal
   liftable into `index.md`; a consumer reaches one directly or by
   following a link from a concept that uses it.
2. **Load** the contract from frontmatter and the computation from the
   body (or the file named by `computation`).
3. **Parameterize**: the agent supplies values for the declared parameters.
4. **Execute**: the executor runs the bound computation and returns a
   receipt shaped by `executor.receipt`.
5. **Attest**: the consumer runs the attester over the receipt. It
   confirms provenance (the computation that ran equals `computation` bound
   with the claimed parameters, not agent-authored SQL) and fidelity (the
   displayed value matches the receipt's authoritative source, re-read by
   job id rather than taken from the agent's text).
6. **Gate**: refuse to display a failing attestation; warn or refuse when
   `now >= stale_after`. On success, surface the verdict (for example a
   link to the job log) so trust is visible.

### 10.6 Verification versus attestation

`verified` (§5.2) and attestation are distinct, and both exist:

- `verified` confirms the *definition* still matches policy. It is
  doc-level, slow, and recorded in the bundle.
- Attestation confirms a single *run* produced the value the sanctioned
  way. It is per-call, runtime, and not stored in the bundle.

A concept with a stale definition can still attest cleanly, and a
freshly-verified definition still requires attestation on each run, which
is why both are needed.

---

## 11. Conformance

A bundle is **conformant** with OKF v0.2 if:

1. Every non-reserved `.md` file in the tree contains a parseable YAML
   frontmatter block.
2. Every frontmatter block contains a non-empty `type` field.
3. Every reserved filename (`index.md`, `log.md`) follows the structure in
   §8 and §9 respectively when present.

When the trust, lifecycle, provenance, or computation families are
present, producers SHOULD follow §5 through §10, and consumers:

- MUST treat a bare `verified` mapping as a one-element list (§5.2).
- MUST NOT reject a concept for missing any optional family (§5.3).
- SHOULD derive trust tiers and staleness only from the fields specified
  here, and SHOULD surface, not silently drop, a failing attestation
  (§10.5).

Consumers SHOULD treat all other constraints as soft guidance. In
particular, consumers MUST NOT reject a bundle because of:

- Missing optional frontmatter fields.
- Unknown `type` values.
- Unknown additional frontmatter keys.
- Broken cross-links.
- Missing `index.md` files.

---

## 12. Versioning

This document specifies OKF version **0.2**. Revisions are versioned as
`<major>.<minor>`:

- A **minor** version bump introduces backward-compatible additions (new
  optional fields, new conventional section headings).
- A **major** version bump may make breaking changes (renaming required
  fields, changing reserved filenames).

Bundles MAY declare the version they target with `okf_version: "0.2"` in a
bundle-root `index.md` frontmatter block (the only place frontmatter is
permitted in an `index.md`). Consumers that do not understand the declared
version SHOULD attempt best-effort consumption rather than refusing the
bundle.

### Considered and deferred

The following are intentionally left to a future revision:

- The full runtime protocol: receipt and verdict wire formats, and the
  attestation lifecycle around a run.
- The attester ABI, portability, and sandboxing, likely bundled with
  future work on serving and Skills.
- Attestation caching.
- Semantic-layer templates (Looker, dbt) where the attester comparison
  shifts from SQL equality to model-and-binding equality.

---

## 13. Changes from v0.1

v0.2 supersedes OKF v0.1 and is a minor version bump under §12, except for
two deliberate breaking changes called out below because they rename or
retire v0.1 fields. A v0.1 bundle is consumable by a v0.2 consumer under
the fallbacks noted here.

### 13.1 Breaking changes

- **`timestamp` is superseded by `generated.at`.** A concept's last
  content change is now recorded as `generated: { by, at }` (§5.2).
  Consumers MAY fall back to a legacy `timestamp` when `generated` is
  absent.
- **The body `# Citations` list is superseded by `sources`.** Provenance
  moves to frontmatter (§5.1). Consumers SHOULD read `sources` and MAY
  still parse a legacy `# Citations` body list for v0.1 documents.

### 13.2 Additive changes

All of the following are additive: new optional keys, one new concept
type, and one new conventional heading. Their absence yields a plain v0.1
concept.

- New frontmatter families: `sources` with its per-source credibility
  signals (`author`, `usage_count`, `last_modified`) and the `usage_window`
  sibling; `generated`, `verified`; `status`, `stale_after` (§5).
- New concept type `Attested Computation` and its computation keys
  `runtime`, `parameters`, `computation`, `executor`, `attester` (§10).
- New conventional body heading `# Computation` (§4.2).
- The actor convention for `generated.by` and `verified[].by` (§7).

Everything else (bundle structure, reserved filenames, the required
`type`, recommended `title`/`description`/`resource`/`tags`, cross-linking,
index files, log files, permissive conformance) is carried forward
unchanged.

---

## Appendix A: Worked example, an income statement

One bundle exercising every family, shown as a v0.1 to v0.2 migration of an
income statement with two figures, revenue and gross profit.

### v0.1 form

A single doc: both figures in one concept, the SQL in prose an agent can
read, ignore, or rewrite, citations a flat list, and the only timestamp is
`timestamp`.

```markdown
---
type: Metric
title: Income statement (fiscal year)
description: Headline income-statement figures for a fiscal year.
tags: [finance, income-statement]
timestamp: '2026-05-28T22:53:05+00:00'
---

# Definition
The income statement reports revenue and gross profit for a fiscal year.

# Revenue
Recognized revenue sums `amount` over rows booked to the fiscal year:

    SELECT SUM(amount) AS revenue
    FROM finance.recognized_revenue
    WHERE fiscal_year = <year>

# Gross profit
Gross profit by segment, per the cost-allocation standard:

    SELECT gross_profit FROM fct_income_statement
    WHERE fiscal_year = <year> AND segment = <segment>

# Citations
- https://wiki.acme/finance/fpa-handbook
- https://wiki.acme/finance/revenue-recognition
- https://wiki.acme/finance/cost-allocation
```

### v0.2 form

The two figures split into attested computations linked from a narrative
concept. Every family is populated, and the two computations sit in
deliberately different states so one consumer reaches two verdicts.

```
bundles/finance/
  metrics/income-statement.md      type: Metric  (narrates, links both)
  computations/revenue.md          type: Attested Computation  (runtime: bigquery)
  computations/profit.md           type: Attested Computation  (runtime: dbt)
  references/skills/run-on-bq.md, run-dbt.md
  references/attesters/sql-equality.py, dbt-binding.py
```

`metrics/income-statement.md`, the readable doc; trust lives on what it
links, not here:

```markdown
---
type: Metric
title: Income statement (fiscal year)
description: Headline income-statement figures for a fiscal year.
tags: [finance, income-statement]
status: stable
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
stale_after: 2026-12-31T00:00:00Z
sources:
  - id: fpa-handbook
    resource: https://wiki.acme/finance/fpa-handbook
    title: FP&A reporting handbook
---

# Definition
The income statement reports [revenue](../computations/revenue.md) and
[gross profit](../computations/profit.md) for a fiscal year, per the FP&A
reporting handbook.[^fpa-handbook] Each figure is produced by a sanctioned,
attestable computation; this concept only narrates them.

[^fpa-handbook]: FP&A reporting handbook
```

`computations/revenue.md`, BigQuery SQL, human-verified, fresh, and
corroborated by a live dashboard source carrying credibility signals:

```markdown
---
type: Attested Computation
title: Revenue for fiscal year
description: Recognized revenue for a fiscal year, per Finance's definition.
tags: [finance, revenue]
status: stable
runtime: bigquery
parameters:
  - { name: year, type: integer, required: true }
executor:
  resource: references/skills/run-on-bq.md
  receipt: [job_id, executed_sql, result]
attester:
  resource: references/attesters/sql-equality.py
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-28T14:00:00Z }
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
stale_after: 2026-12-31T00:00:00Z
sources:
  - id: rev-policy
    resource: https://wiki.acme/finance/revenue-recognition
    title: Revenue recognition policy
    author: team:finance-fpa
    last_modified: 2026-04-02T00:00:00Z
  - id: exec-rev-dash
    resource: dashboards/exec-revenue
    title: Executive revenue dashboard
    author: team:finance-fpa
    usage_count: 5000
    last_modified: 2026-06-18T00:00:00Z
usage_window: { from: 2026-06-01T00:00:00Z, to: 2026-06-30T00:00:00Z }
---

# Computation

    SELECT SUM(amount) AS revenue
    FROM finance.recognized_revenue
    WHERE fiscal_year = @year

Recognized revenue per the recognition policy,[^rev-policy] corroborated by
the executive revenue dashboard.[^exec-rev-dash]

[^rev-policy]: Revenue recognition policy
[^exec-rev-dash]: Executive revenue dashboard
```

`computations/profit.md`, a dbt model, process-verified, and past its
`stale_after`:

```markdown
---
type: Attested Computation
title: Gross profit for fiscal year
description: Gross profit by segment for a fiscal year, per the cost-allocation standard.
tags: [finance, profit]
status: stable
runtime: dbt
parameters:
  - { name: year, type: integer, required: true }
  - { name: segment, type: string, required: true }
executor:
  resource: references/skills/run-dbt.md
  receipt: [run_id, compiled_sql, result]
attester:
  resource: references/attesters/dbt-binding.py
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-14T14:00:00Z }
verified: { by: process:finance-nightly, at: 2026-06-12T08:00:00Z }
stale_after: 2026-06-15T00:00:00Z
sources:
  - id: cost-alloc
    resource: https://wiki.acme/finance/cost-allocation
    title: Cost allocation standard
---

# Computation

    SELECT gross_profit
    FROM {{ ref('fct_income_statement') }}
    WHERE fiscal_year = {{ var('year') }}
      AND segment = {{ var('segment') }}

Gross profit by segment per the cost-allocation standard.[^cost-alloc]

[^cost-alloc]: Cost allocation standard
```

#!/usr/bin/env bash
# OKF Bundle Validator v0.2
# Usage: validate.sh <bundle-path>
# Checks conformance with OKF v0.2 spec:
#   E1: All non-reserved .md files have YAML frontmatter
#   E2: All frontmatter has non-empty 'type' field
#   E3: Reserved files follow structure rules
#   E4: Attested Computation concepts have required 'runtime' field
#
# Also reports v0.2 features: trust fields, lifecycle, provenance, staleness

set -euo pipefail

BUNDLE="${1:-.}"
ERRORS=0
WARNINGS=0
TOTAL=0
CONCEPTS=0
ATTESTED_COMPUTATIONS=0
WITH_GENERATED=0
WITH_VERIFIED=0
HUMAN_VERIFIED=0
MACHINE_VERIFIED=0
WITH_SOURCES=0
WITH_STATUS=0
STALE_COUNT=0
DEPRECATED_COUNT=0
DRAFT_COUNT=0

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[0;33m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
NC='\033[0m'

if [ ! -d "$BUNDLE" ]; then
  echo -e "${RED}Error: '$BUNDLE' is not a directory${NC}"
  exit 1
fi

echo "Validating OKF bundle: $BUNDLE"
echo "Spec version: v0.2"
echo "---"

# Get current timestamp for staleness check
NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)

# Find all .md files
while IFS= read -r -d '' file; do
  TOTAL=$((TOTAL + 1))
  relative="${file#$BUNDLE/}"
  basename=$(basename "$file")

  # Skip reserved files (validate separately)
  if [[ "$basename" == "index.md" || "$basename" == "log.md" ]]; then
    # E3: Check reserved file structure
    if [[ "$basename" == "index.md" ]]; then
      # index.md should NOT have frontmatter (except bundle root may have okf_version)
      if head -1 "$file" | grep -q "^---$"; then
        # Allow only if it's bundle root and contains okf_version
        if [[ "$relative" != "index.md" ]]; then
          echo -e "${RED}E3: $relative — index.md should not have frontmatter${NC}"
          ERRORS=$((ERRORS + 1))
        fi
      fi
    fi
    if [[ "$basename" == "log.md" ]]; then
      # log.md should have date headings in YYYY-MM-DD format
      if ! grep -qE "^## [0-9]{4}-[0-9]{2}-[0-9]{2}" "$file" 2>/dev/null; then
        if [ -s "$file" ]; then
          echo -e "${YELLOW}W5: $relative — log.md has no ISO 8601 date headings${NC}"
          WARNINGS=$((WARNINGS + 1))
        fi
      fi
    fi
    continue
  fi

  CONCEPTS=$((CONCEPTS + 1))

  # E1: Check for YAML frontmatter
  if ! head -1 "$file" | grep -q "^---$"; then
    echo -e "${RED}E1: $relative — no YAML frontmatter${NC}"
    ERRORS=$((ERRORS + 1))
    continue
  fi

  # Extract frontmatter (between first --- and second ---)
  frontmatter=$(sed -n '2,/^---$/p' "$file" | sed '$d')

  # E2: Check for non-empty type field
  # `|| true` is required: under `set -euo pipefail` a non-matching grep would
  # abort the whole script instead of letting the emptiness check below report E2.
  type_value=$(echo "$frontmatter" | grep -E "^type:" | sed 's/^type:\s*//' | tr -d '"' | tr -d "'" | xargs) || true
  if [ -z "$type_value" ]; then
    echo -e "${RED}E2: $relative — missing or empty 'type' field${NC}"
    ERRORS=$((ERRORS + 1))
    continue
  fi

  # E4: Attested Computation must have runtime
  if [[ "$type_value" == "Attested Computation" ]]; then
    ATTESTED_COMPUTATIONS=$((ATTESTED_COMPUTATIONS + 1))
    if ! echo "$frontmatter" | grep -qE "^runtime:"; then
      echo -e "${RED}E4: $relative — Attested Computation missing required 'runtime' field${NC}"
      ERRORS=$((ERRORS + 1))
    fi
  fi

  # Warnings for recommended fields
  if ! echo "$frontmatter" | grep -qE "^title:"; then
    echo -e "${YELLOW}W1: $relative — missing recommended 'title' field${NC}"
    WARNINGS=$((WARNINGS + 1))
  fi
  if ! echo "$frontmatter" | grep -qE "^description:"; then
    echo -e "${YELLOW}W1: $relative — missing recommended 'description' field${NC}"
    WARNINGS=$((WARNINGS + 1))
  fi

  # v0.2 Trust fields check
  if echo "$frontmatter" | grep -qE "^generated:"; then
    WITH_GENERATED=$((WITH_GENERATED + 1))
  else
    # Check for legacy timestamp field
    if echo "$frontmatter" | grep -qE "^timestamp:"; then
      echo -e "${YELLOW}W3: $relative — using legacy 'timestamp' field, consider migrating to 'generated'${NC}"
      WARNINGS=$((WARNINGS + 1))
    fi
  fi

  if echo "$frontmatter" | grep -qE "^verified:"; then
    WITH_VERIFIED=$((WITH_VERIFIED + 1))
    # Check if human-verified
    if echo "$frontmatter" | grep -qE "human:"; then
      HUMAN_VERIFIED=$((HUMAN_VERIFIED + 1))
    else
      MACHINE_VERIFIED=$((MACHINE_VERIFIED + 1))
    fi
  fi

  # v0.2 Provenance check
  if echo "$frontmatter" | grep -qE "^sources:"; then
    WITH_SOURCES=$((WITH_SOURCES + 1))
    # Check that each sources entry has a resource field.
    # The block runs from under `sources:` to the next top-level key, or to the
    # end of the frontmatter when `sources:` is the last key.
    sources_block=$(echo "$frontmatter" | awk '
      /^sources:/ { inblock = 1; next }
      inblock && /^[^[:space:]]/ { inblock = 0 }
      inblock')
    missing=$(echo "$sources_block" | awk '
      /^[[:space:]]*-[[:space:]]/ { if (started && !has) bad++; started = 1; has = 0 }
      /^[[:space:]]*(-[[:space:]]*)?resource:/ { if (started) has = 1 }
      END { if (started && !has) bad++; print bad + 0 }')
    if [ "$missing" -gt 0 ]; then
      echo -e "${YELLOW}W6: $relative — $missing sources entry/entries missing 'resource' field${NC}"
      WARNINGS=$((WARNINGS + 1))
    fi
  fi

  # v0.2 Lifecycle check
  if echo "$frontmatter" | grep -qE "^status:"; then
    WITH_STATUS=$((WITH_STATUS + 1))
    status_value=$(echo "$frontmatter" | grep -E "^status:" | sed 's/^status:\s*//' | tr -d '"' | tr -d "'" | xargs)
    case "$status_value" in
      draft)
        DRAFT_COUNT=$((DRAFT_COUNT + 1))
        ;;
      deprecated)
        DEPRECATED_COUNT=$((DEPRECATED_COUNT + 1))
        ;;
      stable)
        # Default, nothing special
        ;;
      *)
        echo -e "${YELLOW}W: $relative — unknown status value '$status_value' (expected: draft|stable|deprecated)${NC}"
        WARNINGS=$((WARNINGS + 1))
        ;;
    esac
  fi

  # v0.2 Staleness check
  if echo "$frontmatter" | grep -qE "^stale_after:"; then
    stale_date=$(echo "$frontmatter" | grep -E "^stale_after:" | sed 's/^stale_after:\s*//' | tr -d '"' | tr -d "'" | xargs)
    # Simple string comparison works for ISO 8601 dates
    if [[ "$NOW" > "$stale_date" ]] || [[ "$NOW" == "$stale_date" ]]; then
      STALE_COUNT=$((STALE_COUNT + 1))
      echo -e "${YELLOW}W7: $relative — content is STALE (stale_after: $stale_date)${NC}"
      WARNINGS=$((WARNINGS + 1))
    fi
  fi

done < <(find "$BUNDLE" -name "*.md" -type f -print0 | sort -z)

# Summary
echo ""
echo "---"
echo -e "${CYAN}Summary${NC}"
echo "Files scanned: $TOTAL"
echo "Concept files: $CONCEPTS"
echo ""

if [ $ERRORS -eq 0 ]; then
  echo -e "${GREEN}✅ Bundle is OKF v0.2 conformant${NC}"
else
  echo -e "${RED}❌ $ERRORS error(s) — bundle is NOT conformant${NC}"
fi

if [ $WARNINGS -gt 0 ]; then
  echo -e "${YELLOW}⚠  $WARNINGS warning(s)${NC}"
fi

echo ""
echo -e "${CYAN}v0.2 Features${NC}"

# Trust summary
echo ""
echo "Trust:"
if [ $WITH_GENERATED -gt 0 ]; then
  echo -e "  ${BLUE}ℹ${NC}  $WITH_GENERATED concepts with 'generated' field"
fi
if [ $WITH_VERIFIED -gt 0 ]; then
  echo -e "  ${BLUE}ℹ${NC}  $WITH_VERIFIED concepts with 'verified' field"
  if [ $HUMAN_VERIFIED -gt 0 ]; then
    echo -e "      ${GREEN}✓${NC} $HUMAN_VERIFIED human-reviewed"
  fi
  if [ $MACHINE_VERIFIED -gt 0 ]; then
    echo -e "      ${BLUE}○${NC} $MACHINE_VERIFIED machine-confirmed only"
  fi
fi
UNVERIFIED=$((CONCEPTS - WITH_VERIFIED))
if [ $UNVERIFIED -gt 0 ]; then
  echo -e "      ${YELLOW}○${NC} $UNVERIFIED unverified"
fi

# Provenance summary
echo ""
echo "Provenance:"
if [ $WITH_SOURCES -gt 0 ]; then
  echo -e "  ${BLUE}ℹ${NC}  $WITH_SOURCES concepts with 'sources' field"
else
  echo -e "  ${YELLOW}○${NC} No concepts with provenance tracking"
fi

# Lifecycle summary
echo ""
echo "Lifecycle:"
if [ $WITH_STATUS -gt 0 ]; then
  echo -e "  ${BLUE}ℹ${NC}  $WITH_STATUS concepts with explicit 'status'"
fi
if [ $DRAFT_COUNT -gt 0 ]; then
  echo -e "      ${YELLOW}○${NC} $DRAFT_COUNT draft"
fi
if [ $DEPRECATED_COUNT -gt 0 ]; then
  echo -e "      ${YELLOW}○${NC} $DEPRECATED_COUNT deprecated"
fi
if [ $STALE_COUNT -gt 0 ]; then
  echo -e "  ${RED}⚠${NC}  $STALE_COUNT concepts are STALE (past stale_after)"
fi

# Attested Computations
if [ $ATTESTED_COMPUTATIONS -gt 0 ]; then
  echo ""
  echo "Attested Computations:"
  echo -e "  ${BLUE}ℹ${NC}  $ATTESTED_COMPUTATIONS Attested Computation concept(s)"
fi

echo ""
exit $ERRORS