docs: automated documentation pipeline (per-symbol source → pages)

Replace the hardcoded landing page and minimal reference with a generated
documentation site driven by a single source of truth.

- docs/language/**: one file per symbol (93 keywords/types/builtins/namespace
  methods/operators/annotations), each with front-matter (id, kind, tokens,
  sig, tip) + description + a ```ludic example. Seeded by exploding the former
  inline SECTIONS list; these files are now the source of truth.
- docs/site/: site.json (editable hero/features/showcase/messaging, not
  hardcoded) + snippets/*.ludic (real programs shown on the landing page).
- tools/docgen/gen.py: generates index.html, api.html, ludic-highlight.js and
  symbols.json. The highlighter's symbol tables, hover tips and jump anchors
  are GENERATED from the per-symbol files — add a symbol and it is recognized,
  tipped and linked in every snippet automatically. Python stdlib only.
- tools/docgen/check.py: verifies the pages contract + that no snippet token
  links to a missing reference anchor.
- .forgejo/workflows/docs.yml: rebuilds and publishes to the pages branch on
  every push to main touching the docs sources.

Consumes the new Screen.*/Color.*/named-arg API and the 221-color palette.

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

docs/site/snippets/hero.ludic

@@ -0,0 +1,24 @@
+# the smallest program that exercises the whole ECS pipeline
+program Hello {
+
+  property Pos { x: int = 0, y: int = 0 }
+  property Vel { dx: int = 0, dy: int = 0 }
+
+  handler Boot phase Start {
+    spawn Mob { Pos { x: 3, y: 4 }  Vel { dx: 1, dy: 0 } }
+    spawn Mob { Pos { x: 10, y: 2 } Vel { dx: 0, dy: 1 } }
+  }
+
+  # a handler declares the entities it touches; the body
+  # runs once per match, each property bound by name.
+  @Queries(these: [Pos, Vel])
+  handler Move phase FixedUpdate {
+    Pos.x = Pos.x + Vel.dx
+    Pos.y = Pos.y + Vel.dy
+  }
+
+  handler Report phase Update {
+    for (p) in query [Pos] { print(p.x)  print(p.y) }
+    quit()
+  }
+}

docs/site/snippets/lifecycle.ludic

@@ -0,0 +1,20 @@
+program Toggles {
+  property Health { hp: int = 0, max: int = 100 }
+  property Shield { amount: int = 0 }
+  model Player { Health, Shield }
+
+  # hooks fire at the toggle point, data bound by name
+  @OnDisable(Shield) handler Down { print(Shield.amount + 1) }
+  @OnEnable(Shield)  handler Up   { print(Shield.amount + 2) }
+
+  handler Seed phase Start {
+    spawn Player { Health { max: 50 }, Shield { amount: 5 } }
+  }
+
+  handler Run phase Render {
+    for (e) in query [Player] { disable Shield on self() }   # @OnDisable
+    for (e) in query [Player] { enable  Shield on self() }   # @OnEnable, data intact
+    disable Player                                           # whole model off
+    quit()
+  }
+}

docs/site/snippets/scenes.ludic

@@ -0,0 +1,30 @@
+program SceneDemo {
+  var counter: int = 0
+
+  handler Boot phase Start { counter = 0  print(1000) }
+
+  scene Title start {
+    on enter { print(1) }
+    on exit  { print(2) }
+    layer Main {
+      handler Tick phase Update {
+        counter = counter + 1
+        print(100 + counter)
+        if counter >= 2 { become Play }        # hand off to Play
+      }
+    }
+  }
+
+  scene Play {
+    on enter { print(3)  counter = 0 }
+    on exit  { print(4) }
+    layer World {
+      handler Step phase Update {
+        counter = counter + 1
+        print(200 + counter)
+        if counter >= 2 { quit() }
+      }
+    }
+    layer Hud { handler Draw phase Render { print(900) } }
+  }
+}

docs/site/snippets/snake.ludic

@@ -0,0 +1,30 @@
+program Snake {
+  property Pos { x: int = 0, y: int = 0 }
+  property Seg { order: int = 0 }
+
+  const GRID_W: int = 20   const GRID_H: int = 15   const TILE: int = 16
+
+  var food_x: int = 14   var food_y: int = 7   var score: int = 0
+
+  handler Draw phase Render {
+    Screen.clear(Color.MidnightBlue)
+    # checkerboard field — a fresh, immutable gx/gy each pass
+    for gy in 0 .. GRID_H {
+      for gx in 0 .. GRID_W {
+        var tile_color = Color.Charcoal
+        if (gx + gy) % 2 == 0 { tile_color = Color.Gunmetal }
+        Screen.fill_rectangle(x: gx * TILE, y: gy * TILE, width: TILE, height: TILE, color: tile_color)
+      }
+    }
+    # the food, then every snake segment straight from the ECS
+    Screen.fill_rectangle(x: food_x * TILE + 3, y: food_y * TILE + 3, width: TILE - 6, height: TILE - 6, color: Color.Crimson)
+    for (p, s) in query [Pos, Seg] {
+      var seg_color = Color.LimeGreen
+      if s.order == 0 { seg_color = Color.MintGreen }        # brighter head
+      Screen.fill_rectangle(x: p.x * TILE + 1, y: p.y * TILE + 1, width: TILE - 2, height: TILE - 2, color: seg_color)
+    }
+    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()
+  }
+}