📄 docs(agents): update AGENTS.md files for v1.0.0 structure

Sync the root, containers and storage AGENTS.md with the post-V1 repo:
- root: fix project tree (drop removed bridges/pipelines/post/examples,
  add cli/types/viewer/downloadable_examples), fix Core abstractions table
  (Dataset/Features/FeatureIdentifier removed -> Sample/Infos/ProblemDefinition),
  doc tooling Sphinx -> Zensical, build command -> docs/generate_doc.sh
- containers: Dataset/Features/FeatureIdentifier no longer exist; document Sample
  (pydantic BaseModel), DefaultManager and utils helpers
- storage: add backend_api.py (BackendModule Protocol) and the BACKENDS registry

Author: xroynard

AGENTS.md

@@ -48,7 +48,7 @@ issues, or documentation).
 - **Build backend**: setuptools with setuptools-scm (dynamic versioning)
 - **Linter/formatter**: ruff
 - **Test framework**: pytest
-- **Documentation**: Sphinx (ReadTheDocs)
+- **Documentation**: Zensical (with mkdocstrings for the API reference), published on ReadTheDocs
 - **CI/CD**: GitHub Actions
 
 ## Project structure
@@ -61,38 +61,47 @@ issues, or documentation).
 ├── CHANGELOG.md               <- Version history
 ├── CONTRIBUTING.md            <- Contribution guidelines
 ├── src/plaid/                 <- Source code
-│   ├── __init__.py
+│   ├── __init__.py            <- Public API: Sample, Infos, ProblemDefinition
 │   ├── constants.py           <- Global constants
 │   ├── problem_definition.py  <- ProblemDefinition (core concept)
-│   ├── containers/            <- Dataset, Sample, Features (see nested AGENTS.md)
+│   ├── infos.py               <- Infos (dataset/problem metadata)
+│   ├── containers/            <- Sample container + helpers (see nested AGENTS.md)
 │   ├── storage/               <- Storage backends: zarr, hf_datasets, cgns (see nested AGENTS.md)
-│   ├── bridges/               <- HuggingFace bridge utilities
-│   ├── pipelines/             <- sklearn-compatible processing blocks
-│   ├── post/                  <- Post-processing (metrics, bisection)
-│   └── examples/              <- Built-in example datasets
+│   ├── types/                 <- Shared type aliases and definitions
+│   ├── cli/                   <- Command-line entry points (e.g. plaidcheck)
+│   ├── viewer/                <- Dataset visualization services
+│   └── downloadable_examples/ <- Built-in downloadable example datasets
 ├── tests/                     <- Test suite
 ├── docs/                      <- Sphinx documentation source
-├── examples/                  <- Usage examples
-└── benchmarks/                <- Performance benchmarks
+└── examples/                  <- Usage examples
 ```
 
+> Note: the v1.0.0 reorganization removed the top-level `Dataset` re-export and the
+> `bridges/`, `pipelines/`, `post/` and `examples/` source packages. Data is now handled
+> through `Sample` objects and the `storage` layer. See `docs/source/upgrade_guide.md`.
+
 ## Architecture and key concepts
 
 ### Core abstractions
 
 | Concept | Module | Description |
 |---------|--------|-------------|
 | `ProblemDefinition` | `problem_definition.py` | Declares fields, meshes, and their roles (input/output/context) for a physics problem |
-| `Sample` | `containers/sample.py` | One simulation snapshot: mesh + field values |
-| `Dataset` | `containers/dataset.py` | Ordered collection of Samples with shared ProblemDefinition |
-| `Features` | `containers/features.py` | Named tensor-like data with metadata |
-| `FeatureIdentifier` | `containers/feature_identifier.py` | Unique key to identify a feature across samples |
+| `Infos` | `infos.py` | Metadata describing a dataset/problem (legal, data production, etc.) |
+| `Sample` | `containers/sample.py` | One simulation snapshot: mesh + field values (a pydantic `BaseModel`) |
+
+`Sample`, `Infos` and `ProblemDefinition` are re-exported at the top level of the
+`plaid` package, together with the helpers `get_number_of_samples` and `get_sample_ids`
+from `containers/utils.py`.
 
 ### Storage pattern
 
 Storage uses a **Registry pattern** (`storage/registry.py`) to dispatch read/write
 operations to the correct backend (zarr, hf_datasets, cgns). Each backend implements
-a `reader.py` and `writer.py` following a common interface defined in `storage/common/`.
+a `reader.py` and `writer.py` following the backend contract defined in
+`storage/backend_api.py` and the shared interfaces in `storage/common/`.
+Reading/writing a collection of samples is done through this storage layer rather
+than through a dedicated `Dataset` class.
 
 ## Code conventions
 
@@ -182,7 +191,7 @@ uv run ruff check --fix .
 uv run ruff format .
 
 # Build documentation
-cd docs && make html
+bash docs/generate_doc.sh
 ```
 
 ## Contribution workflow

src/plaid/containers/AGENTS.md

@@ -1,28 +1,37 @@
 # AGENTS.md -- plaid/containers
 
-This module defines the core data containers of the PLAID data model.
+This module defines the core data container of the PLAID data model.
 
 ## Key classes
 
 | Class | File | Description |
 |-------|------|-------------|
-| `Dataset` | `dataset.py` | Ordered collection of `Sample` objects sharing a common `ProblemDefinition`. Main entry point for loading and manipulating simulation data. |
-| `Sample` | `sample.py` | Single simulation snapshot containing mesh coordinates and field values as `Features`. |
-| `Features` | `features.py` | Named tensor-like container with shape and dtype metadata. Wraps numpy arrays. |
-| `FeatureIdentifier` | `feature_identifier.py` | Immutable key (name + location) used to uniquely identify a feature across samples. |
-| `DefaultManager` | `managers/default_manager.py` | Manages default values and missing data for features within a dataset. |
+| `Sample` | `sample.py` | Single simulation snapshot containing mesh coordinates and field values. Implemented as a pydantic `BaseModel`. This is the main data container exposed by plaid. |
+| `DefaultManager` | `managers/default_manager.py` | Manages default values and missing data for features within a sample. |
+
+Helper functions live in `utils.py` (e.g. `get_number_of_samples`, `get_sample_ids`)
+and are re-exported at the top level of the `plaid` package.
+
+> Note: the v1.0.0 reorganization removed the `Dataset`, `Features` and
+> `FeatureIdentifier` classes. A collection of samples is now read/written through the
+> `storage` layer rather than a dedicated `Dataset` class. See `docs/source/upgrade_guide.md`.
 
 ## Design constraints
 
-- `Dataset` is a **large class** (~1800 lines). Avoid adding new responsibilities to it. Prefer extracting logic into helper functions or dedicated modules.
-- `Sample` and `Features` are **value objects** -- they should remain simple, with minimal business logic.
-- `FeatureIdentifier` is **immutable and hashable** -- it is used as dictionary keys throughout the codebase. Do not add mutable state.
-- All containers must support **serialization** through the storage backends (zarr, hf_datasets, cgns).
+- `Sample` is a **value object** built on pydantic -- keep it focused on holding mesh
+  and field data, with minimal business logic. Prefer extracting heavy logic into
+  helper functions or dedicated modules.
+- `DefaultManager` centralizes default/missing-data handling -- do not duplicate this
+  logic inside `Sample`.
+- All containers must support **serialization** through the storage backends
+  (zarr, hf_datasets, cgns).
 
 ## Downstream impact
 
-These classes are the public API surface consumed by downstream libraries and end users. Any signature change is a **breaking change** that requires a major version bump.
+`Sample` is part of the public API surface consumed by downstream libraries and end
+users. Any signature change is a **breaking change** that requires a major version bump.
 
 ## Testing
 
-Tests are in `tests/`. When modifying a container class, verify that storage round-trips (write then read) still produce identical data.
+Tests are in `tests/`. When modifying a container class, verify that storage round-trips
+(write then read) still produce identical data.

src/plaid/storage/AGENTS.md

@@ -9,6 +9,7 @@ Storage follows a **Registry pattern**:
 ```
 storage/
 ├── registry.py        <- Dispatches to the correct backend based on format
+├── backend_api.py     <- Backend contract (BackendModule Protocol)
 ├── reader.py          <- Public read API (delegates to backend readers)
 ├── writer.py          <- Public write API (delegates to backend writers)
 ├── common/            <- Abstract interfaces and shared utilities
@@ -23,15 +24,20 @@ storage/
 
 ## How it works
 
-1. The **registry** (`registry.py`) maps format identifiers to backend modules.
+1. The **registry** (`registry.py`) holds a `BACKENDS` dict mapping each format name
+   (`"cgns"`, `"hf_datasets"`, `"zarr"`) to its backend class, exposed through
+   `get_backend(name)` and `available_backends()`.
 2. The public `reader.py` and `writer.py` at the top level accept a format parameter and delegate to the appropriate backend.
-3. Each backend implements the interfaces defined in `common/reader.py` and `common/writer.py`.
+3. Each backend exposes a backend class (e.g. `ZarrBackend`, `HFBackend`, `CgnsBackend`)
+   that conforms to the `BackendModule` Protocol in `backend_api.py`, and implements the
+   read/write logic in its `reader.py` and `writer.py`.
 
 ## Adding a new backend
 
 1. Create a new subdirectory under `storage/` (e.g., `storage/my_format/`).
-2. Implement `reader.py` and `writer.py` following the interfaces in `common/`.
-3. Register the new backend in `registry.py`.
+2. Implement a backend class conforming to the `BackendModule` Protocol
+   (`backend_api.py`), with its `reader.py` and `writer.py` following the interfaces in `common/`.
+3. Register the new backend by adding it to the `BACKENDS` dict in `registry.py`.
 4. Add round-trip tests (write then read) to verify data integrity.
 
 ## Design constraints