diff --git a/docs/superpowers/specs/2026-07-09-interstellar-blackhole-design.md b/docs/superpowers/specs/2026-07-09-interstellar-blackhole-design.md
new file mode 100644
index 0000000..438f734
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-09-interstellar-blackhole-design.md
@@ -0,0 +1,209 @@
+# singularity-rs — Interstellar-style Black Hole Renderer (Design Spec)
+
+**Date:** 2026-07-09
+**Status:** Draft (awaiting user review)
+**Project:** `singularity-rs` (Rust, edition 2024, Bevy 0.19)
+
+## 1. Goal
+
+A real-time, physically-motivated renderer of a Gargantua-style black hole in Bevy, matching the visual reference video (`5u1ymibkiixg1.mp4`): a black shadow, a tilted glowing accretion disk with the lensed halo wrapping over and under the hole, a Doppler brightness asymmetry, and a lensed background starfield — all produced by geodesic ray-tracing curved spacetime per pixel.
+
+The scope is deliberately larger than the reference video: it additionally includes a lensed spacetime-curvature (gravity-well) grid, lensed scene-planet spheres, and a cubemap skybox layer. The renderer is delivered in two phases: a fully-working Schwarzschild (non-spinning) renderer first, then an upgrade to the Kerr (spinning) metric for true Gargantua accuracy.
+
+## 2. Reference video analysis
+
+30 frames were extracted (1/sec) from `5u1ymibkiixg1.mp4` (800×432, 10fps, 30s) and analyzed. Findings that constrain this design:
+
+| Feature | Present in video | Notes |
+|---|---|---|
+| Black hole shadow | Yes | Dark circular region, stays centered |
+| Accretion disk | Yes | Orange/red-hot; tilted relative to camera orbit |
+| Lensed halo (over + under hole) | Yes | The classic wrap-over/wrap-under Einstein ring |
+| Doppler asymmetry | Yes | One side clearly brighter/hotter; bright side shifts as camera orbits |
+| Background stars | Yes | Visible in dark regions, distorted near the hole |
+| Gravity-well grid | No | Not present (but in scope per user decision) |
+| Planets / scene objects | No | Not present (but in scope per user decision) |
+| Cubemap skybox | No | Background is stars only (procedural) |
+| UI / HUD | No | Clean frame |
+
+**Camera motion in video:** smooth continuous orbit around the hole while slowly zooming; disk is tilted relative to the orbit plane, so both the disk face and the lensed halo are visible throughout.
+
+**Visual style target:** photorealistic, Gargantua-like — not stylized/cartoonish.
+
+## 3. Non-goals (Phase 1)
+
+- Kerr metric / frame dragging (Phase 2).
+- Volumetric rendering of the disk (it is a thin emitting surface).
+- Audio, gameplay, networking.
+- Loading external mesh assets (everything is procedural or simple spheres).
+- A real-time editable GUI editor (parameters are tuned via a debug params resource + keyboard; an egui panel is optional later).
+
+## 4. Physics & units
+
+Natural units with the Schwarzschild radius **Rs = 1** everywhere in the shader. This makes the characteristic radii clean and numerically stable:
+
+| Feature | Radius (Rs units) |
+|---|---|
+| Event horizon | 1.0 |
+| Photon sphere | 1.5 |
+| Shadow (critical impact parameter bcrit = 3√3/2 · Rs) | ≈ 2.598 |
+| ISCO (accretion disk inner edge) | 3.0 |
+| Accretion disk outer edge (tunable) | ~12–20 |
+
+### Geodesic integration (Schwarzschild)
+
+For each pixel, generate a photon ray (position `pos`, direction `dir`) and integrate the geodesic. The standard discretized form used across well-known real-time black-hole demos (mholub "Basic Black Hole Rendering"; rantonels *starless*):
+
+```
+per step:
+  r  = length(pos)
+  h2 = |cross(pos, dir)|^2          // squared angular momentum
+  a  = -1.5 * Rs * h2 / r^5 * pos   // geodesic bending acceleration (Rs=1)
+  dir = normalize(dir + a*dt)
+  pos = pos + dir*dt
+```
+
+Integrator: **RK4** (4th-order Runge-Kutta) with a tunable step count (default ~300, range 150–600). RK4 is chosen over Euler because Euler requires far more steps for the same accuracy near the photon sphere and smears the Einstein ring.
+
+Termination conditions for a ray (checked each step):
+1. `r < Rs` → captured by horizon → return pure black (this is the shadow; it emerges naturally at bcrit).
+2. `r > R_escape` (e.g. 1000) → escaped → sample skybox + procedural stars along final direction.
+3. Disk plane intersection within `[r_in, r_out]` → shade disk, **continue** integrating. A ray typically hits the disk multiple times (front pass, then wrapped over/under the hole) — each hit contributes an emissive color. Composite front-to-back by accumulating `(color·α)` and `(1−α)`; stop accumulating once the running alpha saturates near 1. This is what produces the over/under halo and higher-order images.
+4. Planet sphere intersection (within current step segment) → shade nearest planet, composite front-to-back; terminate the ray once alpha saturates (opaque planets occlude everything behind).
+5. Gravity-well (Flamm) surface intersection → shade grid (additive, low alpha), continue.
+
+**Critical for secondary images:** the loop does NOT terminate when a ray merely crosses the photon sphere and comes back. It runs the full step budget unless the accumulated alpha saturates (opaque hit) or the ray is captured/escapes. This is what produces secondary/higher-order Einstein images as in Luminet's paper.
+
+**Integrator form note:** the discretized pseudo-acceleration shown above (Cartesian `(pos, dir)` with the effective bending acceleration) is one valid real-time approximation. An alternative is the integrable Binet form `d²u/dφ² = (3/2)·Rs·u² − 1/(2Rs)` in `u=1/r`, which is more accurate but harder to combine with the off-plane disk/grid/planet intersection tests. The exact choice is a Phase-1 implementation decision in the plan; either way the *behavior* (lensing, shadow at bcrit, wrap halo) is identical.
+
+## 5. Scene elements
+
+### 5.1 Accretion disk
+- Thin emitting ring in the equatorial plane (rotated by a configurable disk tilt).
+- `r ∈ [r_in=3, r_out=15]` (tunable).
+- Intersection: detect sign change of the disk-plane coordinate across an integration step; solve for the crossing point; accept only if `r ∈ [r_in, r_out]`.
+- Procedural texture: layered radial + angular noise (hash-based, time-animated to simulate rotation). Brightness falls off near `r_in` (inner edge hottest) and `r_out`.
+- Color temperature gradient: hotter (white/blue) near `r_in`, cooler (orange/red) near `r_out`.
+- **Doppler beaming:** at each disk hit, compute the disk orbital velocity (relativistic Keplerian, `v = sqrt(Rs/(2r)) / sqrt(1 - Rs/r)` capped), the Doppler factor `δ = 1/(γ(1 − β·n̂))` relative to the ray direction, and scale intensity by `δ³` (and shift hue slightly blue for δ>1, red for δ<1). This produces the one-side-bright asymmetry seen in the reference.
+
+### 5.2 Background skybox (cubemap) + procedural stars
+- Optional cubemap texture bound to the material. When a ray escapes, sample the cubemap along its final direction. Procedural stars are layered on top as an additive detail (hash-based points on the unit sphere) with an intensity uniform.
+- If no cubemap is provided, procedural stars are the sole background (matches the reference video).
+- Because rays bend, the background (cubemap or stars) is naturally lensed: stars near the hole smear into arcs and can form secondary images.
+
+### 5.3 Planets (scene entities)
+- A `Planet` component: `Transform` (center), `radius`, `color`, `emissive` flag.
+- A system collects all `Planet` entities each frame into a `Vec<SphereData>` and uploads to a storage buffer bound to the material (`@group(1) var<storage, read> planets: array<SphereData>`).
+- In the shader, each integration step tests all spheres for ray-segment intersection; the nearest hit wins and is shaded (Lambert-ish with the color, optionally emissive). Planets are therefore fully lensed: a planet near the hole bends into an arc and can show secondary images.
+- The storage buffer also carries a count, and the loop is bounded by a `MAX_PLANETS` constant (e.g. 32) for unrolled/loop performance.
+
+### 5.4 Spacetime-curvature grid (Flamm paraboloid)
+- The classic embedding surface `z(r) = 2·sqrt(Rs·(r − Rs))` (dips down toward the center), oriented in the disk plane.
+- Ray-traced in the shader: each step tests intersection with the paraboloid surface. At a hit, apply a polar grid pattern from the (embedded) `(r, φ)`: bright rings at chosen radius intervals, radial spokes at chosen angle intervals. Fade with depth (z) so it reads as "below" the hole.
+- The grid is **lensed**: because it is traced through curved spacetime, grid lines bend dramatically near the hole and can wrap. Partially transparent (additive) so it never fully occludes the disk.
+- This feature is **off by default** (the reference video does not show it); toggled via a parameter.
+
+## 6. Bevy rendering architecture
+
+- The scene is 100% procedural (no 3D meshes to composite over). The black hole is drawn by a **single full-screen quad** with a custom `Material2d`, whose fragment shader performs all ray-tracing. No scene-color texture is read, so a full-screen `Material2d` is simpler than a render-graph post-processing node.
+- The "camera" is just a set of material uniforms (eye position, forward/right/up vectors, FOV, aspect) updated each frame from the orbit controller.
+- `Material2d` puts our bind group at **group 1** (group 0 is Bevy's view uniforms). WGSL bindings:
+  - `@group(1) @binding(0) var<uniform> params: BlackHoleParams;`
+  - `@group(1) @binding(1) var<uniform> camera: CameraParams;`
+  - `@group(1) @binding(2) var skybox: texture_cube<f32>;` + `@group(1) @binding(3) var skybox_sampler;`
+  - `@group(1) @binding(4) var<storage, read> planets: array<SphereData>;` (+ count in params)
+- Render-scale support: the quad is drawn at `render_scale` (0.5–1.0) of the window and upscaled, needed for the Phase 2 Kerr integrator. Phase 1 targets 1.0 at 60fps.
+
+## 7. Camera & interaction
+
+Orbit controller around the origin:
+- **Drag** (mouse) → yaw/pitch the camera around the hole.
+- **Wheel** → change camera distance (= impact parameter / how close to the hole).
+- **Keyboard** → live-tune: disk inner/outer radius, disk tilt, disk brightness, Doppler intensity, integrator step count, render scale, grid toggle, procedural-star intensity.
+- Parameters live in a `BlackHoleParams` `Resource`; a system mirrors them into the material's uniform each frame.
+
+Default scene (matches the reference): camera at moderate distance, disk tilted ~70–80° from face-on (so the lensed halo is prominent), Doppler enabled, grid off, procedural stars on.
+
+## 8. File structure
+
+```
+src/
+  main.rs              # App setup, plugin registration, default scene
+  params.rs            # BlackHoleParams resource (CPU mirror of uniforms)
+  camera.rs            # Orbit camera input controller
+  scene/
+    mod.rs
+    disk.rs            # Disk parameters & defaults
+    planets.rs         # Planet component + storage-buffer upload system
+  render/
+    plugin.rs          # Full-screen quad + camera + material setup
+    material.rs        # BlackHoleMaterial: AsBindGroup (uniforms, cubemap, storage buffer)
+assets/shaders/
+  black_hole.wgsl      # Entry point: ray gen → integrate → composite
+  ray_gen.wgsl         # Per-pixel ray direction from camera params
+  geodesic_schwarzschild.wgsl   # RK4 integrator (Phase 1)
+  geodesic_kerr.wgsl            # Kerr integrator (Phase 2)
+  disk.wgsl            # Plane intersection + procedural texture + Doppler
+  planets.wgsl         # Sphere intersection + shading
+  grid.wgsl            # Flamm paraboloid intersection + grid pattern
+  stars.wgsl           # Procedural starfield
+  skybox.wgsl          # Cubemap sampling
+  common.wgsl          # Shared structs (SphereData, params, camera), constants
+```
+
+## 9. Parameters (`BlackHoleParams`)
+
+Tunable, mirrored to the GPU uniform each frame:
+
+| Field | Default | Meaning |
+|---|---|---|
+| `rs` | 1.0 | Schwarzschild radius (natural units) |
+| `disk_inner` | 3.0 | Disk inner radius (ISCO) |
+| `disk_outer` | 15.0 | Disk outer radius |
+| `disk_tilt` | ~75° | Disk plane tilt vs. camera |
+| `disk_brightness` | 1.0 | Global disk intensity |
+| `doppler_strength` | 1.0 | Multiplier on beaming asymmetry |
+| `steps` | 300 | Integrator step count |
+| `dt` | derived | Step size (auto from escape radius / steps) |
+| `render_scale` | 1.0 | Render resolution scale |
+| `grid_enabled` | false | Toggle Flamm grid |
+| `star_intensity` | 1.0 | Procedural star brightness |
+| `spin` | 0.0 | Kerr spin parameter (Phase 2) |
+| `planet_count` | 0 | Number of valid entries in planets buffer |
+
+## 10. Phasing
+
+### Phase 1 — Schwarzschild (this project's main deliverable)
+All scene elements (disk + Doppler, skybox/stars, planets, grid) against the Schwarzschild geodesic integrator. Deliverables:
+- Working Bevy app matching the reference video look (shadow, tilted Doppler disk, lensed halo over/under, lensed stars) by default.
+- Grid + planets + cubemap as additional enabled features.
+- Orbit camera + live params.
+- Unit tests for the CPU-mirrored math constants (bcrit ≈ 2.598; a ray at large impact parameter has known small deflection).
+- Target 60fps at full render scale on a typical discrete GPU.
+
+### Phase 2 — Kerr (true Gargantua; documented follow-up, separate plan)
+Replace `geodesic_schwarzschild.wgsl` with `geodesic_kerr.wgsl` integrating the Kerr geodesic equations (Boyer-Lindquist) with adaptive RK4. Adds frame-dragging/ergosphere asymmetry. Expected to require `render_scale ≈ 0.5` + upscaling. The same scene elements, camera, and params carry over unchanged; only the integrator core swaps. This is a separate spec/plan once Phase 1 ships.
+
+## 11. Testing & verification
+
+This is primarily a visual artifact; verification strategy:
+- **Unit tests (Rust):** mirror the shader's key constants/relations in CPU code and assert: bcrit = 3√3/2 ≈ 2.598; a ray launched with impact parameter `b < bcrit` falls below `Rs`; a ray with `b >> bcrit` is deflected by an amount within tolerance of the weak-field formula `δθ ≈ 2Rs/b`. These guard the math against silent regressions.
+- **Visual milestones (manual):**
+  1. Plain starfield renders with the full-screen shader.
+  2. Black circular shadow appears, sized ~bcrit.
+  3. First Einstein ring appears when a disk is added edge-on.
+  4. Tilted disk shows the over/under halo (the money shot matching the reference).
+  5. Doppler asymmetry: one side brighter, bright side shifts as camera orbits.
+  6. Lensing of stars visible near the hole edge.
+  7. (Feature) grid bends near the hole; (feature) planet arcs near the hole.
+- Performance budget check: confirm ≥60fps at `render_scale=1.0`, Steps=300, in Phase 1.
+
+## 12. Risks & mitigations
+
+| Risk | Mitigation |
+|---|---|
+| RK4 too slow at 300 steps/full-res | Make steps + render_scale live params; profile early. Phase 1 default can drop to 200 steps. |
+| WGSL storage-buffer support edge cases for planets | Bound loop with `MAX_PLANETS` constant; fall back to uniform array if needed. |
+| Flamm grid adds noise/visual clutter | Off by default; additive + faded; separate toggle. |
+| Kerr math instability (Phase 2) | Isolated to Phase 2; adaptive step; does not block Phase 1. |
+| Secondary images absent (loop terminates early) | Explicit non-termination policy across photon sphere (Section 4). |