website update

Author: ttuff

AGENTS.md

@@ -190,6 +190,8 @@ Implementation rules for agents:
 - Do not silently replace one viewer system with another without also updating docs, tests, and architectural notes.
 - If you touch axis placement, time-depth direction, cube-attached labels, or camera semantics, read `docs/dev/cube_viewer_invariants.md` first and keep those invariants aligned.
 - Fire-plot work must preserve separation between event geometry generation, climate/event data fusion, and rendering backend.
+- Prefer `FireEventDaily` and `FireHull` as the canonical fire/VASE object model; keep legacy names such as `TimeHull` only as compatibility aliases unless the task explicitly removes them.
+- Prefer cube-compatible outputs when possible. If a hull-to-cube or environment-attribution step is incomplete, expose a narrow documented API with a clear limitation instead of hiding the gap inside plotting code.
 - Do not claim fire_plot is fully migrated unless rendering actually runs through the custom cube-viewer path.
 - Do not update screenshots/docs only while leaving contradictory code behavior.
 - Do not change coordinate conventions without updating `docs/dev/cube_viewer_invariants.md` and relevant tests together.

README.md

@@ -12,12 +12,14 @@ update your code to use the new package name.
 
 ![Tests](https://github.com/CU-ESIIL/cubedynamics/actions/workflows/tests.yml/badge.svg) ![Docs](https://github.com/CU-ESIIL/cubedynamics/actions/workflows/pages.yml/badge.svg)
 
-CubeDynamics: a composable grammar of operations for spatiotemporal data cubes.
+CubeDynamics: a grammar of streaming environmental computation.
 
-CubeDynamics is a Python framework for analyzing environmental data as **spatiotemporal cubes**, rather than disconnected maps and time series.
+CubeDynamics is a Python framework for computing on environmental data streams through **spatiotemporal cubes**, rather than treating storage, retrieval, and visualization as the main product.
 
 It is designed for scientists and data practitioners who want to reason explicitly about **space, time, scale, and events**—and to do so reproducibly and efficiently, even for large datasets.
 
+Scientists and AI agents use the same streaming interface, so workflows can be explored interactively, scripted, or orchestrated programmatically without switching mental models.
+
 
 
 
@@ -39,6 +41,14 @@ Yet most workflows break these dimensions apart:
 
 CubeDynamics keeps **space and time together**, making spatiotemporal structure a first-class part of the analysis.
 
+Most neighboring tools answer:
+
+> How do I store, query, or retrieve a cube?
+
+CubeDynamics answers:
+
+> How do I compute on a stream of environmental data?
+
 ---
 
 ## What CubeDynamics enables
@@ -49,6 +59,15 @@ CubeDynamics keeps **space and time together**, making spatiotemporal structure
 - **Event- and hull-based workflows** (fires, droughts, phenology)
 - **Integrated visualization** of space–time structure
 
+Fire events now follow a clearer object model built around:
+
+- `FireEventDaily` for canonical FIRED-like daily event geometry
+- `FireHull` for the derived fire-time hull / VASE geometry
+
+The intent is to keep FIRED ingestion, hull geometry, environmental attribution,
+cube conversion, and visualization separable so fire workflows remain part of
+the same composable cube grammar as the rest of CubeDynamics.
+
 ---
 
 ## Minimal example

docs/capabilities/fire-vase.md

@@ -0,0 +1,125 @@
+# Fire VASE / FireHull
+
+CubeDynamics treats FIRED fire events as spatiotemporal objects, not just a list of polygons or a one-off plot. The fire/VASE workflow turns daily perimeters into a time-stacked hull that can participate in the same cube-centered grammar used elsewhere in the library.
+
+## Core objects
+
+### `FireEventDaily`
+
+`FireEventDaily` is the canonical daily fire event object.
+
+It stores:
+
+- `event_id`
+- `gdf` with daily perimeter geometry
+- `t0` / `t1`
+- `centroid_lat` / `centroid_lon`
+
+Useful entry points:
+
+```python
+from cubedynamics.fire_time_hull import FireEventDaily
+
+event = FireEventDaily.example()
+event = FireEventDaily.from_fired(fired_daily, event_id=12345)
+```
+
+### `FireHull`
+
+`FireHull` is the canonical fire-time hull / VASE object.
+
+It stores triangulated geometry and time metadata:
+
+- `verts_km`
+- `tris`
+- `t_days_vert`
+- `t_norm_vert`
+- `metrics`
+
+It exposes object methods aligned with CubeDynamics design principles:
+
+```python
+hull = event.to_hull()
+hull.metrics()
+hull.to_mesh()
+hull.to_cube(template_cube)
+hull.attach_environment(cube, variables=["vpd"])
+hull.plot(color="vpd")
+```
+
+`TimeHull` remains available as a compatibility alias, but `FireHull` is the preferred public name going forward.
+
+## Minimal runnable example
+
+```python
+from cubedynamics.fire_time_hull import FireEventDaily
+
+event = FireEventDaily.example()
+hull = event.to_hull(n_ring_samples=24, n_theta=16)
+
+print(hull.metrics())
+mesh = hull.to_mesh()
+print(mesh["verts_km"].shape, mesh["tris"].shape)
+```
+
+For a complete lightweight example that does not require live FIRED downloads, see [Synthetic fire/VASE recipe](../recipes/fire_vase_synthetic.md).
+
+## Metrics available now
+
+Stable metric names currently include:
+
+- `duration_days`
+- `scale_km`
+- `footprint_area_peak_km2`
+- `footprint_area_final_km2`
+- `hull_volume_km2_days`
+- `hull_surface_km_day`
+
+Legacy aliases retained for compatibility:
+
+- `days`
+- `volume_km2_days`
+- `surface_km_day`
+
+These metrics are geometric summaries of the hull. They are not yet a complete ecological or dynamical taxonomy.
+
+## Environmental attribution
+
+The scientific direction is:
+
+```python
+hull + environment -> explanatory fire manifold
+```
+
+The current first implementation is `FireHull.attach_environment(...)`, which stores per-variable `HullClimateSummary` objects keyed by variable name:
+
+```python
+hull_with_env = hull.attach_environment(cube, variables=["vpd"], method="nearest")
+fig = hull_with_env.plot(color="vpd")
+```
+
+This is intentionally modest but now mesh-aware. It stores:
+
+- the original summary-level `HullClimateSummary`
+- per-layer values aligned to hull time slices
+- per-vertex values aligned explicitly to the mesh
+
+It does not yet store a fully local `(x, y, t)` field sampled independently at every hull vertex.
+
+## Cube compatibility
+
+`FireHull.to_cube(template_cube)` returns a boolean occupancy cube aligned to a supplied template grid.
+
+Why a template is required:
+
+- CubeDynamics prefers explicit coordinate semantics.
+- The hull itself does not yet define a standalone canonical occupancy grid.
+- Requiring a template keeps the conversion predictable and composable.
+
+## Current limitations
+
+- The fire-specific interactive hull viewer still uses Plotly.
+- `FireHull.to_cube()` requires a template cube.
+- `attach_environment()` currently supports `method="nearest"` only.
+- Environmental attribution is summary-level, not yet full local hull-element attribution.
+- FIRED ingestion, hull geometry, attribution, and rendering are clearer than before, but not fully separated into independent public submodules yet.

docs/concepts/index.md

@@ -1,9 +1,11 @@
 # Concepts Overview
 
-This section answers: **How does the cube grammar represent space, time, and operations?** Use it to align on terminology before picking verbs, datasets, or recipes.
+This section answers: **How does the CubeDynamics computation model represent space, time, and operations?** Use it to align on terminology before picking verbs, datasets, or recipes.
+
+CubeDynamics is not another storage layer or another visualization package. It is a grammar of streaming environmental computation built to sit above many data systems.
 
 In this section you'll find:
-- How the cube grammar keeps dimensions explicit across a pipeline.
+- How the streaming-first grammar keeps dimensions explicit across a pipeline.
 - The relationship between cubes, pipes, verbs, and VirtualCubes.
 - Pointers to glossary terms and comparisons to other libraries.
 
@@ -18,6 +20,8 @@ Key links:
 ## Cube grammar pipeline
 CubeDynamics expresses analysis as a sequence of verbs connected by pipes, operating on explicit cube dimensions. This grammar keeps space, time, and scale visible throughout a workflow and ensures that intermediate steps remain inspectable.
 
+Scientists and AI agents can both reason about the same pipeline because the abstraction is intentionally small and explicit.
+
 ![Cube grammar pipeline](../assets/diagrams/cube_grammar_pipeline.png)
 
 ## Dimensions stay explicit
@@ -26,10 +30,10 @@ At its core, CubeDynamics works with xarray-backed DataArrays but applies strong
 - metadata about resolution, alignment, and scale
 - consistency enforced across operations
 
-The goal is to avoid hidden assumptions about where operations run. Dimensions are visible and intentional, making workflows easier to reason about and share.
+The goal is to avoid hidden assumptions about where operations run. Dimensions are visible and intentional, making workflows easier to reason about, share, and orchestrate.
 
 ## Streaming via VirtualCubes
-Environmental datasets are often too large to load into memory. VirtualCubes represent a cube without materializing it and stream chunks through analysis pipelines. Code stays the same whether you stream or work in memory, so scale becomes a configuration choice.
+Environmental datasets are often too large to load into memory. VirtualCubes represent a cube without materializing it and stream chunks through analysis pipelines. Code stays the same whether you stream or work in memory, so scale becomes a configuration choice rather than a rewrite.
 
 ## Pipes and verbs
 Instead of chaining methods, you compose verbs with `pipe(...)` to build declarative workflows:
@@ -40,7 +44,7 @@ from cubedynamics import pipe, verbs as v
 pipe(cube) | v.mean() | v.rolling() | v.plot()
 ```
 
-Pipelines remain inspectable objects, making it straightforward to debug, document, or extend analyses.
+Pipelines remain inspectable objects, making it straightforward to debug, document, extend analyses, or hand the same workflow to an agent.
 
 ## Read next
 - [Getting Started](../quickstart.md)