OKF: consume a bundle without blowing your context window

The Stack

Tested Against

Prerequisites

• An OKF bundle to consume
• A consumer/agent you can tell to read the index first

Steps

1. 1

   Add indexes and a log, then check the reserved-file rules

   Give the bundle root an index.md (optionally carrying okf_version), each directory its own index.md with no frontmatter, and a log.md with newest-first ISO 8601 date headings. Tell your consumer to read the index first, follow links, and pull concepts on demand. CI checks the reserved files follow §6/§7/§11.

   mkdir -p bundle/tables
   cat > bundle/index.md <<'MD'
   ---
   okf_version: "0.1"
   ---
   
   # Tables
   * [Orders](tables/orders.md) - One row per completed customer order.
   MD
   cat > bundle/tables/index.md <<'MD'
   # Tables
   * [Orders](orders.md) - One row per completed customer order.
   MD
   cat > bundle/log.md <<'MD'
   ## 2026-05-28
   - Added the orders table concept.
   
   ## 2026-04-12
   - Initial bundle.
   MD
   cat > bundle/tables/orders.md <<'MD'
   ---
   type: BigQuery Table
   title: Orders
   ---
   
   # Schema
   One row per completed order.
   MD
   ruby -ryaml -e '
   require "date"
   errors = []
   Dir.glob("bundle/**/index.md").sort.each do |path|
     lines = File.read(path).lines
     has_fm = !lines.empty? && lines.first.strip == "---"
     if path == "bundle/index.md"
       if has_fm
         rest = lines[1..]
         idx = rest.index { |l| l.strip == "---" }
         fm = (begin; YAML.safe_load(rest[0...idx].join, permitted_classes: [Date, Time]); rescue; {}; end)
         errors << "root index.md frontmatter must carry okf_version" unless fm.is_a?(Hash) && fm["okf_version"]
       end
     else
       errors << (path + ": non-root index.md must not carry frontmatter") if has_fm
     end
   end
   Dir.glob("bundle/**/log.md").sort.each do |path|
     File.read(path).lines.each do |l|
       s = l.strip
       next unless s.start_with?("#")
       token = s.delete("#").strip
       begin
         Date.strptime(token, "%Y-%m-%d")
       rescue ArgumentError
         errors << (path + ": heading is not ISO 8601 YYYY-MM-DD: " + token)
       end
     end
   end
   if errors.empty?
     puts "OKF reserved files OK: root index.md carries okf_version, sub-index has no frontmatter, log.md uses ISO 8601 dates"
   else
     puts "NONCONFORMANT: " + errors.join("; "); exit 1
   end
   '

2. 2

   Wire the consumer to navigate, not swallow (the model step, not checked by CI)

   Tell your agent to read the index first, follow links, and pull individual concepts on demand, rather than globbing every .md into the prompt. For a human view, the reference HTML visualizer renders any bundle as an interactive graph in one self-contained file. The navigation is fenced.