diff --git a/.gitignore b/.gitignore
index dc1e754..273b276 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 background-standalone.html
+Screenshot*.png
diff --git a/README.md b/README.md
index 0f8bdbd..f0837cc 100644
--- a/README.md
+++ b/README.md
@@ -7,9 +7,10 @@ dropped into an iframe or kiosk browser and left running.
 ## Features
 
 - **WebGL flight scene** (`vendor/clouds3d.js`): a 3D terrain mesh built from
-  real elevation data (Copernicus DEM), a raymarched volumetric cloud deck,
-  optional round-world curvature, and a figure-eight flight path around the
-  configured location with a vertical bob inside the 15-35 km flight band.
+  real elevation data (Copernicus DEM), a raymarched volumetric cloud deck with
+  soft layer edges and adaptive march length, optional round-world curvature,
+  and a figure-eight flight path around the configured location with a vertical
+  bob inside the 15-35 km flight band.
 - **One physical light model** shared by sky, clouds, contrails, aircraft and
   ground: direct beam through a Kasten-Young air mass with Rayleigh, ozone and
   aerosol extinction, diffuse skylight, moonlight, a starlight floor and aerial
@@ -129,13 +130,13 @@ flowchart TD
     F --> G[Sky pass: gradient, stars, Milky Way, sun, moon]
     G --> H[Star catalogue points]
     H --> I[Planet points]
-    G --> J[Terrain distance pass]
+    G --> J[Terrain distance pass, only when needed]
     J --> K[Terrain mesh pass]
     K --> L[City lights]
     L --> M[Car lights]
     M --> N[Optional atmosphere model]
     N --> O[Front haze]
-    O --> P[Cloud raymarch]
+    O --> P[Cloud raymarch, soft edges and adaptive march]
     P --> Q[Aircraft]
     Q --> R[Contrails]
 ```
@@ -252,14 +253,14 @@ Groups:
 | --- | --- |
 | `theme`, `language`, `timeFormat`, `units`, `credits` | palette, UI language, clock format, °C/°F, attribution line |
 | `debug` | debug panel (weather, shader counters, theme palette and lighting) |
-| `renderScale`, `maxFps` | internal 3D resolution and frame cap |
+| `renderScale`, `antialias`, `maxFps`, `performance` | internal 3D resolution, MSAA, frame cap and adaptive cloud-march quality |
 | `location` | `lat`/`lon` (+ optional `label`) - everything geographic |
 | `weatherSim`, `weatherSimInterval` | ignore the API and cycle the weather looks |
 | `tiles` | basemap re-fetch interval (`expireDays`), tile-border debug overlay |
 | `ground.style` | `'satellite'` (ESRI World_Imagery) or `'streets'` (ESRI World_Street_Map) |
 | `orbit` | figure-eight path, `radiusKm`, direction, reorientation, `altBob` |
 | `fog.distanceKm` | distance haze (0/false = off) |
-| `clouds` | deck height (`top`/`bottom` in world units), `density` per weather level, and `wind` motion from Open-Meteo |
+| `clouds` | deck height (`top`/`bottom` in world units), `density` per weather level, `wind` motion, soft edge/horizon fading, `maxMarchUnits` and `terrainOcclusion` |
 | `flights` | aircraft count, altitudes, speeds, destination weights, contrails, night strobes |
 | `terrain` | DEM mesh, `exaggeration`, edge fade/skirt, `outerDem`, `carLights`, `cityLights`, `wireframe` |
 | `carLights` | road width, light sizes, lane separation, traffic range/fade, `trafficSide`, spacing, speed, density, brightness |
@@ -280,6 +281,35 @@ Groups:
 (`y ≈ 1.16-2.70`). Cloud deck heights, fog distance and orbit radius are all
 expressed in these units or in km where noted.
 
+### Performance
+
+`CONFIG.performance` controls adaptive cloud raymarching:
+
+```javascript
+performance: {
+    adaptiveCloudMarch: true,
+    lowFps: 24,
+    highFps: 35,
+    minCloudMarchUnits: 45
+}
+```
+
+When the debug FPS drops below `lowFps`, the cloud march is shortened. When it
+stays above `highFps`, the march is restored toward `CONFIG.clouds.maxMarchUnits`.
+
+Other main performance knobs:
+
+- `renderScale`: lower internal 3D resolution.
+- `antialias: false`: disables MSAA.
+- `maxFps`: caps the animation loop.
+- `clouds.maxMarchUnits`: maximum cloud raymarch length.
+- `clouds.softEdges`, `edgeSoftness`, `horizonSoftness`: soft cloud edges;
+  disabling `softEdges` restores the old hard shell behaviour.
+- `atmosphere.cloudShadows` and `atmosphere.terrainShadows`: disable if the
+  scene is GPU-bound.
+- `flights.count`, `flights.contrailChance`, `carLights.density`,
+  `emergencyVehicles.count`: reduce scene-object density.
+
 ### Themes and theme lighting
 
 A theme is a stylesheet plus an optional lighting block: