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/phases/phase-fixedupdate.md

@@ -0,0 +1,40 @@
+---
+id: phase-fixedupdate
+name: FixedUpdate
+category: phases
+kind: phase
+tokens: FixedUpdate
+sig: phase FixedUpdate
+tip: The deterministic simulation step — physics and gameplay meant to be reproducible.
+order: 2
+---
+
+`FixedUpdate` runs each frame after `Input` and before `Update`. It is the home for the <b>deterministic core of the simulation</b> — movement, collisions, physics — the logic you want to produce the identical result given the same inputs and RNG seed. The runtime groups `Input`, `FixedUpdate`, `Update`, and `LateUpdate` into the "sim" step (exposed together for replay, rollback, and headless tests), while `Render` is kept separate so drawing never affects the outcome. Put anything that must stay reproducible here and mark the handler `@deterministic`; put frame-dressing and non-critical logic in `Update` instead.
+
+```ludic
+program FixedUpdateExample {
+  property Position { column: int = 0, row: int = 0 }
+  property Velocity { delta_x: int = 0, delta_y: int = 0 }
+  model Projectile { Position, Velocity }
+
+  handler SpawnShot phase Start {
+    spawn Projectile { Position { column: 0, row: 8 };  Velocity { delta_x: 1, delta_y: 0 } }
+  }
+
+  @deterministic
+  handler AdvancePositions phase FixedUpdate {
+    for (current_position, current_velocity) in query [Position, Velocity] {
+      current_position.column = current_position.column + current_velocity.delta_x
+      current_position.row = current_position.row + current_velocity.delta_y
+    }
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    for (current_position) in query [Position, {Projectile}] {
+      Screen.fill_rectangle(x: current_position.column * 16, y: current_position.row * 16, width: 16, height: 16, color: Color.Crimson)
+    }
+    Screen.show()
+  }
+}
+```

docs/language/phases/phase-input.md

@@ -0,0 +1,34 @@
+---
+id: phase-input
+name: Input
+category: phases
+kind: phase
+tokens: Input
+sig: phase Input
+tip: The first per-frame phase — read the keyboard and record the player's intent.
+order: 1
+---
+
+`Input` is the first phase of every frame. The runtime polls the keyboard just before it runs, so a `handler … phase Input` reads the current key with `Input.key()` and turns it into intent — a chosen direction, a menu selection, a pause toggle — usually by writing a program `var` that later phases act on. Keep it to <b>reading input and recording decisions</b>: do the actual movement and simulation in `FixedUpdate`/`Update`, and the drawing in `Render`. Because it runs before `FixedUpdate`, `Update`, `LateUpdate`, and `Render`, the intent it records is visible to every phase in the same frame.
+
+```ludic
+program InputExample {
+  const DIRECTION_LEFT: int = 0
+  const DIRECTION_RIGHT: int = 1
+  var facing: int = DIRECTION_RIGHT
+
+  handler ReadControls phase Input {
+    let pressed_key = Input.key()
+    if pressed_key == 'a' { facing = DIRECTION_LEFT }
+    if pressed_key == 'd' { facing = DIRECTION_RIGHT }
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    var marker_x = 40
+    if facing == DIRECTION_RIGHT { marker_x = 200 }
+    Screen.fill_rectangle(x: marker_x, y: 100, width: 16, height: 16, color: Color.LimeGreen)
+    Screen.show()
+  }
+}
+```

docs/language/phases/phase-lateupdate.md

@@ -0,0 +1,36 @@
+---
+id: phase-lateupdate
+name: LateUpdate
+category: phases
+kind: phase
+tokens: LateUpdate
+sig: phase LateUpdate
+tip: Runs each frame after Update and before Render.
+order: 4
+---
+
+<code>LateUpdate</code> runs once per frame, after every <code>Update</code> handler has finished and just before <code>Render</code>. Use it for logic that must observe the <b>settled</b> result of this frame's updates: following the camera to the player's new position, resolving queued despawns, or any end-of-step cleanup that would be wrong to do while other <code>Update</code> handlers are still moving models. The full per-frame order the engine runs is <code>Input</code> → <code>FixedUpdate</code> → <code>Update</code> → <code>LateUpdate</code> → <code>Render</code>, with <code>Start</code> running once at boot before any of them.
+
+```ludic
+program FollowCamera {
+  property Position { column: int = 0, row: int = 0 }
+  model Player { Position }
+
+  var camera_column: int = 0
+
+  handler SpawnPlayer phase Start {
+    spawn Player { Position { column: 12, row: 0 } }
+  }
+
+  @Queries(these: [Position])
+  handler MovePlayer phase Update {
+    Position.column = Position.column + 1
+  }
+
+  # runs after MovePlayer, so the camera sees the final position
+  @Queries(these: [Position])
+  handler TrackPlayer phase LateUpdate {
+    camera_column = Position.column
+  }
+}
+```

docs/language/phases/phase-render.md

@@ -0,0 +1,39 @@
+---
+id: phase-render
+name: Render
+category: phases
+kind: phase
+tokens: Render
+sig: phase Render
+tip: The last per-frame phase — draw the world, then call Screen.show() once.
+order: 5
+---
+
+`Render` is the final phase of every frame, run after all the logic phases (`Input`, `FixedUpdate`, `Update`, `LateUpdate`) have finished. A `handler … phase Render` paints the frame with the `Screen.*` calls — start by clearing the surface with `Screen.clear`, draw everything back-to-front, and finish with a single `Screen.show()` to present the completed frame to the window. Keep `Render` free of game-state changes: it should read the world and draw it, not move things, so that the drawing never affects the simulation. When you use scenes, layers within a scene render in declaration order, so a HUD layer written after a world layer paints on top of it.
+
+```ludic
+program RenderExample {
+  property Position { column: int = 0, row: int = 0 }
+  model Player { Position }
+
+  const TILE_SIZE: int = 16
+  var score: int = 0
+
+  handler PlacePlayer phase Start {
+    spawn Player { Position { column: 5, row: 6 } }
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    for (current_position) in query [Position, {Player}] {
+      Screen.fill_rectangle(
+        x: current_position.column * TILE_SIZE,
+        y: current_position.row * TILE_SIZE,
+        width: TILE_SIZE, height: TILE_SIZE, color: Color.LimeGreen)
+    }
+    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()
+  }
+}
+```

docs/language/phases/phase-start.md

@@ -0,0 +1,35 @@
+---
+id: phase-start
+name: Start
+category: phases
+kind: phase
+tokens: Start
+sig: phase Start
+tip: Runs once at boot, before the game loop — the place to set up initial state.
+order: 0
+---
+
+`Start` is the boot phase: a `handler … phase Start` runs <b>exactly once</b>, before the first frame and before the per-frame loop begins. Use it to build the world that everything else assumes — seed the RNG with `Random.seed`, set the tilemap size with `Map.size`, spawn the starting models, and initialise your program `var`s. It runs before any scene is entered, so it is the one phase a scene `layer` handler may <b>not</b> use; per-scene setup belongs in a scene's `on enter` block instead. Every other phase (`Input`, `FixedUpdate`, `Update`, `LateUpdate`, `Render`) then repeats each frame, but `Start` never runs again.
+
+```ludic
+program StartExample {
+  property Position { column: int = 0, row: int = 0 }
+  model Player { Position }
+
+  const GRID_WIDTH: int = 20
+  var score: int = 0
+
+  handler SetUpWorld phase Start {
+    Random.seed(value: 1)
+    Map.size(width: GRID_WIDTH, height: 15)
+    score = 0
+    spawn Player { Position { column: 10, row: 7 } }
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    Screen.draw_number(x: 4, y: 4, value: score, color: Color.Gold, scale: 1)
+    Screen.show()
+  }
+}
+```

docs/language/phases/phase-update.md

@@ -0,0 +1,41 @@
+---
+id: phase-update
+name: Update
+category: phases
+kind: phase
+tokens: Update
+sig: phase Update
+tip: The ordinary per-frame game-logic step, run after Input and FixedUpdate.
+order: 3
+---
+
+`Update` is the everyday game-logic phase, run each frame after `Input` and `FixedUpdate` and before `LateUpdate` and `Render`. It is where most gameplay lives when you are not being strict about determinism: spawn waves on a timer, apply the intent that `Input` recorded, check win/lose conditions, advance animations. Reach for `Update` by default and reserve `FixedUpdate` for the simulation you specifically want reproducible. Because it runs after `Input`, the current frame's key press is already reflected in your program `var`s by the time `Update` reads them.
+
+```ludic
+program UpdateExample {
+  property Position { column: int = 0, row: int = 0 }
+  model Enemy { Position }
+
+  const GRID_WIDTH: int = 20
+  var elapsed_frames: int = 0
+  var score: int = 0
+
+  handler SpawnWave phase Update {
+    elapsed_frames = elapsed_frames + 1
+    if elapsed_frames % 30 == 0 {
+      let spawn_column = Random.range(low: 0, high: GRID_WIDTH - 1)
+      spawn Enemy { Position { column: spawn_column, row: 0 } }
+      score = score + 1
+    }
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    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.Crimson)
+    }
+    Screen.draw_number(x: 4, y: 4, value: score, color: Color.Gold, scale: 1)
+    Screen.show()
+  }
+}
+```