google · jdbcode · Apr 21, 2026 · Apr 21, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,75 @@
+# AGENTS.md
+
+Guidance for automation tools and AI coding assistants working in this
+repository.
+
+## Purpose
+
+Xee is an Xarray backend for Google Earth Engine. The primary user API is:
+
+- `xr.open_dataset(..., engine='ee')`
+
+When making workflow examples, integrations, or docs updates, optimize for this
+user-facing API first.
+
+## Current Version Context
+
+- Xee `v0.1.0` is a refactor with breaking changes.
+- Some repository examples are still pre-v0.1.0 and are being updated.
+- For migration context, see `docs/migration-guide-v0.1.0.md`.
+
+## Canonical Dev Commands
+
+Use Pixi environments so behavior is reproducible across platforms.
+
+- Unit tests: `pixi run -e tests pytest -q xee/ext_test.py`
+- Integration tests: `pixi run -e tests pytest -q xee/ext_integration_test.py`
+- Docs build: `pixi run -e docs docs-build`
+- Docs strict check: `pixi run -e docs docs-check`
+
+Before proposing completion, run at least unit tests for touched areas and
+`docs-check` for docs changes.
+
+## Integration Guidance (for tools helping users adopt Xee)
+
+1. Prefer `xr.open_dataset(..., engine='ee')` examples over backend internals.
+2. Show one of these grid strategies explicitly:
+   - `helpers.extract_grid_params(...)` for matching source grid
+   - `helpers.fit_geometry(..., grid_shape=...)` for fixed output shape
+   - `helpers.fit_geometry(..., grid_scale=...)` for fixed physical resolution
+3. Use consistent endpoint advice:
+   - High-volume endpoint for stored collections
+   - Standard endpoint for computed collections / iterative workflows
+4. Mention that both plain asset IDs and `ee://...` forms are accepted.
+5. Prefer AOI wording as: `AOI (area of interest)` on first use.
+
+## Files To Prefer For Source-of-Truth
+
+- Install/setup: `docs/installation.md`
+- First-user flow: `docs/quickstart.md`
+- Concepts/terminology: `docs/concepts.md`
+- Canonical parameter reference: `docs/open_dataset.md`
+- Performance guidance: `docs/performance.md`
+- Contributor process and required checks: `docs/contributing.md`
+
+## Documentation Expectations
+
+If behavior or API usage changes, update docs in the same change where practical:
+
+- Update user-facing docs first, then examples.
+- Avoid adding duplicate guidance in many places; link to canonical pages.
+- Keep examples explicit about grid parameters and endpoint assumptions.
+
+## Avoid
+
+- Recommending backend internals (`EarthEngineStore`) as primary user entrypoint.
+- Adding new examples that depend on outdated pre-v0.1.0 assumptions.
+- Mixing contradictory endpoint guidance across docs.
+- Introducing new terminology variants when established wording exists.
+
+## PR-Ready Checklist
+
+- Code and docs are aligned with current `v0.1.0` guidance.
+- Relevant tests or checks were run and summarized.
+- New docs links resolve and `docs-check` passes.
+- Any known limitations are stated explicitly.
diff --git a/README.md b/README.md
@@ -1,12 +1,9 @@
 > **⚠️ Breaking Change in v0.1.0**
 >
-> A major refactor was released in v0.1.0, introducing breaking changes to the Xee API. In most cases, existing code written for pre-v0.1.0 versions will require updates to remain compatible.
+> v0.1.0 includes a major refactor with breaking API changes.
 >
-> - See the [Migration Guide](https://github.com/google/Xee/blob/main/docs/migration-guide-v0.1.0.md) for details on updating your code.
-> - If you need more time to migrate, you can pin your environment to the latest pre-v0.1.0 release.
->
-> **During the v0.1.0 prerelease window:** `pip install xee` and `conda install xee` may still install the previous stable line.
-> To use the refactored API documented here, install a prerelease with `pip install --upgrade --pre xee` or pin an RC such as `pip install xee==0.1.0rc1`.
+> - Migration steps: [docs/migration-guide-v0.1.0.md](docs/migration-guide-v0.1.0.md)
+> - Canonical install options (prerelease vs stable): [docs/installation.md](docs/installation.md)
 
 # Xee: Xarray + Google Earth Engine
 
@@ -22,31 +19,14 @@ Xee is an Xarray backend for Google Earth Engine. Open `ee.Image` / `ee.ImageCol
 
 ## Install
 
-For the refactored v0.1.0 API documented below (prerelease period):
+For the latest v0.1.0 prerelease:
 
 ```bash
 pip install --upgrade --pre xee
 ```
 
-or pin a specific release candidate:
-
-```bash
-pip install xee==0.1.0rc1
-```
-
-For the current stable line (pre-v0.1.0 API):
-
-```bash
-pip install --upgrade xee
-```
-
-or
-
-```bash
-conda install -c conda-forge xee
-```
-
-Note: conda-forge may lag PyPI during prerelease testing. Use pip for the latest RC builds.
+For all installation paths (including stable line and conda), see
+[docs/installation.md](docs/installation.md).
 
 ## Minimal example
 
@@ -59,7 +39,7 @@ from xee import helpers
 #   earthengine authenticate
 
 project = 'PROJECT-ID'  # Set your Earth Engine registered Google Cloud project ID
-# Initialize (high‑volume endpoint recommended for reading stored collections)
+# Initialize (high-volume endpoint recommended for reading stored collections)
 ee.Initialize(project=project, opt_url='https://earthengine-highvolume.googleapis.com')
 
 # Open a dataset by matching its native grid
@@ -71,9 +51,9 @@ print(ds)
 
 Next steps:
 
-- [Quickstart](https://github.com/google/Xee/blob/main/docs/quickstart.md)
-- [Concepts (grid params, CRS, orientation)](https://github.com/google/Xee/blob/main/docs/concepts.md)
-- [User Guide (workflows)](https://github.com/google/Xee/blob/main/docs/guide.md)
+- [Quickstart](docs/quickstart.md)
+- [Concepts (grid params, CRS, orientation)](docs/concepts.md)
+- [User Guide (workflows)](docs/guide.md)
 
 ## Features
 

diff --git a/docs/README.md b/docs/README.md
@@ -2,10 +2,10 @@
 
 > **⚠️ Breaking Change in v0.1.0**
 >
-> A major refactor was released in v0.1.0, introducing breaking changes to the Xee API. In most cases, existing code written for pre-v0.1.0 versions will require updates to remain compatible.
+> v0.1.0 includes breaking API changes.
 >
-> - See the [Migration Guide](migration-guide-v0.1.0.md) for details on updating your code.
-> - If you need more time to migrate, you can pin your environment to the latest pre-v0.1.0 release.
+> - Migration steps: [migration-guide-v0.1.0.md](migration-guide-v0.1.0.md)
+> - Install options (prerelease vs stable): [installation.md](installation.md)
 
 ## For nicely rendered documentation
 

diff --git a/docs/concepts.md b/docs/concepts.md
@@ -31,6 +31,7 @@ The tuple follows the [Rasterio/`affine.Affine`](https://affine.readthedocs.io/e
 
 Instead of constructing these manually, prefer helpers:
 
+- AOI means area of interest.
 - `extract_grid_params(obj)`: Match an `ee.Image` or `ee.ImageCollection` source grid.
 - `fit_geometry(geometry, grid_crs, grid_scale=(x, y))`: Define pixel size (resolution) over an AOI.
 - `fit_geometry(geometry, grid_crs, grid_shape=(w, h))`: Define output array dimensions, letting resolution float.
@@ -45,7 +46,7 @@ Datasets are returned as `[time, y, x]` aligning with CF conventions and most ge
 
 ## Stored vs Computed Collections
 
-- Stored: unmodified `ee.ImageCollection('ID')` — use high‑volume endpoint for throughput.
+- Stored: unmodified `ee.ImageCollection('ID')` — use high-volume endpoint for throughput.
 - Computed: collections after `.map()`, `.select()`, filtering, band math — standard endpoint sometimes more efficient due to caching.
 
 ## Choosing a Grid Strategy

diff --git a/docs/examples.md b/docs/examples.md
@@ -0,0 +1,38 @@
+---
+title: Examples
+orphan: true
+---
+
+# Examples
+
+```{admonition} Status note
+:class: warning
+
+Most examples linked here currently target the pre-v0.1.0 API and may not work
+as-is with the refactored v0.1.0 interface documented in this site.
+
+These examples are being updated and expanded.
+```
+
+This page points to runnable end-to-end examples maintained in the repository.
+
+## Core examples
+
+- [examples/README.md](https://github.com/google/Xee/blob/main/examples/README.md)
+- [examples/ee_to_zarr.py](https://github.com/google/Xee/blob/main/examples/ee_to_zarr.py)
+- [examples/ee_to_zarr_reqs.txt](https://github.com/google/Xee/blob/main/examples/ee_to_zarr_reqs.txt)
+
+## Dataflow pipeline example
+
+- [examples/dataflow/README.md](https://github.com/google/Xee/blob/main/examples/dataflow/README.md)
+- [examples/dataflow/ee_to_zarr_dataflow.py](https://github.com/google/Xee/blob/main/examples/dataflow/ee_to_zarr_dataflow.py)
+- [examples/dataflow/requirements.txt](https://github.com/google/Xee/blob/main/examples/dataflow/requirements.txt)
+- [examples/dataflow/Dockerfile](https://github.com/google/Xee/blob/main/examples/dataflow/Dockerfile)
+
+## Choosing where to start
+
+- New to Xee: start with [Quickstart](quickstart.md), then
+  [examples/README.md](https://github.com/google/Xee/blob/main/examples/README.md).
+- Need reproducible chunked outputs: use
+  [examples/ee_to_zarr.py](https://github.com/google/Xee/blob/main/examples/ee_to_zarr.py).
+- Need scalable batch execution: use the Dataflow example set.
diff --git a/docs/guide.md b/docs/guide.md
@@ -2,6 +2,14 @@
 
 This guide collects practical workflows. For underlying theory see [Core Concepts](concepts.md). For a minimal setup see the [Quickstart](quickstart.md).
 
+```{admonition} Where do these parameters come from?
+:class: tip
+
+All examples in this guide ultimately call `xr.open_dataset(..., engine='ee')`.
+Use [Open Dataset Reference](open_dataset.md) for the complete parameter list,
+defaults, and runtime behavior.
+```
+
 ## Match Source Grid
 
 Use `helpers.extract_grid_params` to mirror the dataset's native projection & resolution.
@@ -15,7 +23,7 @@ grid_params = helpers.extract_grid_params(ic)
 ds = xr.open_dataset(ic, engine='ee', **grid_params)
 ```
 
-## Fit Area to a Shape
+## Fit Area of Interest (AOI) to a Shape
 
 Derive a grid that covers an AOI with a fixed pixel count (resolution floats).
 
@@ -33,7 +41,7 @@ grid_params = helpers.fit_geometry(
 ds = xr.open_dataset('ee://ECMWF/ERA5_LAND/MONTHLY_AGGR', engine='ee', **grid_params)
 ```
 
-## Fit Area to a Scale (Resolution)
+## Fit Area of Interest (AOI) to a Scale (Resolution)
 
 Fix physical pixel size; grid dimensions derived from AOI extent.
 
@@ -159,4 +167,5 @@ temp_slice.plot()
 - [Core Concepts](concepts.md)
 - [Performance & Limits](performance.md)
 - [FAQ](faq.md)
-- Examples: see [examples](https://github.com/google/Xee/tree/main/examples) directory in the repository
+- Repository examples (legacy pre-v0.1.0, update in progress):
+    <https://github.com/google/Xee/tree/main/examples>
diff --git a/docs/index.md b/docs/index.md
@@ -21,6 +21,7 @@ quickstart
 installation
 concepts
 guide
+open_dataset
 client-vs-server
 performance
 api

diff --git a/docs/installation.md b/docs/installation.md
@@ -106,7 +106,7 @@ top of your script, include one of the following expressions with the `project`
 argument modified to match the Google Cloud project ID enabled and registered
 for Earth Engine use.
 
-#### High-volume endpoint (bulk stored data)
+#### High-volume endpoint (stored collections)
 
 If you are requesting stored data (supplying a collection ID or passing an
 unmodified `ee.ImageCollection()` object to `xarray.open_dataset`), connect to
@@ -120,7 +120,7 @@ ee.Initialize(
 )
 ```
 
-#### Standard endpoint (computed / cached)
+#### Standard endpoint (computed collections / iterative development)
 
 If you are requesting computed data (applying expressions to the data), consider
 connecting to the [standard
@@ -131,3 +131,5 @@ something about the request.
 ```python
  ee.Initialize(project='your-project-id')
 ```
+
+For more tuning guidance, see [Performance & Limits](performance.md).