docs(api): per-symbol pages, fuzzy search, deep token linking, hover cards

Rebuild the API Reference around one page per symbol and richer, verified content.

Pages & navigation
- One HTML page per symbol (kw-*, type-*, phase-*, screen-*, fn-*, annot-*, op-*)
  instead of a single scrolling page; namespace overview pages (ns-screen …
  ns-color) and a searchable index (api.html) with client-side fuzzy search.
- Sticky-header scroll offset (scroll-margin) so a jumped-to entry/param/color is
  never hidden, plus a flash highlight on the scrolled-to target.

Deep linking in every snippet & example
- Namespace members split: `Screen`→namespace page, `fill_rectangle`→method page;
  `Color`→palette page, `Charcoal`→its swatch — separately.
- Named arguments (`width:`) link to that parameter's anchor on the method page.
- Hover any token for a summary card built from the real API data (symbols.json).

Content & coverage
- Full authoritative surface documented from the compiler: every keyword, type,
  the 6 phases (Start/Input/FixedUpdate/Update/LateUpdate/Render, each its own
  page), all 22 annotations, namespace methods with parameter docs, builtins,
  the world_* reflection ABI, networking, operators — 155 symbols.
- Longer, clearer explanations; "model"/"model instance" terminology, not "entity";
  descriptive identifiers in every example (Position{column,row}, Velocity{delta_x,
  delta_y}, Health{current,maximum}, Player/Enemy) — no Pos/Seg/x/dx.
- Accuracy fixes from compiler ground-truth: world_count() takes no arg,
  world_query_next(property, cursor) arg order, event fields bind by name; dropped
  `when` and `module` (not in the self-hosted parser).

Tooling
- inventory.json + check.py: coverage guard (every symbol has a page), duplicate-
  token guard, and broken-link guard — fail CI so docs can't drift.
- validate.py: compiles every ```ludic example against bin/ludicc (158 compile).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/language/scenes/kw-enter.md

@@ -5,8 +5,33 @@ category: scenes
 kind: keyword
 tokens: enter
 sig: on enter { … }
-tip: The scene-entry hook.
+tip: The scene-entry hook — runs once as a scene becomes active.
 order: 3
 ---
 
-The scene-entry hook.
+`enter` names the body of a scene's entry hook, written `on enter { … }`. It runs <b>once</b> each time the scene becomes active — at boot for the `start` scene (right after the `Start` phase), and on every `become Name` that switches into it. This is where a scene builds what it owns: spawn its models, reset its counters, set the tilemap, open a menu. It is a lifecycle hook, not a phase, so it may not contain `phase` handlers; the scene's ongoing behaviour goes in its `layer` handlers instead.
+
+```ludic
+program EnterHookExample {
+  property Position { column: int = 0, row: int = 0 }
+  model Player { Position }
+
+  var score: int = 0
+
+  scene Overworld start {
+    on enter {
+      score = 0
+      spawn Player { Position { column: 5, row: 5 } }
+    }
+    layer World {
+      handler DrawWorld phase Render {
+        Screen.clear(Color.MidnightBlue)
+        for (current_position) in query [Position, {Player}] {
+          Screen.fill_rectangle(x: current_position.column * 16, y: current_position.row * 16, width: 16, height: 16, color: Color.LimeGreen)
+        }
+        Screen.show()
+      }
+    }
+  }
+}
+```

docs/language/scenes/kw-exit.md

@@ -5,8 +5,40 @@ category: scenes
 kind: keyword
 tokens: exit
 sig: on exit { … }
-tip: The scene-exit hook.
+tip: The scene-exit hook — runs once as a scene is left.
 order: 4
 ---
 
-The scene-exit hook.
+`exit` names the body of a scene's exit hook, written `on exit { … }`. It runs <b>once</b> when the scene is left — on a `become Other`, the leaving scene's `on exit` runs first, then the active scene switches and the new scene's `on enter` runs. Use it to tear down what the scene created so it does not leak into the next state: despawn the scene's models, hide a menu, save progress. Like `on enter`, it is a lifecycle hook rather than a phase and holds plain statements, not `phase` handlers.
+
+```ludic
+program ExitHookExample {
+  property Position { column: int = 0, row: int = 0 }
+  model Enemy { Position }
+
+  scene Battle start {
+    on enter { spawn Enemy { Position { column: 8, row: 4 } } }
+    on exit {
+      for (any_position) in query [Position, {Enemy}] { despawn self() }
+    }
+    layer Fight {
+      handler LeaveBattle phase Update {
+        if Input.key() == 'q' { become Overworld }
+      }
+      handler DrawBattle phase Render {
+        Screen.clear(Color.Crimson)
+        Screen.show()
+      }
+    }
+  }
+
+  scene Overworld {
+    layer World {
+      handler DrawWorld phase Render {
+        Screen.clear(Color.MidnightBlue)
+        Screen.show()
+      }
+    }
+  }
+}
+```

docs/language/scenes/kw-layer.md

@@ -5,8 +5,38 @@ category: scenes
 kind: keyword
 tokens: layer
 sig: layer Name { handlers }
-tip: A group of handlers inside a scene; layers render in declaration order.
+tip: A named group of handlers inside a scene; layers render in declaration order.
 order: 1
 ---
 
-A group of handlers inside a scene; layers render in declaration order.
+A `layer` groups handlers inside a scene, and <b>declaration order is draw order</b>: within a phase the active scene's layers run in the order they were written, so a `Hud` layer declared after a `World` layer paints its `Render` output on top. Layers are the natural unit for stacking a heads-up display over the play-field, or a menu over a paused world. A layer handler may use any phase except `Start` (boot-time setup belongs in the scene's `on enter`). Handlers that should run in every scene are declared outside any scene rather than in a layer.
+
+```ludic
+program LayerExample {
+  property Position { column: int = 0, row: int = 0 }
+  model Player { Position }
+
+  var score: int = 0
+
+  scene Overworld start {
+    on enter { spawn Player { Position { column: 6, row: 6 } } }
+
+    layer World {
+      handler DrawWorld phase Render {
+        Screen.clear(Color.MidnightBlue)
+        for (current_position) in query [Position, {Player}] {
+          Screen.fill_rectangle(x: current_position.column * 16, y: current_position.row * 16, width: 16, height: 16, color: Color.LimeGreen)
+        }
+      }
+    }
+
+    layer Hud {
+      handler DrawScore phase Render {
+        Screen.draw_text(x: 6, y: 4, text: "SCORE", color: Color.White, scale: 1)
+        Screen.draw_number(x: 52, y: 4, value: score, color: Color.Gold, scale: 1)
+        Screen.show()                     # the last layer to draw presents the frame
+      }
+    }
+  }
+}
+```

docs/language/scenes/kw-on.md

@@ -5,8 +5,48 @@ category: scenes
 kind: keyword
 tokens: on
 sig: on enter { … }   on exit { … }
-tip: Hooks that fire when a scene becomes active or is left.
+tip: Scene lifecycle hooks that fire as a scene becomes active or is left.
 order: 2
 ---
 
-Hooks that fire when a scene becomes active or is left.
+`on` introduces a scene's lifecycle hooks: `on enter { … }` runs once when the scene becomes active, and `on exit { … }` runs once as it is left. They are hooks, <b>not phases</b> — the place for per-scene setup and teardown that has no equivalent in a mode register. The start scene's `on enter` fires at boot right after the `Start` phase; on a `become Other` the current scene's `on exit` runs, the active scene switches, then the new scene's `on enter` runs. Use `on enter` to spawn the models a scene needs and reset its counters, and `on exit` to tidy up before leaving.
+
+```ludic
+program SceneHookExample {
+  property Position { column: int = 0, row: int = 0 }
+  model Enemy { Position }
+
+  var elapsed_frames: int = 0
+
+  scene Overworld start {
+    layer World {
+      handler EnterBattle phase Update {
+        if Input.key() == 'b' { become Battle }
+      }
+      handler DrawWorld phase Render {
+        Screen.clear(Color.MidnightBlue)
+        Screen.show()
+      }
+    }
+  }
+
+  scene Battle {
+    on enter {
+      elapsed_frames = 0
+      spawn Enemy { Position { column: 8, row: 4 } }
+    }
+    on exit {
+      for (any_position) in query [Position, {Enemy}] { despawn self() }
+    }
+    layer Fight {
+      handler DrawBattle phase Render {
+        Screen.clear(Color.Crimson)
+        for (current_position) in query [Position, {Enemy}] {
+          Screen.fill_rectangle(x: current_position.column * 16, y: current_position.row * 16, width: 16, height: 16, color: Color.White)
+        }
+        Screen.show()
+      }
+    }
+  }
+}
+```

docs/language/scenes/kw-scene.md

@@ -5,12 +5,40 @@ category: scenes
 kind: keyword
 tokens: scene
 sig: scene Name [start] { on enter{} on exit{} layer … }
-tip: A mutually-exclusive game state.
+tip: A mutually-exclusive game state — a title screen, the overworld, a battle.
 order: 0
 ---
 
-A mutually-exclusive game state. Mark one <code>start</code>.
+A `scene` is one of the mutually-exclusive states a game moves between — a title screen, the overworld, a battle, a shop. Exactly <b>one scene is active</b> at a time, and only the active scene's `layer` handlers run each phase; handlers declared outside any scene are global and run every frame regardless. A scene may carry an `on enter` / `on exit` pair of lifecycle hooks and one or more `layer` blocks that group its handlers. Under the hood a scene lowers to an implicit state machine the compiler writes for you (scenes number themselves by declaration order), so `become` from one scene to another costs two direct calls and a register store — no dispatch table.
 
 ```ludic
-scene Title start { on enter { … } layer Main { … } }
+program SceneExample {
+  var elapsed_frames: int = 0
+
+  scene Title start {
+    on enter { elapsed_frames = 0 }
+    layer Main {
+      handler WaitForStart phase Update {
+        elapsed_frames = elapsed_frames + 1
+        if Input.key() != 0 { become Overworld }
+      }
+      handler DrawTitle phase Render {
+        Screen.clear(Color.MidnightBlue)
+        Screen.draw_text(x: 60, y: 100, text: "PRESS ANY KEY", color: Color.White, scale: 1)
+        Screen.show()
+      }
+    }
+  }
+
+  scene Overworld {
+    on enter { elapsed_frames = 0 }
+    layer World {
+      handler DrawWorld phase Render {
+        Screen.clear(Color.MidnightBlue)
+        Screen.fill_rectangle(x: 80, y: 80, width: 16, height: 16, color: Color.LimeGreen)
+        Screen.show()
+      }
+    }
+  }
+}
 ```

docs/language/scenes/kw-start.md

@@ -0,0 +1,40 @@
+---
+id: kw-start
+name: start
+category: scenes
+kind: keyword
+tokens: start
+sig: scene Name start { … }
+tip: Marks the one scene the game begins in.
+order: 50
+---
+
+`start` marks the scene the game begins in. Written right after the scene's name (`scene Title start { … }`), it tells the compiler which scene becomes active at boot: its `on enter` hook fires once, immediately after the `Start` phase, and its layers begin dispatching on the first frame. Mark <b>exactly one</b> scene `start`; if no scene is marked, the first one declared is used. Every other scene is reached later with `become`.
+
+```ludic
+program StartSceneExample {
+  scene MainMenu start {
+    on enter { Screen.status("main menu") }
+    layer Menu {
+      handler ChooseOption phase Update {
+        if Input.key() == 'p' { become Overworld }
+      }
+      handler DrawMenu phase Render {
+        Screen.clear(Color.MidnightBlue)
+        Screen.draw_text(x: 40, y: 90, text: "PRESS P TO PLAY", color: Color.White, scale: 1)
+        Screen.show()
+      }
+    }
+  }
+
+  scene Overworld {
+    layer World {
+      handler DrawWorld phase Render {
+        Screen.clear(Color.MidnightBlue)
+        Screen.fill_rectangle(x: 100, y: 100, width: 16, height: 16, color: Color.Gold)
+        Screen.show()
+      }
+    }
+  }
+}
+```