Link Search Menu Expand Document
Bodhi Map

Configuration Reference

okf.config.js is the single source of truth for everything that is not a concept — the controlled vocabulary (clusters, levels, relations), the release marker, and the interactive flows (decision wizard, guided path, comparison tables). The build inlines it into js/data.js, so after any change run npm run build.

It’s a UMD module that works in both Node (the build) and the browser. All exports are returned at the bottom: { CLUSTERS, CLUSTER_TYPE, LEVELS, RELATIONS, RELEASE, DECISION_TREE, GUIDED_PATH, COMPARISONS }.

CLUSTERS

The themed groups nodes belong to. Each has a label and a color (used for the node fill and cluster box).

const CLUSTERS = {
  foundations:  { label: 'Foundations',            color: '#3b82f6' },
  architecture: { label: 'Architecture',           color: '#8b5cf6' },
  // …
};

Add a cluster:

  1. Add an entry here (id → { label, color }).
  2. Add a matching CLUSTER_TYPE[id] (the OKF type its concepts use).
  3. Create knowledge/<id>/ and add concept files with cluster: <id>.
  4. Optionally add the cluster to a learning-phase group in js/graph.js (CLUSTER_GROUPS) so it appears in the legend dock — otherwise it still renders but won’t be grouped.
  5. npm run build.

CLUSTER_TYPE

Maps each cluster id to the OKF type value its concepts declare in frontmatter (e.g. peft → 'PEFT Method'). Every cluster needs one (the validator warns otherwise).

LEVELS

The 1–5 learning-depth scale used by the level filter. Names are display-only.

const LEVELS = { 1:'Foundations', 2:'Core Mechanics', 3:'Adaptation Basics',
                 4:'Fine-Tuning Techniques', 5:'Advanced / Alignment' };

RELATIONS

The typed edge vocabulary — each verb’s label, color, and line style in the graph.

const RELATIONS = {
  'is-a':        { label: 'is a type of',   color: '#64748b', style: 'solid'  },
  'improves-on': { label: 'improves on',    color: '#10b981', style: 'solid'  },
  // … 'alternative', 'requires', 'combines', 'builds-on'
  'path':        { label: 'example step',   color: '#fbbf24', style: 'solid'  }, // internal: guided-path edges
};

path is reserved for guided-path edges (derived from GUIDED_PATH, not authored on concepts). To add a new authorable verb, add an entry here, then you can use it in concept relations.

RELEASE

The current version marker that powers the “what’s new” highlight.

const RELEASE = { version: '0.4.0', label: 'v0.4.0' };

Concepts whose frontmatter added: equals RELEASE.version are surfaced as new (green ring + New filter chip). On each release, bump this and tag the new concepts — see Release Process.

DECISION_TREE (the “Which technique?” wizard)

A small state machine: start names the first step; steps maps step ids to a question q and an array of answers a. Each answer either recommends a concept (rec: '<id>', with a why) or advances to the next step (next: '<stepId>'). An answer may also chain a follow-up after a recommendation via then: '<stepId>'.

const DECISION_TREE = {
  start: 'knowledge',
  steps: {
    knowledge: { q: '…', a: [
      { label: 'Yes — needs fresh facts', rec: 'rag', why: '…' },
      { label: 'No — needs new behavior',  next: 'data' },
    ]},
    // …
  },
};

rec ids must be real concept ids (the validator checks this).

GUIDED_PATH (the “▶ Guided Path” walkthrough)

An ordered list of concept ids with a note each. The build derives path edges between consecutive steps automatically.

const GUIDED_PATH = {
  title: 'Worked example: base model → production support assistant',
  steps: [
    { id: 'decoder-gpt',  note: 'Start from a pretrained decoder-only base.' },
    { id: 'sft',          note: 'Supervised fine-tune on demonstrations.' },
    // …
  ],
};

Every id must be a real concept (validator-checked).

COMPARISONS (the “Compare” tables)

An array of comparison matrices. Each has an id, title, blurb, a list of dimensions (the columns: { key, label }), and rows keyed by concept id plus a value per dimension key.

{
  id: 'peft',
  title: 'PEFT methods',
  blurb: '…',
  dimensions: [ { key: 'params', label: 'Trainable params' }, /* … */ ],
  rows: [
    { id: 'lora', params: '~0.1–1%', /* …one value per dimension key… */ },
  ],
}

Each row’s id must be a real concept (clicking the row jumps to it). The validator warns if a row is missing a dimension value.

After editing okf.config.js, always run npm run build and confirm npm run validate reports 0 errors. See Architecture for how this file flows into the runtime.