feat(examples): Basic, a ball simulation with a bug to find

The example was a placeholder that printed which build it was. It is
now a headless simulation of five balls dropped onto a 10 cm floor
slab at 60 ticks a second, with a bug planted the way such bugs are
written: collision is checked only where each step lands, so the ball
dropped from 60 m, at 34 m/s, steps over the slab and falls forever.

It shows the consumer side end to end:
- Basic.DebugShim forwards Pump, Advance, QuitRequested, Log, Check,
  Emit and Sample to Crafter.Debug in debug builds and does nothing in
  plain ones, so the simulation and main have no #ifdef but the
  session's.
- Basic.DebugCommands, compiled only when Debug::Use returns true,
  registers World_Spawn, World_Reset, World_Clear and Ball_Get, and
  watches for the physics, the floor and the balls.
- The simulation checks each ball stays above the floor, emits Bounce
  and samples the fastest ball, so `pause --on-check`, `wait --event`
  and `trace --history` have something to show.

Driven over the real transport, it shows the whole loop: `log --level
warn` names the ball, `pause --on-check` stops the frame it fails,
`set physics.substeps 4` and `call World_Reset` show the fix holds
before any code changes. The plain build simulates ten seconds and
prints that one ball fell through. Its agent notes describe the app
without the bug.

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

examples/Basic/implementations/Basic.DebugCommands.cpp

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
+
+module Basic.DebugCommands;
+import std;
+import Crafter.Debug;
+import Basic.World;
+namespace Debug = Crafter::Debug;
+
+namespace Basic {
+    struct SpawnArgs {
+        Debug::Required<float> y;
+        float x = 0;
+        float vy = 0;
+        float radius = 0.1f;
+    };
+
+    struct BallArgs {
+        Debug::Required<std::int32_t> id;
+    };
+}
+
+void Basic::RegisterDebug(World& world) {
+    // Commands run on the main thread, between ticks, so they touch the
+    // world as the simulation does.
+    Debug::Command("World_Spawn", "Drop a ball from height y (m), moving at vy (m/s, up is positive); returns its id.",
+                   [&world](const SpawnArgs& args) -> Debug::Result<std::int32_t> {
+                       if (args.radius <= 0) return Debug::Error{ "BadRadius", "radius must be above 0" };
+                       if (*args.y - args.radius <= world.floor.top) {
+                           return Debug::Error{ "BelowFloor", std::format("y must clear the floor's top ({} m) by the radius", world.floor.top) };
+                       }
+                       return world.Spawn(args.x, *args.y, args.vy, args.radius);
+                   });
+    Debug::Command("World_Reset", "Remove every ball and drop the scene's five again.", [&world] { world.Reset(); });
+    Debug::Command("World_Clear", "Remove every ball.", [&world] { world.Clear(); });
+    Debug::Command("Ball_Get", "One ball's position, velocity and state.", [&world](const BallArgs& args) -> Debug::Result<Ball> {
+        if (const Ball* ball = world.Find(*args.id)) return *ball;
+        return Debug::Error{ "NoBall", std::format("no ball {}; `get balls` lists them", *args.id) };
+    });
+
+    Debug::Watch("physics.gravity", world.physics.gravity, { .min = -50, .max = 0, .help = "m/s^2" });
+    Debug::Watch("physics.restitution", world.physics.restitution, { .min = 0, .max = 1, .help = "share of speed kept by a bounce" });
+    Debug::Watch("physics.substeps", world.physics.substeps, { .min = 1, .max = 16, .help = "collision checks per tick" });
+    Debug::Watch("floor.top", world.floor.top, { .help = "m" });
+    Debug::Watch("floor.thickness", world.floor.thickness, { .min = 0.01, .max = 10, .help = "m" });
+    Debug::Watch("world.time", [&world] { return world.Time(); }, { .help = "simulated seconds since the last reset" });
+    Debug::Watch("world.count", [&world] { return world.Balls().size(); }, { .help = "balls in the scene" });
+    Debug::Watch("world.lost", [&world] { return world.Lost(); }, { .help = "balls below the floor" });
+    Debug::Watch("world.fastest", [&world] { return world.Fastest(); }, { .help = "m/s, last tick" });
+    Debug::Watch("balls", [&world] { return std::vector<Ball>(world.Balls().begin(), world.Balls().end()); });
+}