@@ -0,0 +1,13 @@
+## Description
+
+<!-- What does this PR change, and why? -->
+
+## Related issues
+
+<!-- e.g. Fixes #123 -->
+
+## Checklist
+
+- [ ] Added tests for the new behavior or bug fix
+- [ ] Added an entry to [CHANGELOG.md](../CHANGELOG.md) under `Unreleased`
+- [ ] Updated [USERGUIDE.md](../USERGUIDE.md) / [USERGUIDE-OME-ZARR.md](../USERGUIDE-OME-ZARR.md) if the public API changed
@@ -0,0 +1,58 @@
+# AGENTS.md
+
+`zarr-java` (`dev.zarr:zarr-java`) is a Java implementation of the Zarr v2 and v3
+array storage specs, plus experimental OME-Zarr support. Public API entry points
+are `dev.zarr.zarrjava.v2.{Array,Group}` and `dev.zarr.zarrjava.v3.{Array,Group}`.
+
+- Build: Maven, compiled with `maven.compiler.release=8` (build with JDK 11).
+- Arrays are backed by `ucar.ma2.Array` (netCDF-Java).
+- Metadata is (de)serialized with Jackson.
+
+## Layout
+
+- `core/` — version-agnostic base types (`Array`, `Group`, `ArrayMetadata`,
+  `DataType`, `Attributes`), shared codecs (`core/codec`) and chunk key encodings.
+- `v2/`, `v3/` — spec-version-specific metadata, codecs and chunk grids.
+- `store/` — `Store` backends: `FilesystemStore`, `HttpStore`, `S3Store`,
+  `MemoryStore`, `ZipStore`/`ReadOnlyZipStore`/`BufferedZipStore`. Keys are
+  addressed through `StoreHandle`.
+- `experimental/ome/` — OME-Zarr (NGFF) v0.4 / v0.5 / v0.6 metadata models.
+- `cli/` — command line wrapper.
+- `utils/` — indexing helpers, notably `IndexingUtils`.
+
+## Before implementing a feature
+
+Before implementing a feature, codec, data type, or behaviour change, check whether it already
+exists or is specified elsewhere, and use that as context. Check in this order:
+
+1. **zarr-specs**: the core Zarr v2/v3 specification. Is it specified, and how exactly?
+   - https://github.com/zarr-developers/zarr-specs (rendered: https://zarr-specs.readthedocs.io)
+2. **zarr-extensions**: codecs, data types, chunk grids etc. that are not part of the core spec.
+   - Local clone: `../zarr-extensions`
+   - https://github.com/zarr-developers/zarr-extensions
+3. **zarr-python**: the reference implementation. Defines the actual behaviour (defaults, edge
+   cases, error handling) that zarr-java must match.
+   - Local clone: `../zarr-python`; the installed version is in `.venv/lib/python*/site-packages/zarr`
+   - https://github.com/zarr-developers/zarr-python
+4. **OME-Zarr (NGFF)**: for anything under `experimental/ome/`, the current OME-NGFF
+   specification is at https://ngff.openmicroscopy.org/specifications/0.6/index.html.
+
+Prefer the local clones (grep) over fetching the web. If the spec and zarr-python disagree,
+match zarr-python and mention the discrepancy. If nothing relevant is found, say so before
+designing the feature from scratch.
+
+## Conventions
+
+- IntelliJ IDEA default Java formatting; run `Reformat Code` and
+  `Optimize Imports` before submitting changes.
+- New user-visible changes go in [CHANGELOG.md](CHANGELOG.md) under `Unreleased`.
+- User-facing documentation lives in [USERGUIDE.md](USERGUIDE.md) and
+  [USERGUIDE-OME-ZARR.md](USERGUIDE-OME-ZARR.md); update them alongside API changes.
+- When writing code comments, keep them short and concise, do not reference other code or previous behavior.
+
+## Pull requests
+
+- After opening a PR, make sure to add the PR number to added changelog entries, e.g. [#103](https://github.com/zarr-developers/zarr-java/pull/103).
+- Use the PR template at .github/pull_request_template.md.
+- Keep your summaries short and to the point.
+- When adding comments or replies to PRs, always mention that Claude wrote them.
@@ -0,0 +1,149 @@
+# Changelog
+
+All notable changes to zarr-java are documented in this file.
+
+The format is loosely 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).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-09-09
+
+### Added
+
+- Support for open-ended byte ranges in `getInputStream` [#103](https://github.com/zarr-developers/zarr-java/pull/103).
+- `cast_value` codec [#83](https://github.com/zarr-developers/zarr-java/pull/83).
+- `gzip` codec for Zarr v2 arrays [#98](https://github.com/zarr-developers/zarr-java/pull/98).
+
+### Fixed
+
+- Fail loudly instead of silently on unreadable ZIP stores [#103](https://github.com/zarr-developers/zarr-java/pull/103).
+- Accept a `shuffle` value of `-1` in Zarr v2 blosc metadata [#102](https://github.com/zarr-developers/zarr-java/pull/102).
+- Logging of unknown fields in OME metadata is less severe [#75](https://github.com/zarr-developers/zarr-java/pull/75).
+
+## [0.2.0] - 2026-07-29
+
+### Added
+
+- `reshape` codec.
+
+### Changed
+
+- Removed unnecessary `resolveOutputShape` calls.
+
+## [0.1.3] - 2026-05-04
+
+### Fixed
+
+- Blosc `shuffle` handling; bumped `blosc-java`.
+- The shaded JAR is attached as a classifier instead of replacing the main artifact.
+
+## [0.1.2] - 2026-03-31
+
+### Added
+
+- Command line wrapper [#45](https://github.com/zarr-developers/zarr-java/pull/45).
+
+### Changed
+
+- `CodecBuilder` accepts a compression `level` for the gzip and zstd codecs [#69](https://github.com/zarr-developers/zarr-java/pull/69).
+- OME-Zarr follow-up improvements [#68](https://github.com/zarr-developers/zarr-java/pull/68).
+
+## [0.1.1] - 2026-03-23
+
+### Added
+
+- Experimental OME-Zarr (NGFF) support [#66](https://github.com/zarr-developers/zarr-java/pull/66).
+
+## [0.1.0] - 2026-03-05
+
+### Added
+
+- User guide and expanded documentation [#55](https://github.com/zarr-developers/zarr-java/pull/55).
+- Big-endian data types for Zarr v2 [#60](https://github.com/zarr-developers/zarr-java/pull/60).
+- Retries for HTTP requests [#62](https://github.com/zarr-developers/zarr-java/pull/62).
+- Parallel decoding in `ShardingIndexedCodec` [#61](https://github.com/zarr-developers/zarr-java/pull/61).
+- Chunk data is deleted when an array is resized, plus additional tests [#49](https://github.com/zarr-developers/zarr-java/pull/49).
+
+### Changed
+
+- `Array.read` takes `long` shape arguments and store requests are validated [#54](https://github.com/zarr-developers/zarr-java/pull/54).
+- Replaced a `ByteBuffer.array()` call [#58](https://github.com/zarr-developers/zarr-java/pull/58).
+
+### Fixed
+
+- Race condition in `ShardingIndexedCodec` during parallel encoding [#61](https://github.com/zarr-developers/zarr-java/pull/61).
+- Removed an unnecessary double store read in sharding [#57](https://github.com/zarr-developers/zarr-java/pull/57).
+- `zstd` in combination with sharding [#56](https://github.com/zarr-developers/zarr-java/pull/56).
+
+## [0.0.10] - 2026-01-30
+
+### Added
+
+- `ZipStore` [#37](https://github.com/zarr-developers/zarr-java/pull/37).
+- `MemoryStore` [#36](https://github.com/zarr-developers/zarr-java/pull/36).
+- Default chunk shape calculation for v2 and v3 arrays [#50](https://github.com/zarr-developers/zarr-java/pull/50).
+
+### Fixed
+
+- `IndexingUtils.computeProjection` [#48](https://github.com/zarr-developers/zarr-java/pull/48).
+- A missing `configuration` key for `chunkKeyEncoding` is accepted [#42](https://github.com/zarr-developers/zarr-java/pull/42).
+
+## 0.0.6 – 0.0.9 - 2025-12-04
+
+Release-process fixes only; no library changes.
+
+## [0.0.5] - 2025-11-22
+
+### Added
+
+- Zarr v2 core features: arrays, groups and attributes [#22](https://github.com/zarr-developers/zarr-java/pull/22), [#25](https://github.com/zarr-developers/zarr-java/pull/25), [#28](https://github.com/zarr-developers/zarr-java/pull/28).
+- Support for arrays smaller than their chunk size [#9](https://github.com/zarr-developers/zarr-java/pull/9).
+- `storageTransformers` metadata attribute; array creation fails on non-empty storage transformers.
+- Reading a missing chunk returns a chunk filled with the fill value.
+
+### Changed
+
+- Dependency version updates [#26](https://github.com/zarr-developers/zarr-java/pull/26).
+- Clearer exception when requested data lies outside the array's domain.
+
+### Fixed
+
+- Codecs without a `configuration` entry [#34](https://github.com/zarr-developers/zarr-java/pull/34).
+- `S3Store.exists` catches `NoSuchKeyException` [#31](https://github.com/zarr-developers/zarr-java/pull/31).
+
+## [0.0.4] - 2024-08-22
+
+Version bump only.
+
+## [0.0.3] - 2024-08-15
+
+### Added
+
+- Validation of sharding bounds and chunk bounds during metadata creation.
+
+## [0.0.2] - 2024-07-04
+
+### Changed
+
+- Artifacts are published to Maven Central; sources are compiled with JDK 11
+  targeting Java 8.
+- The blosc dependency is pulled from Maven instead of being downloaded manually.
+
+## [0.0.1] - 2024-07-04
+
+Initial release with Zarr v3 support.
+
+[Unreleased]: https://github.com/zarr-developers/zarr-java/compare/0.3.0...HEAD
+[0.3.0]: https://github.com/zarr-developers/zarr-java/compare/0.2.0...0.3.0
+[0.2.0]: https://github.com/zarr-developers/zarr-java/compare/0.1.3...0.2.0
+[0.1.3]: https://github.com/zarr-developers/zarr-java/compare/0.1.2...0.1.3
+[0.1.2]: https://github.com/zarr-developers/zarr-java/compare/0.1.1...0.1.2
+[0.1.1]: https://github.com/zarr-developers/zarr-java/compare/0.1.0...0.1.1
+[0.1.0]: https://github.com/zarr-developers/zarr-java/compare/0.0.10...0.1.0
+[0.0.10]: https://github.com/zarr-developers/zarr-java/compare/0.0.9...0.0.10
+[0.0.5]: https://github.com/zarr-developers/zarr-java/compare/0.0.4...0.0.5
+[0.0.4]: https://github.com/zarr-developers/zarr-java/compare/0.0.3...0.0.4
+[0.0.3]: https://github.com/zarr-developers/zarr-java/compare/0.0.2...0.0.3
+[0.0.2]: https://github.com/zarr-developers/zarr-java/compare/0.0.1...0.0.2
+[0.0.1]: https://github.com/zarr-developers/zarr-java/releases/tag/0.0.1
@@ -0,0 +1 @@
+@AGENTS.md