docs: refresh README, add CHANGELOG and CLAUDE.md

Rewrite the README around the new API, add a Keep a Changelog CHANGELOG for
v1.0.0 and a CLAUDE.md contributor guide (env, tests, release flow, erddapy
caveats). Ignore dist/, site/ and .pytest_cache/.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: vinisalazar

.gitignore

@@ -6,8 +6,11 @@
 **/.DS_Store
 **/*.ini
 build/
+dist/
 pyo_oracle/data
 .coverage
 coverage.*
 htmlcov/
 .venv/
+.pytest_cache/
+site/

CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-06-02
+
+First stable release. Modernizes dependencies, reaches feature parity with the
+R package [`biooracler`](https://github.com/bio-oracle/biooracler), and adds new
+functionality.
+
+### Added
+
+- **`info_layer(dataset_id)`** — inspect a layer's dimension ranges (time,
+  latitude, longitude, depth) and its variables with units and long names
+  (parity with `biooracler::info_layer`).
+- **`load_layer(dataset_id, ...)`** — load a layer directly into memory as a
+  `pandas.DataFrame` (default) or `xarray.Dataset` (`fmt="xarray"`).
+- **`build_constraints(...)`** — build griddap constraints from friendly
+  `(min, max)` bounds and strides, with optional validation against the
+  dataset's real ranges.
+- **`variables=`** argument on `download_layers` to download a subset of
+  variables.
+- Optional dependency extras: `xarray`, `docs`, `dev`.
+- MkDocs Material documentation site (quickstart, tutorials, API reference) with
+  a GitHub Pages deploy workflow.
+- `respx` and `ruff` to the dev toolchain; `integration` pytest marker to
+  separate live-server tests from offline unit tests.
+- `CLAUDE.md` contributor guide and this changelog.
+
+### Changed
+
+- Declared explicit dependencies (`erddapy>=2.2`, `pandas>=2.0`, `httpx>=0.27`)
+  and raised the Python floor to `>=3.9`.
+- Refactored griddap server construction into a single shared
+  `_build_griddap_server` helper used by downloads, in-memory loading, and
+  metadata lookups.
+- CI now tests a Python 3.9–3.13 matrix, lints with ruff, and runs offline unit
+  tests by default with a separate (non-blocking) integration job.
+
+### Fixed
+
+- Replaced unsafe `eval()` parsing of the `skip_confirmation` config value with a
+  safe boolean coercion (`_as_bool`), which also handles strings like `"false"`.
+- Hardened handling of erddapy's private `_constraints_original` attribute.
+
+## [0.2.0]
+
+- Previous release.

CLAUDE.md

@@ -0,0 +1,77 @@
+# CLAUDE.md
+
+Guidance for working in this repository.
+
+## What this is
+
+`pyo_oracle` is the Python client for the **Bio-ORACLE** ERDDAP server
+(<https://erddap.bio-oracle.org/erddap/>). It is the Python counterpart of the R
+package [`biooracler`](https://github.com/bio-oracle/biooracler) and is built on
+top of [`erddapy`](https://github.com/ioos/erddapy).
+
+## Layout
+
+- `pyo_oracle/__init__.py` — public namespace; re-exports the API.
+- `pyo_oracle/main.py` — public functions: `list_layers`, `info_layer`,
+  `load_layer`, `download_layers`, `list_local_data`.
+- `pyo_oracle/utils.py` — internals: `_build_griddap_server` (the single shared
+  griddap setup path), `_layer_info`, `_layer_dataframe`, `build_constraints`,
+  `_as_bool`, download helpers.
+- `pyo_oracle/_config.py` — configparser-based config (data dir, server URL,
+  `skip_confirmation`). `config.ini` is generated and git-ignored.
+- `tests/` — `test_utils.py` (offline), `test_main.py` (mostly live), `test_config.py`.
+- `docs/` + `mkdocs.yml` — MkDocs Material site (mkdocstrings API ref).
+
+## Public API parity with `biooracler`
+
+`list_layers`, `info_layer`, `download_layers` mirror the R package. Python adds
+`load_layer` (in-memory pandas/xarray) and `build_constraints` (friendly
+subsetting helper).
+
+## Dev environment
+
+All development happens in the conda env named **`pyo_oracle`**:
+
+```bash
+conda env create -n pyo_oracle -f environment-dev.yaml   # or `mamba`
+conda activate pyo_oracle
+pip install -e ".[dev,xarray,docs]"
+```
+
+## Tests
+
+Two kinds, separated by the `integration` marker:
+
+```bash
+pytest -m "not integration"   # offline unit tests (fast, used in CI by default)
+pytest                        # full suite incl. tests that hit the live server
+pytest -m integration         # only the live-server tests
+```
+
+The exit goal for changes is a **fully green `pytest`** in the `pyo_oracle` env.
+
+## Lint & docs
+
+```bash
+ruff check pyo_oracle tests
+mkdocs serve          # live preview
+mkdocs build --strict # must pass (CI deploys to GitHub Pages)
+```
+
+## Release flow
+
+1. Bump `version` in `pyproject.toml` and update `CHANGELOG.md`.
+2. Ensure `pytest`, `ruff`, and `mkdocs build --strict` pass.
+3. `python -m build` and inspect the artifacts.
+4. Push a tag — `.github/workflows/pypi-publish.yml` builds and publishes to PyPI
+   (package name `pyo-oracle`).
+
+## Gotchas
+
+- **erddapy private API**: `_build_griddap_server` relies on
+  `ERDDAP._constraints_original`. It is guarded with `getattr`/`hasattr` but
+  watch this if bumping erddapy (verified against erddapy 3.2.x).
+- Requires `erddapy>=2.2`, `pandas>=2.0`, Python `>=3.9`. xarray loading needs
+  the optional `xarray` extra (`xarray` + `netCDF4`).
+- `download_layers` with no constraints downloads the entire global layer and
+  prompts for confirmation unless `skip_confirmation=True`.

README.md

@@ -1,40 +1,82 @@
 # pyo_oracle
-## Python interface for the Bio-ORACLE ERDDAP server
 
-### Quick start
+**Python client for the [Bio-ORACLE](https://bio-oracle.org/) ERDDAP server.**
 
-```python
-import pyo_oracle
-
-# List available layers in the Bio-ORACLE server
-pyo_oracle.list_layers()
-
-# Define constraints and download a layer (the full layer is a large file)
-constraints = {
-    "time>=": "2000-01-01T00:00:00Z",
-    "time<=": "2010-01-01T12:00:00Z",
-    "time_step": 100,
-    "latitude>=": 0,
-    "latitude<=": 10,
-    "latitude_step": 100,
-    "longitude>=": 0,
-    "longitude<=": 10,
-    "longitude_step": 1
-}
-pyo_oracle.download_layers("thetao_baseline_2000_2019_depthsurf", constraints=constraints)
-
-# See local data
-pyo_oracle.list_local_data()
-```
+Discover, inspect, subset, download, and load Bio-ORACLE marine environmental
+layers (temperature, salinity, nutrients, sea ice, and more) from Python.
+`pyo_oracle` is the Python counterpart of the R package
+[`biooracler`](https://github.com/bio-oracle/biooracler) and is built on
+[`erddapy`](https://github.com/ioos/erddapy).
+
+📖 **Documentation:** <https://bio-oracle.github.io/pyo_oracle/>
 
-### Installation
+## Installation
 
 ```bash
+# With pip
+pip install pyo-oracle
+
+# Load layers as xarray (optional extra)
+pip install "pyo-oracle[xarray]"
+
 # With conda
 conda create -n pyo_oracle conda-forge::pyo-oracle
+```
 
-# or with pip
-pip install pyo-oracle
+## Quick start
+
+```python
+import pyo_oracle as pyo
+
+# 1. List available layers (filter by search term, variable, scenario, depth, ...)
+pyo.list_layers(search="Temperature")
+
+# 2. Inspect a layer: dimension ranges + variables and units
+pyo.info_layer("thetao_baseline_2000_2019_depthsurf")
+
+# 3. Build constraints from friendly bounds (no hand-written dicts)
+constraints = pyo.build_constraints(
+    "thetao_baseline_2000_2019_depthsurf",
+    time=("2000-01-01T00:00:00Z", "2010-01-01T00:00:00Z"),
+    latitude=(0, 10),
+    longitude=(0, 10),
+)
+
+# 4a. Load directly into memory (pandas or xarray)
+df = pyo.load_layer(
+    "thetao_baseline_2000_2019_depthsurf",
+    constraints=constraints,
+    variables=["thetao_mean"],
+)
+ds = pyo.load_layer(
+    "thetao_baseline_2000_2019_depthsurf",
+    constraints=constraints,
+    fmt="xarray",
+)
+
+# 4b. Or download to a file (NetCDF by default)
+pyo.download_layers(
+    "thetao_baseline_2000_2019_depthsurf",
+    constraints=constraints,
+    variables=["thetao_mean"],
+)
+
+# 5. See local data
+pyo.list_local_data()
 ```
 
-Please open an issue if you experience any problems. More documentation coming soon!
+## Key functions
+
+| Function | Purpose |
+|----------|---------|
+| `list_layers` | List/filter available layers |
+| `info_layer` | Inspect a layer's dimensions and variables |
+| `build_constraints` | Build griddap constraints from `(min, max)` bounds + strides |
+| `load_layer` | Load a layer into memory (`pandas` or `xarray`) |
+| `download_layers` | Download a layer (NetCDF/CSV), optionally a variable subset |
+| `list_local_data` | List downloaded files |
+
+## Contributing
+
+See [`CLAUDE.md`](CLAUDE.md) for the dev setup, testing, and release flow.
+Please open an issue if you experience any problems.