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/random/random-chance.md

@@ -5,8 +5,48 @@ category: random
 kind: namespace-method
 tokens: Random.chance
 sig: Random.chance(percent) -> bool
-tip: True with the given percent probability.
+tip: Return true with the given percent probability.
 order: 1
+ns: Random
+member: chance
 ---
 
-True with the given percent probability.
+Returns <code>true</code> roughly <code>percent</code> times out of a hundred, and <code>false</code> otherwise — a convenient shorthand for "this happens X% of the time". Use it to gate random events such as spawning an enemy on a given frame, dropping loot, or triggering a rare animation. Passing <code>0</code> never fires and <code>100</code> always fires. Like the rest of the <code>Random</code> namespace it is driven by the seeded generator, so seed it with <code>Random.seed</code> for reproducible behavior.
+
+Parameters:
+- `percent` — the probability of returning `true`, from `0` to `100`
+
+```ludic
+program SpawnWave {
+  property Position { column: int = 0, row: int = 0 }
+  model Enemy { Position }
+
+  const GRID_WIDTH: int = 20
+  const TILE_SIZE: int = 16
+
+  handler SeedRandom phase Start {
+    Random.seed(value: 3)
+  }
+
+  handler MaybeSpawn phase Update {
+    if Random.chance(percent: 10) {
+      spawn Enemy {
+        Position { column: Random.range(low: 0, high: GRID_WIDTH - 1), row: 0 }
+      }
+    }
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    for (Position) in query [Position, {Enemy}] {
+      Screen.fill_rectangle(
+        x: Position.column * TILE_SIZE,
+        y: Position.row * TILE_SIZE,
+        width: TILE_SIZE,
+        height: TILE_SIZE,
+        color: Color.Crimson)
+    }
+    Screen.show()
+  }
+}
+```

docs/language/random/random-range.md

@@ -7,10 +7,48 @@ tokens: Random.range
 sig: Random.range(low, high) -> int
 tip: A random integer in the inclusive range [low, high].
 order: 0
+ns: Random
+member: range
 ---
 
-A random integer in the inclusive range [low, high].
+Returns a random integer between <code>low</code> and <code>high</code>, inclusive of both ends — so <code>Random.range(low: 0, high: 3)</code> can return <code>0</code>, <code>1</code>, <code>2</code>, or <code>3</code>. Use it to place things randomly on a grid, pick from a list of options by index, or add jitter to positions and timers. The sequence is deterministic for a given seed, so call <code>Random.seed</code> first if you need reproducible runs. To pick a random <code>column</code> across a grid of width <code>GRID_WIDTH</code>, pass <code>high: GRID_WIDTH - 1</code>, since the last valid index is one less than the count.
+
+Parameters:
+- `low` — the smallest value that can be returned (inclusive)
+- `high` — the largest value that can be returned (inclusive)
 
 ```ludic
-food_x = Random.range(low: 0, high: GRID_W - 1)
+program ScatterPickups {
+  property Position { column: int = 0, row: int = 0 }
+  model Pickup { Position }
+
+  const GRID_WIDTH: int = 20
+  const GRID_HEIGHT: int = 15
+  const TILE_SIZE: int = 16
+
+  handler SeedPickups phase Start {
+    Random.seed(value: 7)
+    for spawn_index in 0 .. 5 {
+      spawn Pickup {
+        Position {
+          column: Random.range(low: 0, high: GRID_WIDTH - 1),
+          row: Random.range(low: 0, high: GRID_HEIGHT - 1)
+        }
+      }
+    }
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    for (Position) in query [Position, {Pickup}] {
+      Screen.fill_rectangle(
+        x: Position.column * TILE_SIZE,
+        y: Position.row * TILE_SIZE,
+        width: TILE_SIZE,
+        height: TILE_SIZE,
+        color: Color.Gold)
+    }
+    Screen.show()
+  }
+}
 ```

docs/language/random/random-seed.md

@@ -5,8 +5,49 @@ category: random
 kind: namespace-method
 tokens: Random.seed
 sig: Random.seed(value)
-tip: Seed the RNG.
+tip: Seed the random generator so runs are reproducible.
 order: 2
+ns: Random
+member: seed
 ---
 
-Seed the RNG. Seeding with the same value makes runs reproducible.
+Sets the starting state of the random-number generator. Every subsequent call to <code>Random.range</code> and <code>Random.chance</code> then follows a fixed, repeatable sequence for that seed, so seeding with the same <code>value</code> makes two runs produce identical randomness — invaluable for tests, replays, and debugging. Seed once, typically in a <code>Start</code>-phase handler before you draw any random numbers. Use different seed values (for example a frame count or a level number) when you want variety between runs.
+
+Parameters:
+- `value` — the seed; the same value reproduces the same sequence
+
+```ludic
+program ReproducibleField {
+  property Position { column: int = 0, row: int = 0 }
+  model Star { Position }
+
+  const GRID_WIDTH: int = 20
+  const GRID_HEIGHT: int = 15
+  const TILE_SIZE: int = 16
+
+  handler SeedField phase Start {
+    Random.seed(value: 42)
+    for spawn_index in 0 .. 8 {
+      spawn Star {
+        Position {
+          column: Random.range(low: 0, high: GRID_WIDTH - 1),
+          row: Random.range(low: 0, high: GRID_HEIGHT - 1)
+        }
+      }
+    }
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    for (Position) in query [Position, {Star}] {
+      Screen.fill_rectangle(
+        x: Position.column * TILE_SIZE,
+        y: Position.row * TILE_SIZE,
+        width: TILE_SIZE,
+        height: TILE_SIZE,
+        color: Color.White)
+    }
+    Screen.show()
+  }
+}
+```