Wanderland

Things That Are Silly as Fuck

Wanderland landmines. Stuff that quietly breaks because two systems disagree on a convention.


H1 heading slug must match the node slug

The fence indexer (fence_index_builder._extract_fences_for_backend) only strips the file's H1 wrapper from section_path when the H1's slug equals the node slug. The runtime resolver (graph_api_ast._resolve_fence_in_graph) always strips the single level-1 H1 child. When the two disagree, every code-fence on that node 404s on /execute and /source while metadata GETs still work — confusing as hell because the fence is clearly indexed.

Symptom: oculus_execute_fence({fence_id: "..."}) returns 401/404 PathNotFound on a fence that oculus_get_fence finds fine.

Root cause example: node required-reading.md had H1 # Required Reading Lists (slug required-reading-lists). The names diverged, the index stored section_path = "required-reading-lists.tools.get-reading-lists", the resolver expected "tools.get-reading-lists", and execution 404'd.

Fix: rename the H1 to match the slug (cheap, file-only) or drop the slug-match guard in the indexer so it always strips the single H1 (correct, structural).

Also note: if a fence body uses peek("slug", "old-h1.section.yaml"), the H1-rename invalidates that path too. Walk the file for stale <old-h1>. prefixes after renaming.