diff --git a/docs/diagrams/architecture/d239-tile-derivation-contract.d2 b/docs/diagrams/architecture/d239-tile-derivation-contract.d2
new file mode 100644
index 000000000..e11f636c0
--- /dev/null
+++ b/docs/diagrams/architecture/d239-tile-derivation-contract.d2
@@ -0,0 +1,139 @@
+# D-239 — Tile derivation contract (resolves Q-101)
+# Coarse->fine refinement chain: RegionProfile (~1km) -> ChunkContext (64m) -> VoxelColumn (1m)
+
+vars: {
+  color-bg: "#2a3040"
+  color-stroke: "#333340"
+  color-text: "#c8d0e0"
+  color-accent: "#c8d8f0"
+  color-prim: "#3a4a4a"
+  color-warp: "#4a3a4a"
+}
+
+direction: right
+
+inputs: Inputs (authored upstream only) {
+  style.fill: ${color-bg}
+  style.font-color: ${color-text}
+  style.stroke: ${color-stroke}
+
+  seed: seed {
+    style.fill: ${color-bg}
+    style.font-color: ${color-text}
+  }
+  atlas: atlas (L0-L4) {
+    style.fill: ${color-bg}
+    style.font-color: ${color-text}
+  }
+  body: "body-params\n(stellar / orbit / hydrosphere / lithology)" {
+    style.fill: ${color-bg}
+    style.font-color: ${color-text}
+  }
+}
+
+climate: "Climate primitives (per 2x2 km district)" {
+  style.fill: ${color-prim}
+  style.font-color: ${color-text}
+  style.stroke: ${color-accent}
+
+  temp: "temperature  C  (nullable)\nsun + planet + atmosphere\nseason + day/night swing" {
+    style.fill: ${color-prim}
+    style.font-color: ${color-text}
+  }
+  moist: "moisture\n(separate primitive)" {
+    style.fill: ${color-prim}
+    style.font-color: ${color-text}
+  }
+  derived: "derived: precipitation / GlaciationGrade /\nvegetation+treeline / seasonal-clock (Q-105)\n+ scattered transient freeze+snow" {
+    style.fill: ${color-prim}
+    style.font-color: ${color-text}
+  }
+  temp -> derived
+  moist -> derived
+}
+
+chain: Three-carrier refinement chain (pure, deterministic D-010) {
+  style.fill: ${color-bg}
+  style.font-color: ${color-text}
+  style.stroke: ${color-accent}
+
+  region: "RegionProfile  (~1 km)\nmorphology family + tectonic_class\n+ derived RIVER_THRESHOLD" {
+    shape: hexagon
+    style.fill: ${color-bg}
+    style.font-color: ${color-text}
+    style.stroke: ${color-accent}
+  }
+  chunk: "ChunkContext  (64 m)\nbasin-dir + meander-curve params\n(no per-tile flow grid)" {
+    shape: hexagon
+    style.fill: ${color-bg}
+    style.font-color: ${color-text}
+    style.stroke: ${color-accent}
+  }
+  voxel: "VoxelColumn  (1 m)\non-demand, cached, never persisted" {
+    shape: hexagon
+    style.fill: ${color-bg}
+    style.font-color: ${color-text}
+    style.stroke: ${color-accent}
+  }
+  region -> chunk -> voxel
+}
+
+morph: "8 morphology families\n(gated decision tree)" {
+  style.fill: ${color-bg}
+  style.font-color: ${color-text}
+  fams: "Lava / Fjord / CliffCoast / BraidedDelta /\nDuneStrand / IncisedGorge / Meander / AlluvialPlain" {
+    style.fill: ${color-bg}
+    style.font-color: ${color-text}
+  }
+  gates: "hard gates: fjord>=Glaciation2 |\nLava=Volcanic | lithology bounds slope" {
+    style.fill: ${color-bg}
+    style.font-color: ${color-text}
+  }
+  vocab: "frozen 17-zone MorphologyZone vocab\n(enum = freeze point; change needs D-amendment)" {
+    style.fill: ${color-bg}
+    style.font-color: ${color-text}
+  }
+}
+
+warp: "Domain warp (anti-squaring)\nstateless hash(seed, body, pos)\nf64 sub-metre -> truncate to voxel addr" {
+  shape: parallelogram
+  style.fill: ${color-warp}
+  style.font-color: ${color-text}
+  style.stroke: ${color-accent}
+}
+
+cache: "BodyWorldState cache (D-203)\nRegionProfile labels for the Atlas\n(populated in D-206 background pass)" {
+  style.fill: ${color-bg}
+  style.font-color: ${color-text}
+}
+
+# wiring
+inputs -> chain.region: "(seed, atlas, body-params, position)" {
+  style.stroke: ${color-accent}
+}
+inputs.body -> climate.temp {
+  style.stroke: ${color-accent}
+  style.stroke-dash: 3
+}
+climate.derived -> chain.region: gates morphology + freeze {
+  style.stroke: ${color-accent}
+  style.stroke-dash: 3
+}
+chain.region -> morph.fams: select family {
+  style.stroke: ${color-accent}
+}
+morph.gates -> morph.fams {
+  style.stroke: ${color-stroke}
+}
+warp -> chain.chunk: "organic, seam-free" {
+  style.stroke: ${color-accent}
+  style.stroke-dash: 5
+}
+warp -> chain.voxel {
+  style.stroke: ${color-accent}
+  style.stroke-dash: 5
+}
+chain.region -> cache: store labels {
+  style.stroke: ${color-accent}
+  style.stroke-dash: 3
+}
diff --git a/docs/diagrams/architecture/d239-tile-derivation-contract.png b/docs/diagrams/architecture/d239-tile-derivation-contract.png
new file mode 100644
index 000000000..c85749a6a
Binary files /dev/null and b/docs/diagrams/architecture/d239-tile-derivation-contract.png differ