Learning Node & Graph System

[plyfofun]

Link Learning Paths and Learning Nodes so they stay in sync

Background

The Learn system currently has two separate layers:

• Learning Paths — the graph layer. Each path's structure lives in path.json:
  the list of nodes (id, title, type, and hand-placed x/y coordinates)
  and the edges (from → to) that wire up prerequisites. learn-path.js
  renders this as the interactive SVG graph.
• Learning Nodes — the content layer. Each node's actual lesson/challenge
  content is a separate markdown file at {base}/{nodeId}/node.md (with YAML
  front matter). learn-node.js fetches and renders it.

The problem

Right now these two layers are maintained by hand and a node effectively exists
in two places at once:

• Its identity and metadata (id, title, type) are declared in path.json.
• Its content lives in {nodeId}/node.md.

That means adding, renaming, retyping, or removing a node requires editing both
the graph definition and the content file, and keeping them consistent
manually. They can drift: a node can be listed in the graph with no content file,
or a content file can exist with no node on the graph. Titles/types can disagree
between path.json and the node's front matter.

What I want

A single source of truth that links the two layers so that editing the content
(Learning Nodes) automatically updates the graph (Learning Paths), and vice
versa — no double-bookkeeping. Concretely, the goal is to be able to author a
node once and have it appear, with the correct title, type, and prerequisites,
on the path graph without separately hand-editing path.json.

Possible directions

• Move node metadata (title, type, prerequisites/edges) into each node's
  node.md front matter and derive path.json from the collection of nodes,
  so the content files are the source of truth.
• Or keep path.json as the source of truth for structure/layout and have it
  reference content files, with validation that every node has a matching
  node.md (and every node.md has a node).
• Either way, add a check (build step or runtime warning) that flags drift:
  nodes without content, content without nodes, or mismatched title/type.
• Decide what stays manual vs. generated — e.g. graph layout (x/y) may
  still need hand-placement or auto-layout even if everything else is derived.

Other questions

• Should the graph layout (x/y coordinates) be auto-generated or stay
  hand-authored?
• Where should edges/prerequisites be defined — in the graph or in each node?
• Is this a build-time generation step, or resolved dynamically in the browser
  at load time?

Goal

• A node can be added/edited/removed in one place and both the graph and the
  content view reflect it.
• No field (title, type, prerequisites) has to be kept in sync by hand across
  two files.
• Drift between graph and content is impossible or surfaced as an explicit error.