add better messagin

Author: print-sid8

README.md

@@ -25,6 +25,13 @@ Rasteret parses those headers **once**, caches them in Parquet, and its
 own reader fetches pixels concurrently with no GDAL in the path.
 **Up to 20x faster** on cold starts.
 
+We call this pattern **index-first geospatial image retrieval**:
+
+- **Control plane**: a queryable Parquet index (scene metadata, COG header metadata, user columns like splits/labels)
+- **Data plane**: on-demand tile reads from the original GeoTIFF/COG objects
+
+This keeps metadata and experiment logic in tables while leaving imagery bytes in source COGs.
+
 - **Easy** - three lines from STAC search or Parquet file to a TorchGeo-compatible dataset
 - **Zero downloads** - work with terabytes of imagery while storing only megabytes of metadata
 - **No STAC at training time** - query once at setup; zero API calls during training

docs/explanation/design-decisions.md

@@ -4,6 +4,16 @@ This page documents the key design choices behind Rasteret and the reasoning
 that drives them. It is aimed at contributors and advanced users who want to
 understand *why* things work the way they do.
 
+## Category framing
+
+Rasteret follows an **index-first geospatial retrieval** architecture:
+
+- **Control plane (tables/Parquet)**: discovery, filtering, splits/labels, and cached COG header metadata.
+- **Data plane (COG object storage)**: on-demand tile byte reads from source GeoTIFFs.
+
+This separation is intentional. It preserves table interoperability for metadata
+workflows while avoiding payload-in-Parquet duplication for routine pixel reads.
+
 ## Why Parquet indexes?
 
 Remote COGs require an HTTP HEAD + IFD range read per file just to discover

docs/index.md

@@ -24,6 +24,13 @@
            (once)                 (queryable)          (no GDAL, no headers)
     ```
 
+!!! info "Category: index-first geospatial retrieval"
+
+    Rasteret treats Parquet as the **control plane** (scene metadata + COG
+    header metadata + user-enriched columns), and COG object storage as the
+    **data plane** (pixel bytes fetched on demand). Metadata stays table-native;
+    imagery bytes stay in source COGs.
+
 ---
 
 <div class="grid cards" markdown>