diff --git a/packages/zarr-metadata/README.md b/packages/zarr-metadata/README.md
index a01ed26842..4b3c1293fe 100644
--- a/packages/zarr-metadata/README.md
+++ b/packages/zarr-metadata/README.md
@@ -2,410 +2,44 @@
 
 Documentation: <https://zarr-metadata.readthedocs.io/>
 
-Basic tools for modelling Zarr metadata, with minimal dependencies.
+Types, models and validators for Zarr metadata documents, with minimal
+dependencies.
 
 `zarr-metadata` is developed in the
 [zarr-python repository](https://github.com/zarr-developers/zarr-python/tree/main/packages/zarr-metadata)
-and released independently of `zarr` itself. Install it with:
+and released independently of `zarr`. Install it with:
 
 ```
 pip install zarr-metadata
 ```
 
-## Who needs this
-
-This library supports software that interacts with Zarr metadata documents.
-
 ## What this is
 
-This is *not* a full Zarr implementation. It's a collection of data structures and routines that
-closely model the content of the Zarr specifications, such as:
-
-- **Typed JSON shapes** ([`zarr_metadata.v2`](https://zarr-metadata.readthedocs.io/en/latest/api/v2/) and
-  [`zarr_metadata.v3`](https://zarr-metadata.readthedocs.io/en/latest/api/v3/)): `TypedDict` definitions and
-  `Literal` aliases for the JSON documents specified by the
-  [Zarr v2](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html) and
-  [Zarr v3](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html)
-  specifications, plus types for
-  [zarr-extensions](https://github.com/zarr-developers/zarr-extensions/) and a
-  few widely-used-but-unspecified entities (e.g. consolidated metadata).
-- **Document models** ([`zarr_metadata.model`](https://zarr-metadata.readthedocs.io/en/latest/api/model/)): immutable
-  models of whole metadata documents, each one a document and the scope
-  it was read in, with readers that report every problem at its
-  location, and store-key (de)serialization. A document
-  produced by `to_json` shares no mutable state with the model that produced
-  it.
-- **Definitions and scopes** ([`zarr_metadata.definition`](https://zarr-metadata.readthedocs.io/en/latest/api/definition/),
-  with each format's kinds in `zarr_metadata.v3.definition` and
-  `zarr_metadata.v2.definition`): each extension's configuration as a
-  `TypedDict` with its rules, and the scope that decides which definitions
-  read a document. `zarr_metadata.v3` and `zarr_metadata.v2` export every
-  definition and scope of their format, such as `BYTES_CODEC` and
-  `CORE_AND_EXTENSIONS_CONTEXT`.
-- **JSON type checking** ([`zarr_metadata.typed_json`](https://zarr-metadata.readthedocs.io/en/latest/api/typed_json/)):
-  `check` checks a JSON value against any `TypedDict` and reports every
-  problem with its location.
-- **Problems** ([`zarr_metadata.problems`](https://zarr-metadata.readthedocs.io/en/latest/api/problems/)): the problem
-  values every reader returns, and the error that carries them.
-- **JSON Schema** ([`zarr_metadata.json_schema`](https://zarr-metadata.readthedocs.io/en/latest/api/json_schema/)): the
-  JSON Schema of a `TypedDict`, a v3 declaration, or a whole `zarr.json`.
-- **Optional Pydantic integration** ([`zarr_metadata.pydantic`](https://zarr-metadata.readthedocs.io/en/latest/api/pydantic/),
-  requires Pydantic 2.13 or newer): each model as a Pydantic field type that
-  validates raw documents through the same strict parser.
-
-## What this is for
-
-- **Static Type Checking** The public `TypedDict` definitions describe the static JSON shape of Zarr
-  metadata.
-
-- **Dynamic JSON validation** For strict, loc-aware validation of JSON loaded from disk, use the
-  model parser:
-
-  ```python test="true" session="readme"
-  import json
-  from zarr_metadata.model import ZarrV3ArrayMetadata
-
-  with open("zarr.json", "rb") as f:
-      raw = json.load(f)
-
-  metadata = ZarrV3ArrayMetadata.from_json(raw)
-  ```
-
-  The optional Pydantic integration delegates raw input to the same strict
-  parser and returns the same normalized model class:
-
-  ```python test="true" session="readme"
-  from pydantic import TypeAdapter
-  import zarr_metadata.pydantic as zmp
-
-  adapter: TypeAdapter[zmp.ZarrV3ArrayMetadataField] = TypeAdapter(zmp.ZarrV3ArrayMetadataField)
-  metadata = adapter.validate_python(raw)
-  encoded = metadata.to_key_value()["zarr.json"]
-  ```
-
-  A field annotated `Annotated[ZarrV3ArrayMetadata, zmp.InScope(CONTEXT)]`
-  is read in `CONTEXT`, whatever the validation context holds, and a model
-  instance given to it is read again in `CONTEXT`.
-
-  Note that a bare `TypeAdapter` over a public `TypedDict` is a **coercive** shape
-  adapter, not a Zarr conformance validator; it may coerce values or discard
-  members that the strict model parser rejects. This is better suited for handling input provided
-  from Python objects (e.g., user-authored dicts) than JSON.
-
-## Validation boundary
-
-The readers and model constructors enforce the declared document structure and a small set
-of context-free consistency rules, e.g.:
-- fixed format literals,
-- finite JSON numbers outside `attributes` and the members nothing in scope reads
-- non-negative dimensions
-- one `dimension_names` entry per array dimension.
-
-In a v3 document, validation also checks each extension point: the data
-type, the chunk grid, the chunk key encoding, each codec, and each storage
-transformer. Each one is checked by the definition that claims its name in
-a scope. The scope is `CORE_AND_EXTENSIONS_CONTEXT` unless a `context` is passed.
-`ZARR_PYTHON_CONTEXT` adds the data types that zarr-python writes but no
-specification registers.
-If the definition rejects a configuration, the reader rejects it too,
-and a configuration key the definition does not declare is reported as
-`unknown_key`. If no definition in the scope claims a name, the reader
-does not check that extension point, and the consumer decides whether to
-support it.
-
-Some checks relate one part of a v3 document to another:
-
-- The fill value is checked against the data type the document names, by
-  that data type's definition.
-- The chunk grid is checked against the shape, by the grid's definition.
-- The codecs are checked as a pipeline. In order, each codec's definition
-  checks the codec against the chunk it receives. This includes a shard's
-  inner codecs and index codecs.
-
-The readers do no arithmetic on values. For example, they do not check
-whether a fill value survives a `cast_value` round trip.
-
-Some choices that the spec text leaves open, or answers in two ways:
-
-- **`attributes` may hold `NaN`, `Infinity` and `-Infinity`.** The spec
-  does not interpret attributes, and zarr-python and xarray write these
-  numbers there (for example, a CF `_FillValue`). The models read them,
-  and `to_key_value` writes them back as bare tokens, which a strict JSON
-  parser rejects. So may a member the spec does not define when no
-  definition in scope claims it: nothing reads it, so it is kept as
-  written. `check`, from `zarr_metadata.typed_json`, rejects a non-finite
-  number anywhere, including in attributes.
-- **A reader walks at most 256 levels of nesting.** A value nested deeper
-  is an `invalid_value` problem at the first level past the limit,
-  wherever it is. Every reader, writer and comparison uses one stack
-  frame per level, and `copy.deepcopy` (and `pickle` before Python 3.12)
-  uses two. A document at the limit therefore uses about half of the
-  interpreter's default recursion limit, and the rest is left for the
-  caller.
-- **`consolidated_metadata: null` is a problem.** A zarr-python 3.0.x bug
-  wrote it. The spec requires an object, and the package accepts only an
-  object. A reader of those stores removes the key before reading.
-- **An extension name must follow the spec's naming rule**,
-  `^[a-z][a-z0-9-_.]+$`, or be a URI, which earlier versions of the spec
-  required. Any other name is rejected before any definition is
-  consulted, so `""` and `"foo/bar"` are problems, not unknown extensions.
-- **`must_understand: false` is rejected at every extension point**,
-  including codecs and storage transformers, although the core spec names
-  only the data type, chunk grid and chunk key encoding. A reader that
-  skips a codec reads wrong bytes, just as a reader that skips a data type
-  reads wrong values. On an unknown top-level member, `must_understand`
-  keeps its meaning: a reader can skip that member.
-- **A v2 datetime or timedelta dtype must have a unit**, as in `<M8[ns]`,
-  because the v2 spec requires the unit in brackets. zarr-python 3 writes
-  `<M8` or `<m8` for a NumPy `datetime64` or `timedelta64` with no unit,
-  and the package refuses those dtypes. A codec's dtype parameter, such as
-  the `dtype` of a `delta` filter, may leave out the unit, because
-  numcodecs writes it that way and runs it.
-- **A v2 codec's dtype parameter is checked against the core v2 data
-  types**, whatever scope the array is read in, because numcodecs reads
-  the parameter with NumPy. So a scope that widens a data type, for
-  example to read `<f16`, does not widen what a codec's dtype parameter
-  may be.
-
-A v3 `regular` chunk grid's chunk lengths must be at least 1, even along a
-dimension of length 0. The regular grid spec says "Chunk sizes must be
-greater than zero". The core spec's wording, "non-zero when the
-corresponding dimensions of the arrays have non-zero length", requires
-less, but does not explicitly allow anything more. So a document with a
-chunk length of 0, which zarr-python 3.0 and 3.1 wrote for an empty
-dimension, is rejected.
+A collection of data structures and routines that closely model the
+metadata rules in the Zarr v2 and v3 specifications and in zarr-extensions:
+`TypedDict` shapes for every document and configuration, immutable
+document models whose readers report every problem at its location, and
+**contexts**, which say exactly which codecs, data types and other
+extensions a program reads.
 
-The readers are strict, so a document that a known writer bug made
-invalid has problems. The repair readers in `zarr_metadata.model`
-(`read_repaired_node_metadata_v3`, `read_repaired_node_metadata_v2` and
-`read_repaired_consolidated_metadata_v2`) undo these bugs first, then
-read the result strictly, and return each change they made as a `Repair`:
-
-- A chunk length of 0 in a v3 `regular` chunk grid, along an empty
-  dimension, which zarr-python 3.0 and 3.1 wrote, is written as 1.
-- `consolidated_metadata: null` on a v3 group, which zarr-python 3.0 and
-  3.1 wrote, is removed.
-- The `consolidated_metadata` member that zarr-python 3 writes into each
-  `.zgroup` entry of a `.zmetadata` below the root is removed.
-- A non-finite v2 fill value that zarr-python 3.0.0 to 3.0.6 wrote as a
-  bare `NaN`, `Infinity` or `-Infinity` is written as the string the v2
-  spec uses, such as `"NaN"`.
-- A non-finite float or complex fill value in a v3 group's consolidated
-  metadata, which zarr-python 3.0.0 to 3.0.6 wrote as a bare token, is
-  written as the string the v3 spec uses, such as `"NaN"`.
-
-The repair readers do not undo these known writer bugs, so a document
-with one of them is refused:
-
-- zarr-python 3.0.7 to 3.0.10 wrote the fill value of an `S` or `V`
-  array in a `.zmetadata` entry as a JSON array of byte values. The
-  array's own `.zarray` file holds the base64 string that the package
-  reads.
-- zarr-python 3.0.7 and 3.0.8 wrote the fill value of a v2 datetime
-  array as an ISO 8601 string, not as a count of ticks.
-- zarr-python 3.0 and 3.1 wrote a chunk length of 0 in a v3 `regular`
-  chunk grid along a dimension that is not empty, for an explicit chunk
-  length of 0.
-- Some releases of zarr-python from 3.0 to 3.2 wrote a chunk length of
-  `true` in a v3 `regular` chunk grid for `chunks=True`, and some
-  releases of 3.0 and 3.1 wrote `false` for `chunks=False`.
-
-`read_array_metadata_v3` reads a document once and returns everything the
-read found:
-
-- each declaration as the scope read it: an `AcceptedDeclaration` when a definition
-  claims its name, an `UnclaimedDeclaration` when none does, or a
-  `RefusedDeclaration`, together with the declaration's location and the kind it was
-  read as;
-- each codec, with the chunk it receives;
-- every problem;
-- the model, when there are no problems.
-
-`from_json` returns that model, or raises the problems. A consumer can
-apply its own policy by walking the declarations, without reading anything
-twice. `with_problems` pairs each declaration with its problems: those located
-in the declaration and in the declarations it contains. This matches how zod's
-`flattenError` groups issues. `canonical_of` returns the simplest
-spelling of a declaration that has no problems, without reading it again. For
-example, the code below finds the declarations that go beyond the core spec (a
-declaration with no name is already a problem), and the simplest spelling of
-each declaration:
-
-```python test="true" session="readme"
-from zarr_metadata.model import read_array_metadata_v3
-from zarr_metadata.definition import canonical_of, with_problems
-from zarr_metadata.v3.definition import CORE_CONTEXT
-
-reading = read_array_metadata_v3(raw)
-beyond_core = [
-    loc
-    for loc, declaration in reading.declarations()
-    if declaration.name is not None
-    and CORE_CONTEXT.claimant(declaration.read_as, declaration.name) is None
-]
-simplest = {
-    loc: canonical_of(declaration, problems)
-    for loc, declaration, problems in with_problems(reading.declarations(), reading.problems)
-}
-metadata = reading.metadata  # None when reading.problems is not empty
-```
-
-`read_group_metadata_v3` reads a group the same way. It checks the
-envelope of the group's `consolidated_metadata`, and does not read the
-documents the member lists (see below). `read_node_metadata_v3` reads
-a `zarr.json` of either kind as the node type its `node_type` names, the
-same way a discriminated union uses its tag. A document whose `node_type`
-is neither reads as `ZarrV3UnknownNodeMetadataReading`, with the problems.
-Only its `zarr_format` is read, so a document of another format is
-reported as not v3. `node_metadata_from_json_v3` and
-`node_metadata_from_key_value_v3` build the model of either kind, the same
-way the models' own `from_json` and `from_key_value` build one.
-
-Consolidated metadata holds the hierarchy below its group, with the group
-as the root. The document of the node at `/a/b` is stored under the key
-`a/b`. The documents and the group must form a tree: only groups have
-child nodes, and the parent of every node is present.
-`ZarrV3ConsolidatedMetadata` checks this when it reads the documents. `NodeName` and
-`NodePath`, in `zarr_metadata.v3`, are the types of strings that satisfy
-the spec's rules for node names and paths. They are modeled on the zarrs
-types with the same names. `validate_node_name_v3`, `is_node_name_v3` and
-`parse_node_name_v3`, and the matching `node_path` functions, check a
-string against those rules.
-
-A top-level member that the spec does not define is an extra field. A
-scope can hold a definition for one, by its key, in the
-`array_extra_fields` or `group_extra_fields` slot of `ZarrV3Context`. A
-member whose key a definition claims is read by that definition: an extra field is a declaration
-written as the member alone, `{key: value}`. Any other extra field is kept as
-written, as an `UnclaimedDeclaration`.
-The scope is what a reader recognizes, so the model's
-`must_understand_fields` lists each unclaimed member that does not say
-`"must_understand": false`: the spec requires a reader to fail to open a
-node with any such member. It covers extra fields only. A data type, chunk
-grid, chunk key encoding, codec or storage transformer that nothing in
-scope claims is an `UnclaimedDeclaration` too, also when it sits inside another
-declaration, such as a codec inside a shard. A model's `unclaimed_declarations` lists
-every declaration nothing in scope claims, at any depth, by its location, and
-leaves out the members that waive `must_understand`: a reader can open
-the node when it is empty. `CORE_CONTEXT` holds
-`CONSOLIDATED_METADATA_EXTRA_FIELD`, which reads a group's
-`consolidated_metadata` as the envelope the spec fixes. A group's
-`consolidated()` reads the documents that member lists, in the group's
-own scope.
-
-A v3 model consists of its document and the scope it was read in.
-`ZarrV3ArrayMetadata(document, context=None)` reads the document in the
-scope (`CORE_AND_EXTENSIONS_CONTEXT` when none is given) and raises
-`MetadataValidationError` with every problem, so an invalid model is never
-built. `to_json` returns the document as it was written, and
-`to_key_value` writes that same document to store bytes.
-
-Every typed attribute is a view of that read: each declaration as the scope read
-it (an `AcceptedDeclaration` or an `UnclaimedDeclaration`), and `shape`, `attributes`
-and the members that hold no declaration as the read refined them. These views are read-only
-at every level: a list in the document is shown as a tuple, and an object
-as a read-only mapping. `to_json` returns plain containers.
-
-To change a model, call `update`. It replaces members of the document with
-the given JSON members and reads the result in the model's own scope, so
-you do not pass the scope again. A member the spec defines is given by its
-name, and any other member in `extra_fields`, a mapping from its key to its
-value, or to `UNSET` to remove it. A name `update` does not take raises
-`TypeError`, so a misspelled member is never written. `with_context` reads the document in
-another scope. `refined_in` also reads the document in another scope, but
-only one that claims what this scope left unclaimed and contradicts
-nothing; otherwise it raises `ScopeConflictError`.
-
-A group does not read the documents its `consolidated_metadata` lists.
-Consolidated metadata is a convention of the reference implementation,
-not core metadata, so a group holds the member as written, after it
-checks the envelope that the core spec fixes. A reader can use the
-member as a source of child documents in place of the store: read one
-document with `read_node_metadata_v3` when that node is opened, or read
-all of them with `ZarrV3ConsolidatedMetadata`, or with
-`read_consolidated_metadata_v3`, which returns problems instead of
-raising them. A document with a problem then fails only when it is read.
-Pass `context=group.context` to read the documents in the group's own
-scope; with no `context`, they are read in `CORE_AND_EXTENSIONS_CONTEXT`.
-
-To write consolidated metadata, build a `ZarrV3ConsolidatedMetadata` and
-pass it to the group's `update`. The group reads the listed models in its
-own scope, refuses one that its scope reads differently, and writes the
-document. The model reads every document strictly, and also accepts node
-models as entries. Such an entry is accepted when its claims refine into
-the model's scope, and refused at its path otherwise. To consolidate
-children that were read in several scopes, consolidate them in the
-`union` of those scopes. Every reader takes `context=None` for the
-default scope, `CORE_AND_EXTENSIONS_CONTEXT`.
-
-Two models are equal when they represent the same document, even if each
-is spelled differently. Values the package interprets (each declaration, and the
-fill value against its data type) are compared by their canonical
-spelling, as returned by `canonical_of` and `canonical_fill_value`. For
-example, `"NaN"` and `"0x7fc00000"` are the same `float32` fill value,
-`0.0` and `-0.0` are two different fill values, and a v3 blosc codec
-under `noshuffle`, which ignores `typesize`, is the same codec with or
-without one. A v2
-document's dtype, codecs and fill value are compared the same way: `<b1`
-and `|b1` are one dtype, in `dtype` and in a codec's dtype parameter
-alike, and a v2 codec that leaves out a parameter is
-the same as one that writes the numcodecs default, so
-`{"id": "zstd", "level": 0}` equals
-`{"id": "zstd", "level": 0, "checksum": false}`. A v2 blosc `typesize`
-is kept whatever the `shuffle`, unlike in v3: v2 codecs are defined by
-numcodecs, which writes it into each chunk's header, so two v2 blosc
-codecs that differ only in it encode different bytes, though they decode
-the same data. The v3 spec defines its blosc codec, and says `noshuffle`
-ignores `typesize`. A v2 node with no `.zattrs` equals one with an
-empty `.zattrs`, as a v3 document with and without an empty
-`attributes` are equal. Values the package does
-not interpret (attributes, extra fields, and the configuration of a declaration
-that nothing in the scope claims) are compared as JSON text. JSON text
-distinguishes `true` from `1` and `-0.0` from `0.0`, and treats `NaN` as
-equal to itself. Equal models have equal hashes, but may write different
-documents, because `to_json` writes each document as it was given. A
-model holds nothing that can be changed in place.
-
-`node_metadata_json_schema_v3` writes the rules the readers apply as a
-JSON Schema (draft 2020-12). Use it in an editor that checks a `zarr.json`
-while you write it, or with a validator in another language. Each
-extension point is described as a declaration as its scope reads it: a claimed
-configuration follows its definition's TypedDict, including bounds, and a
-name that nothing in the scope claims may have any configuration. The fill
-value must be a valid fill value for the data type the document names.
-`declaration_json_schema_v3(kind, *, context=None)` writes the schema of one declaration, and
-`json_schema` writes the schema of any TypedDict as `check` reads it. All
-three are in `zarr_metadata.json_schema`. A schema describes each member on its own, not the rules that
-relate members to each other, so a document the schema accepts may still
-have a problem. Every JSON document the readers accept, the schema also
-accepts. A schema validator reads JSON as a parser produces it, with
-arrays as lists. A model's `to_json` returns tuples, which a Python
-validator does not accept as arrays.
+This is *not* a full Zarr implementation. Nothing here reads or writes
+chunks, encodes or decodes data, or performs store I/O.
 
 ```python test="true" session="readme"
 import json
-from zarr_metadata.json_schema import node_metadata_json_schema_v3
+from zarr_metadata import ZarrV3ArrayMetadata
 
-with open("zarr.schema.json", "w") as f:
-    json.dump(node_metadata_json_schema_v3(), f, indent=2)
-```
+with open("zarr.json", "rb") as f:
+    raw = json.load(f)
 
-## Scope
-
-At minimum, this library supports what Zarr-Python needs: the complete
-Zarr v2 and v3 specs, consolidated metadata, and a subset of the metadata
-defined in `zarr-extensions`. We are generally open to contributions that
-add types, models, or validation for Zarr metadata with a
-published spec.
+metadata = ZarrV3ArrayMetadata.from_json(raw)
+```
 
-Runtime array behavior is out of scope: nothing here encodes or decodes
-chunks, resolves codec or data type names to implementations, or performs
-store I/O. The models begin and end at the metadata documents themselves —
-`from_key_value` / `to_key_value` map documents to store keys and bytes,
-and everything past that belongs to consumer libraries.
+`from_json` returns the model, or raises `MetadataValidationError` with
+every problem it found. The
+[documentation](https://zarr-metadata.readthedocs.io/) has a guide for
+each kind of use, and the API reference.
 
-## Reference
+## License
 
-- [API reference](https://zarr-metadata.readthedocs.io/en/latest/api/)
-- [Release notes](https://zarr-metadata.readthedocs.io/en/latest/release-notes/)
-- [License (MIT)](https://github.com/zarr-developers/zarr-python/blob/main/packages/zarr-metadata/LICENSE.txt)
+[MIT](https://github.com/zarr-developers/zarr-python/blob/main/packages/zarr-metadata/LICENSE.txt)
diff --git a/packages/zarr-metadata/changes/434.doc.md b/packages/zarr-metadata/changes/434.doc.md
new file mode 100644
index 0000000000..65a09f4e1f
--- /dev/null
+++ b/packages/zarr-metadata/changes/434.doc.md
@@ -0,0 +1 @@
+The documentation now has a short landing page that points each kind of reader to a guide page, instead of one long page. New guide pages cover models and readers, the rules the readers check, consolidated metadata, repairing known writer bugs, writing an extension, JSON Schema and Pydantic. Each claim the pages make about a Zarr specification links to the section of the spec that makes it, and the consolidated metadata page says what the specs do and do not settle, with links to the zarr-specs pull requests and issues and to the original zarr-python implementation. The pages say "context" for a `Context` where some said "scope".
diff --git a/packages/zarr-metadata/docs/api/index.md b/packages/zarr-metadata/docs/api/index.md
index a3e7be2665..fae1f6fd03 100644
--- a/packages/zarr-metadata/docs/api/index.md
+++ b/packages/zarr-metadata/docs/api/index.md
@@ -9,7 +9,7 @@ The package is organized to mirror the structure of the Zarr specifications:
 - [`zarr_metadata.json_schema`](json_schema.md) — JSON Schema output for
   any `TypedDict`, one v3 declaration, or a whole v3 `zarr.json`
 - [`zarr_metadata.model`](model.md) — document models (each one a
-  document and the scope it was read in), the readers that return
+  document and the context it was read in), the readers that return
   problems instead of raising them, and the `UNSET` sentinel
 - [`zarr_metadata.problems`](problems.md) — `ValidationProblem`,
   `ProblemKind`, `Problems` and `MetadataValidationError`, which every
@@ -21,7 +21,7 @@ The package is organized to mirror the structure of the Zarr specifications:
   typing spec defines them, with every problem located
 - [`zarr_metadata.v2`](v2.md) — `TypedDict` shapes for Zarr v2 documents
   (`.zarray`, `.zgroup`, `.zattrs`, `.zmetadata`), and
-  `zarr_metadata.v2.definition`: the v2 kinds of metadata, the scope
+  `zarr_metadata.v2.definition`: the v2 kinds of metadata, the context
   `CORE_V2_CONTEXT`, and the readers of one `dtype` or codec. Each dtype family's
   definition is in `zarr_metadata.v2.data_type`, and each codec's in
   `zarr_metadata.v2.codec`
@@ -32,10 +32,11 @@ The package is organized to mirror the structure of the Zarr specifications:
 - [`zarr_metadata.definition`](definition.md) — what both formats share
   for reading a declaration: `Definition`, `resolve`, the three results of a
   reading (`AcceptedDeclaration`, `UnclaimedDeclaration`, `RefusedDeclaration`), and the
-  scope type `Context`. Its module docstring is the guide
+  context type `Context`. Its module docstring is the guide
 - [`zarr_metadata.v3.definition`](v3/definition.md) — the five v3 kinds
   of metadata (`CodecDefinition`, `DataTypeDefinition`, ...), the codec
-  pipeline types, and the v3 scopes `CORE_CONTEXT` and `CORE_AND_EXTENSIONS_CONTEXT`
+  pipeline types, and the v3 contexts `CORE_CONTEXT`,
+  `CORE_AND_EXTENSIONS_CONTEXT` and `ZARR_PYTHON_CONTEXT`
 
 The document types, models, and spec vocabulary — including the store keys —
 are re-exported at the top level, so
diff --git a/packages/zarr-metadata/docs/consolidated-metadata.md b/packages/zarr-metadata/docs/consolidated-metadata.md
new file mode 100644
index 0000000000..e7e10d3d96
--- /dev/null
+++ b/packages/zarr-metadata/docs/consolidated-metadata.md
@@ -0,0 +1,95 @@
+# Consolidated metadata
+
+Consolidated metadata is a copy of every metadata document below a group,
+kept in one place so that a reader can open a hierarchy with one read. It
+is a convention of zarr-python, the reference implementation, and neither
+Zarr specification defines it in full. This page says what is settled
+before it describes the API.
+
+## Status in the specifications
+
+- **Zarr v2.** The v2 spec has no consolidated metadata. The `.zmetadata`
+  file was designed and shipped in zarr-python
+  [PR 268](https://github.com/zarr-developers/zarr-python/pull/268), merged in November 2018 and released in
+  zarr-python 2.3.0, and is described in the
+  [zarr-python 2 tutorial](https://zarr.readthedocs.io/en/v2.18.3/tutorial.html#consolidating-metadata).
+  zarr-specs [issue 113](https://github.com/zarr-developers/zarr-specs/issues/113), on standardizing the
+  format, is open.
+- **Zarr v3.** zarr-specs [PR 309](https://github.com/zarr-developers/zarr-specs/pull/309), open since
+  August 2024 and following [issue 136](https://github.com/zarr-developers/zarr-specs/issues/136), proposes the
+  `consolidated_metadata` member with the `kind: "inline"` envelope that
+  zarr-python 3 writes. It is not merged. The core spec does not define the
+  member's entries. Since [PR 373](https://github.com/zarr-developers/zarr-specs/pull/373), merged in July 2026,
+  it names the member "for historical reasons" and fixes its envelope: an
+  object with `must_understand: false`, `kind: "inline"` and a `metadata`
+  object ([spec text](https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L802-L816)). That change closed
+  [issue 371](https://github.com/zarr-developers/zarr-specs/issues/371), which found that the v3.1.0 extension
+  rules, read strictly, put every consolidated group zarr-python 3 had
+  written out of spec, because the envelope has no `name`.
+
+This package reads the envelope the spec fixes, and the entries as
+zarr-python writes them.
+
+## Zarr v3
+
+Consolidated metadata holds the hierarchy below its group, with the group
+as the root. The document of the node at `/a/b` is stored under the key
+`a/b`, as the [stored representation](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#stored-representation) strips
+the leading `/` of a path. The documents and the group must form a tree:
+only groups have child nodes, and the parent of every node is present.
+`ZarrV3ConsolidatedMetadata` checks this when it reads the documents.
+
+`NodeName` and `NodePath`, in `zarr_metadata.v3`, are the types of strings
+that satisfy the spec's rules for [node names](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#node-names) and
+paths. They are modeled on the zarrs types with the same names.
+`validate_node_name_v3`, `is_node_name_v3` and `parse_node_name_v3`, and
+the matching `node_path` functions, check a string against those rules.
+
+### Reading
+
+A group does not read the documents its `consolidated_metadata` lists.
+Consolidated metadata is a convention of the reference implementation, not
+core metadata, so a group holds the member as written, after it checks the
+[envelope that the core spec fixes](https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L802-L816). `CORE_CONTEXT` holds
+`CONSOLIDATED_METADATA_EXTRA_FIELD`, the definition that reads a group's
+`consolidated_metadata` as that envelope.
+
+A reader can use the member as a source of child documents in place of the
+store: read one document with `read_node_metadata_v3` when that node is
+opened, or read all of them with the group's `consolidated()`, with
+`ZarrV3ConsolidatedMetadata`, or with `read_consolidated_metadata_v3`,
+which returns problems instead of raising them. A document with a problem
+then fails only when it is read. `consolidated()` reads the documents in
+the group's own context. The other three take a `context`; pass
+`context=group.context` to read the documents in the group's own context,
+and with no `context` they are read in `CORE_AND_EXTENSIONS_CONTEXT`.
+
+### Writing
+
+To write consolidated metadata, build a `ZarrV3ConsolidatedMetadata` and
+pass it to the group's `update`. The group reads the listed models in its
+own context, refuses one that its context reads differently, and writes the
+document. The model reads every document strictly, and also accepts node
+models as entries. Such an entry is accepted when its claims refine into
+the model's context, and refused at its path otherwise. To consolidate
+children that were read in several contexts, consolidate them in the
+`union` of those contexts.
+
+## Zarr v2
+
+A v2 hierarchy's consolidated metadata is the `.zmetadata` document at the
+root of the store, as zarr-python 2.3 and later write it: an object with
+`zarr_consolidated_format: 1` and a `metadata` object that maps each
+metadata file's path to that file's contents, under keys such as
+`a/.zarray`, `a/.zattrs` and `a/b/.zgroup`. The format comes from
+zarr-python [PR 268](https://github.com/zarr-developers/zarr-python/pull/268); no specification defines it.
+
+`ZarrV2ConsolidatedMetadata` reads such a document, and
+`read_consolidated_metadata_v2` returns problems instead of raising them.
+Both take a `context`, `CORE_V2_CONTEXT` when none is given. Each `.zarray` or
+`.zgroup` entry is read as a node, merged with its sibling `.zattrs`. A
+`.zattrs` with no sibling is kept but forms no node, and any other entry
+must be JSON and is kept. `to_json` returns the entries keyed by file, as
+written. The `.zmetadata` that zarr-python 3 writes for a v2 hierarchy has
+a known bug, which `read_repaired_consolidated_metadata_v2` undoes; see
+[Repairing known writer bugs](repair.md).
diff --git a/packages/zarr-metadata/docs/context.md b/packages/zarr-metadata/docs/context.md
index 38a51dd12b..f759416428 100644
--- a/packages/zarr-metadata/docs/context.md
+++ b/packages/zarr-metadata/docs/context.md
@@ -4,7 +4,7 @@ Resolving metadata documents requires a context, a `Context`, that defines which
 
 ## Why do we need a context
 
-The Zarr V3 spec defines the JSON structure of `zarr.json` for arrays and groups exactly, by defining the fields that must be present and the JSON types they must have. But the __interpretation__ of those fields as actual data types, codecs, chunk grids, etc is not strictly defined by the spec. Relating a JSON value like `"bytes"` to the `bytes` codec requires a mapping from names to codec types.
+The Zarr V3 spec defines the JSON structure of `zarr.json` for arrays and groups exactly, by defining the members that must be present and the JSON types they must have. But the __interpretation__ of those members as actual data types, codecs, chunk grids, etc is not strictly defined by the spec. Relating a JSON value like `"bytes"` to the `bytes` codec requires a mapping from names to codec types.
 
 `zarr-metadata` makes this explicit by validating JSON documents with a __context object__. That context object contains definitions of codecs, data types, etc, which can be matched to the declarations in the JSON document.
 
@@ -47,7 +47,7 @@ document: ZarrV3ArrayMetadataJSON = {
 }
 ```
 
-In the above code snippet we define a `zarr.json` document with three codec declarations (we will just call them codecs for brevity): one named `bytes`, another named `gzip`, and a third named `unknown`. The `bytes` codec here is correctly configured according to the `bytes` codec spec. The `gzip` declaration here violates the `gzip` codec spec because the `level` configuration field is too high. And the `unknown` codec is unknown, it has no specification and cannot be resolved.
+In the above code snippet we define a `zarr.json` document with three codec declarations (we will just call them codecs for brevity): one named `bytes`, another named `gzip`, and a third named `unknown`. The `bytes` codec here is correctly configured according to the `bytes` codec spec. The `gzip` declaration here violates the `gzip` codec spec because the `level` configuration member is too high. And the `unknown` codec is unknown, it has no specification and cannot be resolved.
 
 These three codecs represent three different scenarios that this library handles, two with distinct failure modes. We demonstrate how this works in the next code snippet.
 
@@ -101,7 +101,7 @@ These are the three scenarios:
 
 - `bytes` is parsed to an `AcceptedDeclaration`. A definition in the context claims the name `bytes`, and the configuration passes its checks.
 - The malformed `gzip` is parsed to a `RefusedDeclaration`. A definition claims the name `gzip`, but the configuration fails one of its checks: a `level` of 99 is outside the range gzip allows. The read reports the problem, with its location in the document, and builds no model, so `reading.metadata` is `None`. Building the model directly raises the same problem as a `MetadataValidationError`.
-- The `unknown` codec is parsed to an `UnclaimedDeclaration`. Nothing in the context claims the name, so it is kept as written and not checked. This is not a problem: the spec lets a document name codecs a reader does not know.
+- The `unknown` codec is parsed to an `UnclaimedDeclaration`. Nothing in the context claims the name, so it is kept as written and not checked. This is not a problem: the spec [lets a document name codecs](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#extension-codecs) defined outside it, which a reader may not know.
 
 So one JSON document can be valid in one context and invalid in another. This is why a model is a document _and_ the context it was read in: the context defines the interpretation of the document. A model keeps its context, and moving it to another context reads the document again. Our `small` model was valid in its original context, but it is not valid in the new one:
 
diff --git a/packages/zarr-metadata/docs/extensions.md b/packages/zarr-metadata/docs/extensions.md
new file mode 100644
index 0000000000..357d29d493
--- /dev/null
+++ b/packages/zarr-metadata/docs/extensions.md
@@ -0,0 +1,83 @@
+# Writing an extension
+
+A document may name a codec, data type, chunk grid, chunk key encoding or
+storage transformer that this package does not define: each is an
+[extension point](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#extension-points) of the v3 spec. The readers leave
+such a declaration unclaimed, and a program that needs to check it adds a
+**definition** to the context it reads in. The
+[`zarr_metadata.definition`](api/definition.md) module docstring is the
+full reference; this page is the short version.
+
+A definition is a value, not a class to subclass. It has a `name`, a
+`TypedDict` for the configuration's JSON, and, when the type cannot
+express every rule, a `rules` function that yields the spec violations in a
+configuration. A v3 codec also says what kind of codec it is and whether
+its output size is fixed by its input size.
+
+```python test="true" session="extensions"
+from collections.abc import Iterator
+from typing import Annotated, NotRequired
+
+from annotated_types import Ge
+from typing_extensions import TypedDict
+
+from zarr_metadata import ValidationProblem
+from zarr_metadata.definition import Nested
+from zarr_metadata.v3.definition import CORE_AND_EXTENSIONS_CONTEXT, CodecDefinition
+
+
+class AcmeLz4Configuration(TypedDict, closed=True):
+    acceleration: Annotated[int, Ge(1)]
+    dictionary: NotRequired[str]
+    dictionary_size: NotRequired[Annotated[int, Ge(1)]]
+
+
+def acme_lz4_rules(
+    configuration: AcmeLz4Configuration, nested: Nested
+) -> Iterator[ValidationProblem]:
+    if "dictionary" in configuration and "dictionary_size" not in configuration:
+        yield ValidationProblem(
+            ("dictionary_size",), "a dictionary needs its size", "missing_key"
+        )
+
+
+ACME_LZ4 = CodecDefinition(
+    name="acme.lz4",
+    configuration=AcmeLz4Configuration,
+    kind="bytes_bytes",
+    size="dynamic",
+    rules=acme_lz4_rules,
+)
+CONTEXT = CORE_AND_EXTENSIONS_CONTEXT.update(codecs=[*CORE_AND_EXTENSIONS_CONTEXT.codecs.values(), ACME_LZ4])
+```
+
+Pass `context=CONTEXT` to any reader or model constructor, and a document
+that names `acme.lz4` is checked against this definition.
+
+Some rules for the pieces:
+
+- The `TypedDict` must be a `typing_extensions.TypedDict`, and must say
+  how undeclared keys are handled: `closed=True`, `extra_items=`, or
+  `closed=False`. An open-by-default `TypedDict` is refused, because it
+  would accept a misspelled key silently.
+- Its members must be JSON shapes: `int`, `float`, `bool`, `str`, `None`,
+  `JSONValue`, a `Literal`, `tuple[T, ...]`, `tuple[T1, T2]`, a union, a
+  `TypedDict`, `Mapping[str, V]`, a `NewType` or a type alias. A number
+  may carry bounds from annotated-types (`Gt`, `Ge`, `Lt`, `Le`,
+  `Interval`). Any other `Annotated` metadata is refused when the
+  definition is built.
+- The rules run only on a configuration within its bounds, so a rule can
+  rely on them. A rule reports the location of a problem, and the value
+  there becomes the problem's `input`. Show values in messages with
+  `zarr_metadata.problems.shown`, so they read like the package's own.
+- Define each function at module top level. A model holds the definitions
+  that read it, so it can be pickled only if they can.
+
+A data type also declares its fill value (`fill_value`,
+`fill_value_rules`, `fill_value_canonical`) and how its values are stored
+(`storage`). A chunk grid declares which shapes it fits (`shape_rules`) and
+its chunk lengths (`chunk_lengths`). A codec declares what it checks about
+the chunk it receives (`chunk_rules`), what it hands on (`transition`), and
+any pipelines it contains (`pipelines`). The
+[`zarr_metadata.v3.definition`](api/v3/definition.md) docstring describes
+each of these.
diff --git a/packages/zarr-metadata/docs/index.md b/packages/zarr-metadata/docs/index.md
index b139dfd307..50058a3041 100644
--- a/packages/zarr-metadata/docs/index.md
+++ b/packages/zarr-metadata/docs/index.md
@@ -1,411 +1,89 @@
 # zarr-metadata
 
-Basic tools for modelling Zarr metadata, with minimal dependencies.
+Types, models and validators for Zarr metadata documents, with minimal
+dependencies.
 
 `zarr-metadata` is developed in the
 [zarr-python repository](https://github.com/zarr-developers/zarr-python/tree/main/packages/zarr-metadata)
-and released independently of `zarr` itself. Install it with:
+and released independently of `zarr`. Install it with:
 
 ```
 pip install zarr-metadata
 ```
 
-## Who needs this
-
-This library supports software that interacts with Zarr metadata documents.
-
 ## What this is
 
-This is *not* a full Zarr implementation. It's a collection of data structures and routines that
-closely model the content of the Zarr specifications, such as:
-
-- **Typed JSON shapes** ([`zarr_metadata.v2`](api/v2.md) and
-  [`zarr_metadata.v3`](api/v3/index.md)): `TypedDict` definitions and
-  `Literal` aliases for the JSON documents specified by the
-  [Zarr v2](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html) and
-  [Zarr v3](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html)
-  specifications, plus types for
-  [zarr-extensions](https://github.com/zarr-developers/zarr-extensions/) and a
-  few widely-used-but-unspecified entities (e.g. consolidated metadata).
-- **Document models** ([`zarr_metadata.model`](api/model.md)): immutable
-  models of whole metadata documents, each one a document and the scope
-  it was read in, with readers that report every problem at its
-  location, and store-key (de)serialization. A document
-  produced by `to_json` shares no mutable state with the model that produced
-  it.
-- **Definitions and scopes** ([`zarr_metadata.definition`](api/definition.md),
-  with each format's kinds in `zarr_metadata.v3.definition` and
-  `zarr_metadata.v2.definition`): each extension's configuration as a
-  `TypedDict` with its rules, and the scope that decides which definitions
-  read a document. `zarr_metadata.v3` and `zarr_metadata.v2` export every
-  definition and scope of their format, such as `BYTES_CODEC` and
-  `CORE_AND_EXTENSIONS_CONTEXT`.
-- **JSON type checking** ([`zarr_metadata.typed_json`](api/typed_json.md)):
-  `check` checks a JSON value against any `TypedDict` and reports every
-  problem with its location.
-- **Problems** ([`zarr_metadata.problems`](api/problems.md)): the problem
-  values every reader returns, and the error that carries them.
-- **JSON Schema** ([`zarr_metadata.json_schema`](api/json_schema.md)): the
-  JSON Schema of a `TypedDict`, a v3 declaration, or a whole `zarr.json`.
-- **Optional Pydantic integration** ([`zarr_metadata.pydantic`](api/pydantic.md),
-  requires Pydantic 2.13 or newer): each model as a Pydantic field type that
-  validates raw documents through the same strict parser.
-
-## What this is for
-
-- **Static Type Checking** The public `TypedDict` definitions describe the static JSON shape of Zarr
-  metadata.
-
-- **Dynamic JSON validation** For strict, location-aware validation of JSON loaded from disk, use the
-  model parser:
-
-  ```python test="true" session="index"
-  import json
-  from zarr_metadata.model import ZarrV3ArrayMetadata
-
-  with open("zarr.json", "rb") as f:
-      raw = json.load(f)
-
-  metadata = ZarrV3ArrayMetadata.from_json(raw)
-  ```
-
-  The optional Pydantic integration delegates raw input to the same strict
-  parser and returns the same normalized model class:
-
-  ```python test="true" session="index"
-  from pydantic import TypeAdapter
-  import zarr_metadata.pydantic as zmp
-
-  adapter: TypeAdapter[zmp.ZarrV3ArrayMetadataField] = TypeAdapter(zmp.ZarrV3ArrayMetadataField)
-  metadata = adapter.validate_python(raw)
-  encoded = metadata.to_key_value()["zarr.json"]
-  ```
-
-  A field annotated `Annotated[ZarrV3ArrayMetadata, zmp.InScope(CONTEXT)]`
-  is read in `CONTEXT`, whatever the validation context holds, and a model
-  instance given to it is read again in `CONTEXT`.
-
-  Note that a bare `TypeAdapter` over a public `TypedDict` is a **coercive** shape
-  adapter, not a Zarr conformance validator; it may coerce values or discard
-  members that the strict model parser rejects. This is better suited for handling input provided
-  from Python objects (e.g., user-authored dicts) than JSON.
-
-## Validation boundary
-
-The readers and model constructors enforce the declared document structure and a small set
-of context-free consistency rules, e.g.:
-- fixed format literals,
-- finite JSON numbers outside `attributes` and the members nothing in scope reads
-- non-negative dimensions
-- one `dimension_names` entry per array dimension.
-
-In a v3 document, validation also checks each extension point: the data
-type, the chunk grid, the chunk key encoding, each codec, and each storage
-transformer. Each one is checked by the definition that claims its name in
-a scope. The scope is `CORE_AND_EXTENSIONS_CONTEXT` unless a `context` is passed.
-`ZARR_PYTHON_CONTEXT` adds the data types that zarr-python writes but no
-specification registers.
-If the definition rejects a configuration, the reader rejects it too,
-and a configuration key the definition does not declare is reported as
-`unknown_key`. If no definition in the scope claims a name, the reader
-does not check that extension point, and the consumer decides whether to
-support it.
-
-Making the context and explicit part of metadata parsing allows different libraries, which might support different
-sets of Zarr features, to formally represent exactly the codecs, data types, etc they support when
-parsing metadata.
-
-Some checks relate one part of a v3 document to another:
-
-- The fill value is checked against the data type the document names, by
-  that data type's definition.
-- The chunk grid is checked against the shape, by the grid's definition.
-- The codecs are checked as a pipeline. In order, each codec's definition
-  checks the codec against the chunk it receives. This includes a shard's
-  inner codecs and index codecs.
-
-The readers do no arithmetic on values. For example, they do not check
-whether a fill value survives a `cast_value` round trip.
-
-Some choices that the spec text leaves open, or answers in two ways:
-
-- **`attributes` may hold `NaN`, `Infinity` and `-Infinity`.** The spec
-  does not interpret attributes, and zarr-python and xarray write these
-  numbers there (for example, a CF `_FillValue`). The models read them,
-  and `to_key_value` writes them back as bare tokens, which a strict JSON
-  parser rejects. So may a member the spec does not define when no
-  definition in scope claims it: nothing reads it, so it is kept as
-  written. `check`, from `zarr_metadata.typed_json`, rejects a non-finite
-  number anywhere, including in attributes.
-- **A reader walks at most 256 levels of nesting.** A value nested deeper
-  is an `invalid_value` problem at the first level past the limit,
-  wherever it is. Every reader, writer and comparison uses one stack
-  frame per level, and `copy.deepcopy` (and `pickle` before Python 3.12)
-  uses two. A document at the limit therefore uses about half of the
-  interpreter's default recursion limit, and the rest is left for the
-  caller.
-- **`consolidated_metadata: null` is a problem.** A zarr-python 3.0.x bug
-  wrote it. The spec requires an object, and the package accepts only an
-  object. A reader of those stores removes the key before reading.
-- **An extension name must follow the spec's naming rule**,
-  `^[a-z][a-z0-9-_.]+$`, or be a URI, which earlier versions of the spec
-  required. Any other name is rejected before any definition is
-  consulted, so `""` and `"foo/bar"` are problems, not unknown extensions.
-- **`must_understand: false` is rejected at every extension point**,
-  including codecs and storage transformers, although the core spec names
-  only the data type, chunk grid and chunk key encoding. A reader that
-  skips a codec reads wrong bytes, just as a reader that skips a data type
-  reads wrong values. On an unknown top-level member, `must_understand`
-  keeps its meaning: a reader can skip that member.
-- **A v2 datetime or timedelta dtype must have a unit**, as in `<M8[ns]`,
-  because the v2 spec requires the unit in brackets. zarr-python 3 writes
-  `<M8` or `<m8` for a NumPy `datetime64` or `timedelta64` with no unit,
-  and the package refuses those dtypes. A codec's dtype parameter, such as
-  the `dtype` of a `delta` filter, may leave out the unit, because
-  numcodecs writes it that way and runs it.
-- **A v2 codec's dtype parameter is checked against the core v2 data
-  types**, whatever scope the array is read in, because numcodecs reads
-  the parameter with NumPy. So a scope that widens a data type, for
-  example to read `<f16`, does not widen what a codec's dtype parameter
-  may be.
-
-A v3 `regular` chunk grid's chunk lengths must be at least 1, even along a
-dimension of length 0. The regular grid spec says "Chunk sizes must be
-greater than zero". The core spec's wording, "non-zero when the
-corresponding dimensions of the arrays have non-zero length", requires
-less, but does not explicitly allow anything more. So a document with a
-chunk length of 0, which zarr-python 3.0 and 3.1 wrote for an empty
-dimension, is rejected.
-
-The readers are strict, so a document that a known writer bug made
-invalid has problems. The repair readers in `zarr_metadata.model`
-(`read_repaired_node_metadata_v3`, `read_repaired_node_metadata_v2` and
-`read_repaired_consolidated_metadata_v2`) undo these bugs first, then
-read the result strictly, and return each change they made as a `Repair`:
-
-- A chunk length of 0 in a v3 `regular` chunk grid, along an empty
-  dimension, which zarr-python 3.0 and 3.1 wrote, is written as 1.
-- `consolidated_metadata: null` on a v3 group, which zarr-python 3.0 and
-  3.1 wrote, is removed.
-- The `consolidated_metadata` member that zarr-python 3 writes into each
-  `.zgroup` entry of a `.zmetadata` below the root is removed.
-- A non-finite v2 fill value that zarr-python 3.0.0 to 3.0.6 wrote as a
-  bare `NaN`, `Infinity` or `-Infinity` is written as the string the v2
-  spec uses, such as `"NaN"`.
-- A non-finite float or complex fill value in a v3 group's consolidated
-  metadata, which zarr-python 3.0.0 to 3.0.6 wrote as a bare token, is
-  written as the string the v3 spec uses, such as `"NaN"`.
-
-The repair readers do not undo these known writer bugs, so a document
-with one of them is refused:
-
-- zarr-python 3.0.7 to 3.0.10 wrote the fill value of an `S` or `V`
-  array in a `.zmetadata` entry as a JSON array of byte values. The
-  array's own `.zarray` file holds the base64 string that the package
+A collection of data structures and routines that closely model the
+metadata rules in the [Zarr v2](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html)
+and [Zarr v3](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html)
+specifications and in [zarr-extensions](https://github.com/zarr-developers/zarr-extensions/):
+
+- **Typed JSON shapes**: `TypedDict` definitions for every document and
+  configuration, for static type checking at the boundary of a Zarr
+  application.
+- **Document models**: immutable models of whole documents, with readers
+  that report every problem at its location in the document.
+- **Contexts**: a model is a document read in a **context**, a collection
+  of definitions for codecs, data types, chunk grids and so on. This makes
+  an important fact explicit: not every Zarr implementation supports the
+  same set of features, and a program says exactly which features it
   reads.
-- zarr-python 3.0.7 and 3.0.8 wrote the fill value of a v2 datetime
-  array as an ISO 8601 string, not as a count of ticks.
-- zarr-python 3.0 and 3.1 wrote a chunk length of 0 in a v3 `regular`
-  chunk grid along a dimension that is not empty, for an explicit chunk
-  length of 0.
-- Some releases of zarr-python from 3.0 to 3.2 wrote a chunk length of
-  `true` in a v3 `regular` chunk grid for `chunks=True`, and some
-  releases of 3.0 and 3.1 wrote `false` for `chunks=False`.
-
-`read_array_metadata_v3` reads a document once and returns everything the
-read found:
 
-- each declaration as the scope read it: an `AcceptedDeclaration` when a definition
-  claims its name, an `UnclaimedDeclaration` when none does, or a
-  `RefusedDeclaration`, together with the declaration's location and the kind it was
-  read as;
-- each codec, with the chunk it receives;
-- every problem;
-- the model, when there are no problems.
+This is *not* a full Zarr implementation. Nothing here reads or writes
+chunks, encodes or decodes data, or performs store I/O.
 
-`from_json` returns that model, or raises the problems. A consumer can
-apply its own policy by walking the declarations, without reading anything
-twice. `with_problems` pairs each declaration with its problems: those located
-in the declaration and in the declarations it contains. This matches how zod's
-`flattenError` groups issues. `canonical_of` returns the simplest
-spelling of a declaration that has no problems, without reading it again. For
-example, the code below finds the declarations that go beyond the core spec (a
-declaration with no name is already a problem), and the simplest spelling of
-each declaration:
-
-```python test="true" session="index"
-from zarr_metadata.model import read_array_metadata_v3
-from zarr_metadata.definition import canonical_of, with_problems
-from zarr_metadata.v3.definition import CORE_CONTEXT
-
-reading = read_array_metadata_v3(raw)
-beyond_core = [
-    loc
-    for loc, declaration in reading.declarations()
-    if declaration.name is not None and CORE_CONTEXT.claimant(declaration.read_as, declaration.name) is None
-]
-simplest = {
-    loc: canonical_of(declaration, problems)
-    for loc, declaration, problems in with_problems(reading.declarations(), reading.problems)
-}
-metadata = reading.metadata  # None when reading.problems is not empty
-```
-
-`read_group_metadata_v3` reads a group the same way. It checks the
-envelope of the group's `consolidated_metadata`, and does not read the
-documents the member lists (see below). `read_node_metadata_v3` reads
-a `zarr.json` of either kind as the node type its `node_type` names, the
-same way a discriminated union uses its tag. A document whose `node_type`
-is neither reads as `ZarrV3UnknownNodeMetadataReading`, with the problems.
-Only its `zarr_format` is read, so a document of another format is
-reported as not v3. `node_metadata_from_json_v3` and
-`node_metadata_from_key_value_v3` build the model of either kind, the same
-way the models' own `from_json` and `from_key_value` build one.
-
-Consolidated metadata holds the hierarchy below its group, with the group
-as the root. The document of the node at `/a/b` is stored under the key
-`a/b`. The documents and the group must form a tree: only groups have
-child nodes, and the parent of every node is present.
-`ZarrV3ConsolidatedMetadata` checks this when it reads the documents. `NodeName` and
-`NodePath`, in `zarr_metadata.v3`, are the types of strings that satisfy
-the spec's rules for node names and paths. They are modeled on the zarrs
-types with the same names. `validate_node_name_v3`, `is_node_name_v3` and
-`parse_node_name_v3`, and the matching `node_path` functions, check a
-string against those rules.
-
-A top-level member that the spec does not define is an extra field. A
-scope can hold a definition for one, by its key, in the
-`array_extra_fields` or `group_extra_fields` slot of `ZarrV3Context`. A
-member whose key a definition claims is read by that definition: an extra field is a declaration
-written as the member alone, `{key: value}`. Any other extra field is kept as
-written, as an `UnclaimedDeclaration`.
-The scope is what a reader recognizes, so the model's
-`must_understand_fields` lists each unclaimed member that does not say
-`"must_understand": false`: the spec requires a reader to fail to open a
-node with any such member. It covers extra fields only. A data type, chunk
-grid, chunk key encoding, codec or storage transformer that nothing in
-scope claims is an `UnclaimedDeclaration` too, also when it sits inside another
-declaration, such as a codec inside a shard. A model's `unclaimed_declarations` lists
-every declaration nothing in scope claims, at any depth, by its location, and
-leaves out the members that waive `must_understand`: a reader can open
-the node when it is empty. `CORE_CONTEXT` holds
-`CONSOLIDATED_METADATA_EXTRA_FIELD`, which reads a group's
-`consolidated_metadata` as the envelope the spec fixes. A group's
-`consolidated()` reads the documents that member lists, in the group's
-own scope.
-
-A v3 model consists of its document and the scope it was read in.
-`ZarrV3ArrayMetadata(document, context=None)` reads the document in the
-scope (`CORE_AND_EXTENSIONS_CONTEXT` when none is given) and raises
-`MetadataValidationError` with every problem, so an invalid model is never
-built. `to_json` returns the document as it was written, and
-`to_key_value` writes that same document to store bytes.
-
-Every typed attribute is a view of that read: each declaration as the scope read
-it (an `AcceptedDeclaration` or an `UnclaimedDeclaration`), and `shape`, `attributes`
-and the members that hold no declaration as the read refined them. These views are read-only
-at every level: a list in the document is shown as a tuple, and an object
-as a read-only mapping. `to_json` returns plain containers.
-
-To change a model, call `update`. It replaces members of the document with
-the given JSON members and reads the result in the model's own scope, so
-you do not pass the scope again. A member the spec defines is given by its
-name, and any other member in `extra_fields`, a mapping from its key to its
-value, or to `UNSET` to remove it. A name `update` does not take raises
-`TypeError`, so a misspelled member is never written. `with_context` reads the document in
-another scope. `refined_in` also reads the document in another scope, but
-only one that claims what this scope left unclaimed and contradicts
-nothing; otherwise it raises `ScopeConflictError`.
-
-A group does not read the documents its `consolidated_metadata` lists.
-Consolidated metadata is a convention of the reference implementation,
-not core metadata, so a group holds the member as written, after it
-checks the envelope that the core spec fixes. A reader can use the
-member as a source of child documents in place of the store: read one
-document with `read_node_metadata_v3` when that node is opened, or read
-all of them with `ZarrV3ConsolidatedMetadata`, or with
-`read_consolidated_metadata_v3`, which returns problems instead of
-raising them. A document with a problem then fails only when it is read.
-Pass `context=group.context` to read the documents in the group's own
-scope; with no `context`, they are read in `CORE_AND_EXTENSIONS_CONTEXT`.
-
-To write consolidated metadata, build a `ZarrV3ConsolidatedMetadata` and
-pass it to the group's `update`. The group reads the listed models in its
-own scope, refuses one that its scope reads differently, and writes the
-document. The model reads every document strictly, and also accepts node
-models as entries. Such an entry is accepted when its claims refine into
-the model's scope, and refused at its path otherwise. To consolidate
-children that were read in several scopes, consolidate them in the
-`union` of those scopes. Every reader takes `context=None` for the
-default scope, `CORE_AND_EXTENSIONS_CONTEXT`.
-
-Two models are equal when they represent the same document, even if each
-is spelled differently. Values the package interprets (each declaration, and the
-fill value against its data type) are compared by their canonical
-spelling, as returned by `canonical_of` and `canonical_fill_value`. For
-example, `"NaN"` and `"0x7fc00000"` are the same `float32` fill value,
-`0.0` and `-0.0` are two different fill values, and a v3 blosc codec
-under `noshuffle`, which ignores `typesize`, is the same codec with or
-without one. A v2
-document's dtype, codecs and fill value are compared the same way: `<b1`
-and `|b1` are one dtype, in `dtype` and in a codec's dtype parameter
-alike, and a v2 codec that leaves out a parameter is
-the same as one that writes the numcodecs default, so
-`{"id": "zstd", "level": 0}` equals
-`{"id": "zstd", "level": 0, "checksum": false}`. A v2 blosc `typesize`
-is kept whatever the `shuffle`, unlike in v3: v2 codecs are defined by
-numcodecs, which writes it into each chunk's header, so two v2 blosc
-codecs that differ only in it encode different bytes, though they decode
-the same data. The v3 spec defines its blosc codec, and says `noshuffle`
-ignores `typesize`. A v2 node with no `.zattrs` equals one with an
-empty `.zattrs`, as a v3 document with and without an empty
-`attributes` are equal. Values the package does
-not interpret (attributes, extra fields, and the configuration of a declaration
-that nothing in the scope claims) are compared as JSON text. JSON text
-distinguishes `true` from `1` and `-0.0` from `0.0`, and treats `NaN` as
-equal to itself. Equal models have equal hashes, but may write different
-documents, because `to_json` writes each document as it was given. A
-model holds nothing that can be changed in place.
-
-`node_metadata_json_schema_v3` writes the rules the readers apply as a
-JSON Schema (draft 2020-12). Use it in an editor that checks a `zarr.json`
-while you write it, or with a validator in another language. Each
-extension point is described as a declaration as its scope reads it: a claimed
-configuration follows its definition's TypedDict, including bounds, and a
-name that nothing in the scope claims may have any configuration. The fill
-value must be a valid fill value for the data type the document names.
-`declaration_json_schema_v3(kind, *, context=None)` writes the schema of one declaration, and
-`json_schema` writes the schema of any TypedDict as `check` reads it. All
-three are in `zarr_metadata.json_schema`. A schema describes each member on its own, not the rules that
-relate members to each other, so a document the schema accepts may still
-have a problem. Every JSON document the readers accept, the schema also
-accepts. A schema validator reads JSON as a parser produces it, with
-arrays as lists. A model's `to_json` returns tuples, which a Python
-validator does not accept as arrays.
+Reading a `zarr.json` from disk looks like this:
 
 ```python test="true" session="index"
 import json
-from zarr_metadata.json_schema import node_metadata_json_schema_v3
+from zarr_metadata import ZarrV3ArrayMetadata
 
-with open("zarr.schema.json", "w") as f:
-    json.dump(node_metadata_json_schema_v3(), f, indent=2)
-```
+with open("zarr.json", "rb") as f:
+    raw = json.load(f)
 
-## Scope
+metadata = ZarrV3ArrayMetadata.from_json(raw)
+```
 
-At minimum, this library supports what Zarr-Python needs: the complete
+`from_json` returns the model, or raises `MetadataValidationError` with
+every problem it found.
+
+## Where to go next
+
+- **You want type hints for Zarr JSON.** The `TypedDict`s are in
+  [`zarr_metadata.v3`](api/v3/index.md) and [`zarr_metadata.v2`](api/v2.md),
+  and `check` in [`zarr_metadata.typed_json`](api/typed_json.md) turns any
+  of them into a runtime check.
+- **You validate metadata you did not write.** Start with
+  [Parsing and validation](parsing-validation.md) for what the readers
+  check and why, then [Models and readers](models.md) for the API.
+  [What the readers check](validation-rules.md) lists the rules and the
+  decisions made where the spec is silent.
+- **You support codecs or data types this package does not know.** Read
+  [Context](context.md), then [Writing an extension](extensions.md).
+- **You read stores written by older versions of zarr-python.** See
+  [Repairing known writer bugs](repair.md).
+- **You work with hierarchies.** See
+  [Consolidated metadata](consolidated-metadata.md).
+- **You build tools around the metadata.** [JSON Schema](json-schema.md)
+  writes the readers' rules for an editor or another language, and
+  [Pydantic](pydantic.md) wraps each model as a field type.
+- **You want the module-by-module view.** The [API reference](api/index.md)
+  describes each module, and the module docstrings are the detailed guide.
+
+## What the library covers
+
+At minimum, this library supports what zarr-python needs: the complete
 Zarr v2 and v3 specs, consolidated metadata, and a subset of the metadata
-defined in `zarr-extensions`. We are generally open to contributions that
-add types, models, or validation for Zarr metadata with a
-published spec.
+defined in zarr-extensions. We are generally open to contributions that
+add types, models, or validation for Zarr metadata with a published spec.
+
+The models begin and end at the metadata documents themselves:
+`from_key_value` and `to_key_value` map documents to store keys and bytes,
+and everything past that, including resolving a codec or data type name to
+an implementation, belongs to consumer libraries. This boundary limits how
+far some codec combinations can be validated. For example,
+the readers cannot check that a `cast_value` codec maps scalars one to one.
 
-Runtime array behavior is out of scope: nothing here encodes or decodes
-chunks, resolves codec or data type names to implementations, or performs
-store I/O. The models begin and end at the metadata documents themselves —
-`from_key_value` / `to_key_value` map documents to store keys and bytes,
-and everything past that belongs to consumer libraries. The "no encoding / decoding" rule does constrain
-how extensively we can validate certain codec combinations. For example, we cannot check that the `cast_value`
-codec bijectively maps scalars.
 ## Reference
 
 - [API reference](api/index.md)
diff --git a/packages/zarr-metadata/docs/json-schema.md b/packages/zarr-metadata/docs/json-schema.md
new file mode 100644
index 0000000000..783476e514
--- /dev/null
+++ b/packages/zarr-metadata/docs/json-schema.md
@@ -0,0 +1,33 @@
+# JSON Schema
+
+`zarr_metadata.json_schema` writes the rules the readers apply as JSON
+Schema (draft 2020-12). Use it in an editor that checks a `zarr.json` while
+you write it, or with a validator in another language.
+
+- `node_metadata_json_schema_v3(context=None)` writes the schema of a
+  whole v3 `zarr.json`, array or group.
+- `declaration_json_schema_v3(kind, *, context=None)` writes the schema of
+  one declaration read as `kind`.
+- `json_schema(typed_dict)` writes the schema of any of the package's
+  `TypedDict`s, as `check` from `zarr_metadata.typed_json` reads it.
+
+Each extension point is described as a declaration as its context reads
+it: a claimed configuration follows its definition's TypedDict, including
+bounds, and a name that nothing in the context claims may have any
+configuration. The fill value must be a valid fill value for the data type
+the document names.
+
+A schema describes each member on its own, not the rules that relate members
+to each other, so a document the schema accepts may still have a problem.
+Every JSON document the readers accept, the schema also accepts. A schema
+validator reads JSON as a parser produces it, with arrays as lists. A
+model's `to_json` returns tuples, which a Python validator does not accept
+as arrays.
+
+```python test="true" session="json-schema"
+import json
+from zarr_metadata.json_schema import node_metadata_json_schema_v3
+
+with open("zarr.schema.json", "w") as f:
+    json.dump(node_metadata_json_schema_v3(), f, indent=2)
+```
diff --git a/packages/zarr-metadata/docs/models.md b/packages/zarr-metadata/docs/models.md
new file mode 100644
index 0000000000..2deb6c2b36
--- /dev/null
+++ b/packages/zarr-metadata/docs/models.md
@@ -0,0 +1,160 @@
+# Models and readers
+
+A model is a metadata document and the context it was read in. This page
+covers how a document becomes a model, what a model exposes, how to change
+one, and when two models are equal. The [Context](context.md) page explains
+why the context is part of the model; this page is about using it.
+
+## Readers and readings
+
+Every document type has a reader in `zarr_metadata.model`. A reader does
+one read and returns a **reading**: everything the read found, as values,
+with nothing raised. `read_array_metadata_v3` returns:
+
+- each declaration as the context read it: an `AcceptedDeclaration` when a
+  definition claims its name, an `UnclaimedDeclaration` when none does, or
+  a `RefusedDeclaration`, together with the declaration's location and the
+  kind it was read as;
+- each codec, with the chunk it receives;
+- every problem;
+- the model, when there are no problems.
+
+The model's `from_json` returns that model, or raises
+`MetadataValidationError` with the same problems. A consumer can apply its
+own policy by walking the declarations, without reading anything twice.
+`with_problems` pairs each declaration with its problems: those located in
+the declaration and in the declarations it contains. This matches how zod's
+`flattenError` groups issues. `canonical_of` returns the simplest spelling
+of a declaration that has no problems, without reading it again. For
+example, the code below finds the declarations that go beyond the core spec
+(a declaration with no name is already a problem), and the simplest
+spelling of each declaration:
+
+```python test="true" session="models"
+import json
+from zarr_metadata.model import read_array_metadata_v3
+from zarr_metadata.definition import canonical_of, with_problems
+from zarr_metadata.v3.definition import CORE_CONTEXT
+
+with open("zarr.json", "rb") as f:
+    raw = json.load(f)
+
+reading = read_array_metadata_v3(raw)
+beyond_core = [
+    loc
+    for loc, declaration in reading.declarations()
+    if declaration.name is not None and CORE_CONTEXT.claimant(declaration.read_as, declaration.name) is None
+]
+simplest = {
+    loc: canonical_of(declaration, problems)
+    for loc, declaration, problems in with_problems(reading.declarations(), reading.problems)
+}
+metadata = reading.metadata  # None when reading.problems is not empty
+```
+
+`read_group_metadata_v3` reads a group the same way. It checks the envelope
+of the group's `consolidated_metadata`, and does not read the documents the
+member lists (see [Consolidated metadata](consolidated-metadata.md)).
+`read_node_metadata_v3` reads a `zarr.json` of either kind as the node type
+its [`node_type`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#node-type) names, the same way a discriminated union uses its tag. A
+document whose `node_type` is neither reads as
+`ZarrV3UnknownNodeMetadataReading`, with the problems. Only its
+`zarr_format` is read, so a document of another format is reported as not
+v3. `node_metadata_from_json_v3` and `node_metadata_from_key_value_v3`
+build the model of either kind, the same way the models' own `from_json`
+and `from_key_value` build one.
+
+Every reader takes `context=None` for the default context,
+`CORE_AND_EXTENSIONS_CONTEXT`.
+
+## A model is a document read in a context
+
+`ZarrV3ArrayMetadata(document, context=None)` reads the document in the
+context (`CORE_AND_EXTENSIONS_CONTEXT` when none is given) and raises
+`MetadataValidationError` with every problem, so an invalid model is never
+built. `to_json` returns the document as it was written, and `to_key_value`
+writes that same document to store bytes.
+
+Every typed attribute is a view of that read: each declaration as the
+context read it (an `AcceptedDeclaration` or an `UnclaimedDeclaration`),
+and `shape`, `attributes` and the members that hold no declaration as the
+read refined them. These views are read-only at every level: a list in the
+document is shown as a tuple, and an object as a read-only mapping.
+`to_json` returns plain containers. A model holds nothing that can be
+changed in place.
+
+To change a model, call `update`. It replaces members of the document with
+the given JSON members and reads the result in the model's own context, so
+you do not pass the context again. A member the spec defines is given by its
+name, and any other field in `extra_fields`, a mapping from its key to its
+value, or to `UNSET` to remove it. A name `update` does not take raises
+`TypeError`, so a misspelled member is never written. `with_context` reads
+the document in another context. `refined_in` also reads the document in
+another context, but only one that claims what this context left unclaimed
+and contradicts nothing; otherwise it raises `ScopeConflictError`.
+
+## Extra fields
+
+A top-level member that the spec does not define is an extra field. The
+core spec hands such a member to its [extension rules](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#unknown). A
+context can hold a definition for one, by its key, in the
+`array_extra_fields` or `group_extra_fields` slot of `ZarrV3Context`. A
+member whose key a definition claims is read by that definition: an extra
+field is a declaration written as the member alone, `{key: value}`. Any
+other extra field is kept as written, as an `UnclaimedDeclaration`.
+
+The spec calls these members [additional fields](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html#additional-fields),
+and the names `extra_fields`, `ExtraFieldDefinition` and
+`must_understand_fields` follow it. That heading comes from
+[PR 373](https://github.com/zarr-developers/zarr-specs/pull/373), which
+renamed the section v3.1.0 calls [Unknown](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#unknown).
+As of v3.1.0 no tagged release carries the new heading, so the link points
+at the latest spec; pin it once a release does. Everywhere else this package says
+*member* for a name/value pair of a JSON object and *declaration* for the
+value at an extension point. It keeps *field* for the fields of a Python
+class, such as a dataclass or a pydantic model, and, after the spec and
+NumPy, for the parts of a structured data type (`StructField`).
+
+The context is what a reader recognizes, so the model's
+`must_understand_fields` lists each unclaimed member that does not say
+`"must_understand": false`: the spec [requires](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#must-understand) a reader to fail to open a
+node with any such member. It covers extra fields only. A data type, chunk
+grid, chunk key encoding, codec or storage transformer that nothing in the
+context claims is an `UnclaimedDeclaration` too, also when it sits inside
+another declaration, such as a codec inside a shard. A model's
+`unclaimed_declarations` lists every declaration nothing in the context
+claims, at any depth, by its location, and leaves out the members that waive
+`must_understand`: a reader can open the node when it is empty.
+
+## Equality
+
+Two models are equal when they represent the same document, even if each
+is spelled differently. Values the package interprets (each declaration,
+and the fill value against its data type) are compared by their canonical
+spelling, as returned by `canonical_of` and `canonical_fill_value`. For
+example, `"NaN"` and `"0x7fc00000"` are the [same `float32` fill value](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/data-types/index.html#permitted-fill-values),
+`0.0` and `-0.0` are two different fill values, and a v3 blosc codec under
+`noshuffle`, which [ignores `typesize`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/blosc/index.html#configuration-parameters), is the same codec with or without
+one.
+
+A v2 document's [dtype](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html#data-type-encoding), codecs and fill value are compared the same way:
+`<b1` and `|b1` are one dtype, in `dtype` and in a codec's dtype parameter
+alike, and a v2 codec that leaves out a parameter is the same as one that
+writes the numcodecs default, so `{"id": "zstd", "level": 0}` equals
+`{"id": "zstd", "level": 0, "checksum": false}`. A v2 blosc `typesize` is
+kept whatever the `shuffle`, unlike in v3: v2 codecs are defined by
+numcodecs, which writes it into each chunk's header, so two v2 blosc codecs
+that differ only in it encode different bytes, though they decode the same
+data. The [v3 blosc spec](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/blosc/index.html#configuration-parameters) says `noshuffle` ignores `typesize`. A v2 node
+with no `.zattrs` equals one with an empty `.zattrs`: the
+[v2 spec](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html#attributes) says the key
+"does not have to be present, and if it is absent the attributes should be
+treated as empty". In the same way, a v3 document with no `attributes`
+equals one whose `attributes` is empty.
+
+Values the package does not interpret (attributes, extra fields, and the
+configuration of a declaration that nothing in the context claims) are
+compared as JSON text. JSON text distinguishes `true` from `1` and `-0.0`
+from `0.0`, and treats `NaN` as equal to itself. Equal models have equal
+hashes, but may write different documents, because `to_json` writes each
+document as it was given.
diff --git a/packages/zarr-metadata/docs/parsing-validation.md b/packages/zarr-metadata/docs/parsing-validation.md
index 1be626d5ee..a60e6618c0 100644
--- a/packages/zarr-metadata/docs/parsing-validation.md
+++ b/packages/zarr-metadata/docs/parsing-validation.md
@@ -25,26 +25,26 @@ This procedure yields one of two values:
 
 ### JSON document shape
 
-At this stage we check that the document is a JSON object with per-field structure consistent with rules in the Zarr V3 spec.
+At this stage we check that the document is a JSON object with per-member structure consistent with rules in the Zarr V3 spec.
 
 After confirming that the object named `zarr.json` is indeed valid JSON, we now need to check that the structure of this object is consistent with the rules in the Zarr V3 spec, namely the rules about the [structure of array metadata](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#array-metadata).
 
 At this stage we need to ensure that:
 
-- every **required** field is present
-- every **required** and **optional** field has the correct shape
+- every **required** member is present
+- every **required** and **optional** member has the correct shape
 
-The correct shape varies per field. The Zarr V3 spec defines a **generic metadata element type** that is reused for data types, codecs, etc. Inhabitants of that type are:
+The correct shape varies per member. The Zarr V3 spec defines a [**generic metadata element type**](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#extension-definition) that is reused for data types, codecs, etc. Inhabitants of that type are:
 
 - strings
-- JSON objects with a `"name"` field and optionally `"configuration"` and `"must_understand"` fields
+- JSON objects with a `"name"` member and optionally `"configuration"` and `"must_understand"` members
 
-The `data_type` field must comply with this shape. The `codecs` field must be a non-empty JSON array of values that comply with this shape.
+The `data_type` member must comply with this shape. The `codecs` member must be a non-empty JSON array of values that comply with this shape.
 
-The spec does not define a shape for **extra** fields. Instead, the [relevant section of the spec](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#unknown) says that a reader must refuse to open an array with an extra field, unless that field is a JSON object with `"must_understand": false`. Like an unknown name, which we will see later, an extra field is not a problem with the document. It's a field that some readers can't use. So at this stage we don't check extra fields; we just note which of them a reader must understand.
+The spec does not define a shape for **extra** fields. Instead, the [relevant section of the spec](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#unknown) says that a reader must refuse to open an array with an extra field, unless that field is a JSON object with [`"must_understand": false`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#must-understand). Like an unknown name, which we will see later, an extra field is not a problem with the document. It's a field that some readers can't use. So at this stage we don't check extra fields; we just note which of them a reader must understand.
 
 !!! note
-    At this stage we don't need to know **which** data type, or chunk grid, or codecs, are declared in the metadata document. We are only looking at **how** those fields are declared. We will resolve the raw JSON to a specific data type, chunk grid, etc. in a later validation pass.
+    At this stage we don't need to know **which** data type, or chunk grid, or codecs, are declared in the metadata document. We are only looking at **how** those members are declared. We will resolve the raw JSON to a specific data type, chunk grid, etc. in a later validation pass.
 
 This procedure yields one of two values:
 
@@ -55,22 +55,22 @@ For a program that repairs broken `zarr.json` documents, the list of problems is
 
 ### Context-free consistency checks
 
-At this stage we check if correlated fields in the document are consistent.
+At this stage we check if correlated members in the document are consistent.
 
-Some of the fields in the array metadata document are semantically coupled in a way that can be directly checked at the structural level. As of this writing, the only such fields are the `shape` field (a JSON array of non-negative integers), and the `dimension_names` field (an optional JSON array of strings or `null`s).
+Some of the members in the array metadata document are semantically coupled in a way that can be directly checked at the structural level. As of this writing, the only such members are the `shape` member (a JSON array of non-negative integers), and the `dimension_names` member (an optional JSON array of strings or `null`s).
 
-The length of the `shape` field must match the length of the `dimension_names` field, if that field is declared.
+The length of the `shape` member must match the length of the `dimension_names` member, if that member is declared.
 
 This procedure yields one of two values:
 
-1. A Zarr-metadata-shaped JSON object with consistent `shape` and `dimension_names` fields
-2. A problem localized to the `dimension_names` field. Strictly speaking, we can't say which of the two fields is wrong. But we treat `shape` as the reference for the number of axes in the array, so the problem goes on the field that disagrees with it. `shape` is required, and other fields like `chunk_grid` depend on it; `dimension_names` is optional, and only names the axes. This metadata has to be repaired; there's no other way to handle it.
+1. A Zarr-metadata-shaped JSON object with consistent `shape` and `dimension_names` members
+2. A problem localized to the `dimension_names` member. Strictly speaking, we can't say which of the two members is wrong. But we treat `shape` as the reference for the number of axes in the array, so the problem goes on the member that disagrees with it. `shape` is required, and other members like `chunk_grid` depend on it; `dimension_names` is optional, and only names the axes. This metadata has to be repaired; there's no other way to handle it.
 
 ### Resolving and validating each declaration
 
 At this stage we check that each metadata object names a known type, given a registry of data types, codec types, etc., and that its configuration is valid for that type.
 
-We take the JSON given for the `data_type`, elements of `codecs`, `chunk_grid`, `chunk_key_encoding`, and `storage_transformers` fields and attempt to **resolve** that JSON into a concrete data type, chunk grid, etc.
+We take the JSON given for the `data_type`, elements of `codecs`, `chunk_grid`, `chunk_key_encoding`, and `storage_transformers` members and attempt to **resolve** that JSON into a concrete data type, chunk grid, etc.
 
 In the previous stages, we just had two elements to work with:
 
@@ -79,11 +79,11 @@ In the previous stages, we just had two elements to work with:
 
 This stage introduces a third element to our process: a registry of data types, codecs, chunk grids, etc. We "resolve" anonymous JSON metadata into a data type or codec by finding a type matching that JSON in the registry.
 
-That registry is keyed by string identifiers, which almost all[^1] data types, codecs, etc. present. And the result of this stage is no longer context-free: it depends on the contents of the registry, i.e. which codec, data type, etc. definitions are in scope.
+That registry is keyed by string identifiers, which almost all[^1] data types, codecs, etc. present. And the result of this stage is no longer context-free: it depends on the contents of the registry, i.e. which codec, data type, etc. definitions are in the context.
 
 For example, the string `"float64"` should resolve to the 64-bit floating point data type with the same name defined in the [Zarr V3 spec](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/data-types/index.html#core-data-types).
 
-We say "should" because that's what the Zarr V3 spec says about this. There is not a hard requirement that all implementations resolve the string `"float64"` to the 64-bit floating point data type. Someone could write their own (deviant) Zarr implementation that gives the name `"float64"` to a boolean data type. The mapping from JSON identifier (a string) to metadata type (a definition) is held by the registry that entered scope at this stage of validation.
+We say "should" because that's what the Zarr V3 spec says about this. There is not a hard requirement that all implementations resolve the string `"float64"` to the 64-bit floating point data type. Someone could write their own (deviant) Zarr implementation that gives the name `"float64"` to a boolean data type. The mapping from JSON identifier (a string) to metadata type (a definition) is held by the registry that was brought in at this stage of validation.
 
 For each declaration, we do two steps:
 
@@ -92,7 +92,7 @@ For each declaration, we do two steps:
 
 What if a name isn't in the registry? This is **not** a problem with the document. The document might be perfectly valid, and written by a program with a bigger registry than ours. An unknown name tells us something about our registry, not about the document. So we don't report it as a problem. Instead we mark the declaration as **unknown**, skip the second step, and leave it to the program that reads the document to decide what to do with it. A program that only needs to list the arrays in a hierarchy might be fine with an unknown codec. A program that decodes chunks is not, and it can try again with a more comprehensive registry.
 
-If the name is in the registry, we validate the configuration. Suppose our metadata JSON had the following `chunk_grid` field: `"chunk_grid": {"name": "regular", "configuration": "error"}`. If we resolved the name of the chunk grid (`"regular"`) to the [regular chunk grid](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/chunk-grids/regular-grid/index.html) defined in the core spec, then we must do additional checks on the structure of the `configuration` field before we can interpret this chunk grid. In this case, the spec requires that the `configuration` field be a JSON object with a `chunk_shape` field, which is a JSON array of positive integers. Our `"configuration": "error"` field has the wrong type, so this is a problem localized to `/chunk_grid/configuration`.
+If the name is in the registry, we validate the configuration. Suppose our metadata JSON had the following `chunk_grid` member: `"chunk_grid": {"name": "regular", "configuration": "error"}`. If we resolved the name of the chunk grid (`"regular"`) to the [regular chunk grid](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/chunk-grids/regular-grid/index.html) defined in the core spec, then we must do additional checks on the structure of the `configuration` member before we can interpret this chunk grid. In this case, the spec requires that the `configuration` member be a JSON object with a `chunk_shape` member, which is a JSON array of positive integers. Our `"configuration": "error"` member has the wrong type, so this is a problem localized to `/chunk_grid/configuration`.
 
 Validating a configuration might require resolving more declarations. Consider this example:
 
@@ -111,18 +111,18 @@ Validating a configuration might require resolving more declarations. Consider t
 }
 ```
 
-The name `"sharding_indexed"` should resolve to the [codec with the same name](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/sharding-indexed/index.html), and the definition of that codec states that its `codecs` field contains more codec metadata. These JSON array elements go through the same two steps, recursively: `"not_a_codec"` is not in the registry, so it is marked as unknown, not reported as a problem.
+The name `"sharding_indexed"` should resolve to the [codec with the same name](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/sharding-indexed/index.html), and the definition of that codec states that its `codecs` member contains more codec metadata. These JSON array elements go through the same two steps, recursively: `"not_a_codec"` is not in the registry, so it is marked as unknown, not reported as a problem.
 
 Repeating these steps, recursively if necessary, for all metadata objects, we yield one of two values:
 
 1. A Zarr metadata object where each declaration is either unknown, or resolved to a type and internally consistent with the definition of that type
 2. An enumeration of localized validation problems.
 
-### Consistency checks between fields
+### Consistency checks between members
 
 At this stage we check that our resolved metadata is consistent across the entire metadata document.
 
-Here we are in the space of interactions between metadata objects. It's a big space. One key invariant that cuts across many fields is dimensionality, i.e. the number of array axes. The `chunk_grid` and `shape` fields must agree on the dimensionality of the array. That is,
+Here we are in the space of interactions between metadata objects. It's a big space. One key invariant that cuts across many members is dimensionality, i.e. the number of array axes. The `chunk_grid` and `shape` members must agree on the dimensionality of the array. That is,
 
 ```json
 {
@@ -131,11 +131,11 @@ Here we are in the space of interactions between metadata objects. It's a big sp
 }
 ```
 
-is a snippet of an invalid metadata document because the `shape` field applies to an array with three axes while the `chunk_grid` field applies to an array with just one. As with `dimension_names`, `shape` is the reference, so the problem is localized to `/chunk_grid/configuration/chunk_shape`. Dimensionality shows up in codecs too: the `order` of a [`transpose`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/transpose/index.html) codec must name each array axis exactly once.
+is a snippet of an invalid metadata document because the `shape` member applies to an array with three axes while the `chunk_grid` member applies to an array with just one. As with `dimension_names`, `shape` is the reference, so the problem is localized to `/chunk_grid/configuration/chunk_shape`. Dimensionality shows up in codecs too: the `order` of a [`transpose`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/transpose/index.html) codec must name each array axis exactly once.
 
-The `fill_value` field is another example. The spec does not define a single shape for `fill_value`. Instead, each data type defines which JSON values it accepts as a fill value. So `"fill_value": "hello"` might be fine for a string data type, but it's a problem for `"float64"`. We can only check `fill_value` after we have resolved `data_type`.
+The `fill_value` member is another example. The spec does not define a single shape for `fill_value`. Instead, each data type defines which JSON values it accepts as a fill value. So `"fill_value": "hello"` might be fine for a string data type, but it's a problem for `"float64"`. We can only check `fill_value` after we have resolved `data_type`.
 
-The `codecs` field has the most interactions of all, because a list of codecs is a **pipeline**. The spec divides codecs into three kinds:
+The `codecs` member has the most interactions of all, because a list of codecs is a **pipeline**. [The spec](https://github.com/zarr-developers/zarr-specs/blob/v3.1.0/docs/v3/core/index.rst#L931-L1024) divides codecs into three kinds:
 
 - array → array codecs, like `transpose`, which take an array and return an array
 - array → bytes codecs, like `bytes`, which take an array and return bytes
@@ -145,8 +145,8 @@ A valid pipeline is zero or more array → array codecs, then exactly one array
 
 Each codec in the pipeline is also handed a value produced by everything that came before it. The first codec is handed a chunk with the data type of the array and the shape of the chunk grid's chunks. An array → array codec may change that shape or data type before handing it on. Some codecs have rules about what they are handed. For example:
 
-- The `bytes` codec requires an `endian` field in its configuration when the data type it is handed takes more than one byte per element. `{"name": "bytes"}` is valid for a `uint8` array, but a problem for a `float64` array.
-- The `sharding_indexed` codec requires that its inner `chunk_shape` evenly divides the shape of the chunk it is handed, which is the outer chunk (or shard) shape.
+- The [`bytes`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/bytes/index.html#configuration-parameters) codec requires an `endian` member in its configuration when the data type it is handed takes more than one byte per element. `{"name": "bytes"}` is valid for a `uint8` array, but a problem for a `float64` array.
+- The [`sharding_indexed`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/sharding-indexed/index.html#configuration-parameters) codec requires that its inner `chunk_shape` evenly divides the shape of the chunk it is handed, which is the outer chunk (or shard) shape.
 
 To check these rules, we walk the pipeline in order, tracking the chunk that each codec is handed. For codecs that hold pipelines of their own, like `sharding_indexed`, we walk those inner pipelines too.
 
@@ -161,7 +161,7 @@ This procedure yields one of two values:
 
 `zarr-metadata` does not run each stage as a separate function. Instead, a single read of the document collects the problems from every stage, so a caller gets the full list of problems at once.
 
-The **registry** from the resolve-and-validate stage is called a **scope** in this library. For Zarr V3 it is a [`ZarrV3Context`](api/v3/definition.md) object, with one slot for each kind of declaration (`data_types`, `codecs`, `chunk_grids`, ...), and every reader takes a `context` argument. The default scope is `CORE_AND_EXTENSIONS_CONTEXT`, which holds the data types, codecs, chunk grids, etc. defined in the Zarr V3 spec and in [zarr-extensions](https://github.com/zarr-developers/zarr-extensions/). `CORE_CONTEXT` holds only the definitions from the Zarr V3 spec. `ZARR_PYTHON_CONTEXT` adds to `CORE_AND_EXTENSIONS_CONTEXT` the data types that zarr-python writes but no specification registers (`null_terminated_bytes` for NumPy's `S`, `raw_bytes` for NumPy's `V`, and `variable_length_bytes`), so a strict check of what zarr-python writes passes it.
+The **registry** from the resolve-and-validate stage is called a **context** in this library. For Zarr V3 it is a [`ZarrV3Context`](api/v3/definition.md) object, with one slot for each kind of declaration (`data_types`, `codecs`, `chunk_grids`, ...), and every reader takes a `context` argument. The default context is `CORE_AND_EXTENSIONS_CONTEXT`, which holds the data types, codecs, chunk grids, etc. defined in the Zarr V3 spec and in [zarr-extensions](https://github.com/zarr-developers/zarr-extensions/). `CORE_CONTEXT` holds only the definitions from the Zarr V3 spec. `ZARR_PYTHON_CONTEXT` adds the data types that zarr-python writes but no specification registers.
 
 `read_array_metadata_v3` reads a JSON document and returns a "reading". `reading.problems` is a tuple of the problems, and `reading.metadata` is the validated model, or `None` if there are problems. Each problem has a `loc`, which is its position in the document as a tuple, a `kind`, like `missing_key` or `invalid_value`, and a human-readable `message`:
 
@@ -189,7 +189,7 @@ for problem in reading.problems:
 
 If you only want the model, `ZarrV3ArrayMetadata.from_json(raw)` returns it, or raises `MetadataValidationError` with every problem in `.problems`.
 
-To read one declaration on its own, such as a codec, use `resolve` from `zarr_metadata.definition`. It takes the declaration, the kind of declaration, and the scope, and returns the declaration as read and its problems:
+To read one declaration on its own, such as a codec, use `resolve` from `zarr_metadata.definition`. It takes the declaration, the kind of declaration, and the context, and returns the declaration as read and its problems:
 
 ```python test="true" session="parsing-validation"
 from zarr_metadata.definition import resolve
@@ -203,14 +203,14 @@ for problem in problems:
 # ('configuration', 'level') invalid_value
 ```
 
-A declaration with an unknown name is called **unclaimed**, because no definition in the scope claims that name. It is not reported as a problem: it is read as an `UnclaimedDeclaration`, and the checks that depend on it are skipped, as described above. So an empty `reading.problems` does not mean that every declaration is known. A program that decodes chunks should also check that no declaration is unclaimed. A model's `unclaimed_declarations` lists each one, at any depth, by its location, and leaves out an extra field that says `"must_understand": false`, with everything in it, since a reader may ignore it. A reading with problems has no model, and a node with problems cannot be opened either:
+A declaration with an unknown name is called **unclaimed**, because no definition in the context claims that name. It is not reported as a problem: it is read as an `UnclaimedDeclaration`, and the checks that depend on it are skipped, as described above. So an empty `reading.problems` does not mean that every declaration is known. A program that decodes chunks should also check that no declaration is unclaimed. A model's `unclaimed_declarations` lists each one, at any depth, by its location, and leaves out an extra field that says `"must_understand": false`, with everything in it, since a reader may ignore it. A reading with problems has no model, and a node with problems cannot be opened either:
 
 ```python test="true" session="parsing-validation"
 unclaimed = None if reading.metadata is None else reading.metadata.unclaimed_declarations
 can_open = unclaimed is not None and len(unclaimed) == 0
 ```
 
-To make an unknown data type or codec known, add its definition to the scope's slot and read the document again:
+To make an unknown data type or codec known, add its definition to the context's slot and read the document again:
 
 ```python test="true" session="parsing-validation"
 from zarr_metadata.definition import EmptyConfiguration
@@ -227,4 +227,4 @@ reading = read_array_metadata_v3(raw, context=context)
 
 `update` replaces each slot it is given and keeps the others. A slot can also be given as a mapping from each definition's name to it, so `CORE_AND_EXTENSIONS_CONTEXT.update(codecs={**CORE_AND_EXTENSIONS_CONTEXT.codecs, "gzip": MY_GZIP})` replaces the gzip definition with your own.
 
-[^1]: The one exception is the `r*` data type, which is identified by a templated string with no `configuration` object. This mixes the identifier with the configuration in the same JSON value, which is not good design. So this library normalizes `r*` into the same form as all the other metadata objects: the declaration `"r16"` keeps its name, and is read by the `r*` definition with the configuration `{"bits": 16}`.
+[^1]: The one exception is the [`r*` data type](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#data-types), which is identified by a templated string with no `configuration` object. This mixes the identifier with the configuration in the same JSON value, which is not good design. So this library normalizes `r*` into the same form as all the other metadata objects: the declaration `"r16"` keeps its name, and is read by the `r*` definition with the configuration `{"bits": 16}`.
diff --git a/packages/zarr-metadata/docs/pydantic.md b/packages/zarr-metadata/docs/pydantic.md
new file mode 100644
index 0000000000..3d573a4e9c
--- /dev/null
+++ b/packages/zarr-metadata/docs/pydantic.md
@@ -0,0 +1,58 @@
+# Pydantic
+
+`zarr_metadata.pydantic` is an optional integration. It requires Pydantic
+2.13 or newer, and the core package does not depend on it. Each exported
+name is a Pydantic field type over one of the models: a raw document given
+to the field goes through the same strict reader as `from_json`, and the
+value of the field is the model class itself.
+
+```python test="true" session="pydantic"
+import json
+from pydantic import BaseModel, TypeAdapter
+import zarr_metadata.pydantic as zmp
+
+with open("zarr.json", "rb") as f:
+    raw = json.load(f)
+
+adapter: TypeAdapter[zmp.ZarrV3ArrayMetadataField] = TypeAdapter(zmp.ZarrV3ArrayMetadataField)
+metadata = adapter.validate_python(raw)
+encoded = metadata.to_key_value()["zarr.json"]
+
+
+class ArrayManifest(BaseModel):
+    path: str
+    metadata: zmp.ZarrV3ArrayMetadataField
+
+
+manifest = ArrayManifest.model_validate({"path": "a/b", "metadata": raw})
+```
+
+A static type checker sees `manifest.metadata` as a
+`zarr_metadata.model.ZarrV3ArrayMetadata`. A failed read raises a Pydantic
+`ValidationError` with one line error per problem, in the format Pydantic
+uses for its own errors.
+
+## Choosing the context
+
+A field type reads its document in the context given by Pydantic's
+validation context:
+
+- If the validation context is a `Context`, every field type of that
+  format reads in it.
+- If it is a mapping, the v3 field types read in its
+  `"zarr_metadata_context"` item and the v2 field types in its
+  `"zarr_metadata_context_v2"` item.
+- If no context is given for a format, its field types read in that
+  format's default, `CORE_AND_EXTENSIONS_CONTEXT` or `CORE_V2_CONTEXT`.
+
+A field annotated `Annotated[ZarrV3ArrayMetadata, zmp.InScope(CONTEXT)]`
+is read in `CONTEXT`, whatever the validation context holds, and a model
+instance given to it is read again in `CONTEXT`.
+
+## A bare `TypeAdapter` is not a validator
+
+A `TypeAdapter` over one of the public `TypedDict`s is a **coercive**
+shape adapter, not a Zarr conformance validator; it may coerce values or
+discard fields that the strict reader rejects. It suits input built from
+Python objects, such as user-authored dicts, better than JSON read from a
+store. For JSON, use the field types above or the readers directly.
diff --git a/packages/zarr-metadata/docs/repair.md b/packages/zarr-metadata/docs/repair.md
new file mode 100644
index 0000000000..696b08bea7
--- /dev/null
+++ b/packages/zarr-metadata/docs/repair.md
@@ -0,0 +1,40 @@
+# Repairing known writer bugs
+
+The readers are strict, so a document that a known writer bug made invalid
+has problems. The repair readers in `zarr_metadata.model`
+(`read_repaired_node_metadata_v3`, `read_repaired_node_metadata_v2` and
+`read_repaired_consolidated_metadata_v2`) undo these bugs first, then read
+the result strictly, and return each change they made as a `Repair`.
+
+## Bugs the repair readers undo
+
+- A chunk length of 0 in a v3 [`regular` chunk grid](https://zarr-specs.readthedocs.io/en/latest/v3/chunk-grids/regular-grid/index.html#description), along an empty
+  dimension, which zarr-python 3.0 and 3.1 wrote, is written as 1.
+- `consolidated_metadata: null` on a v3 group, which zarr-python 3.0 and
+  3.1 wrote, is removed. The spec [requires an object](https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L802-L816).
+- The `consolidated_metadata` member that zarr-python 3 writes into each
+  `.zgroup` entry of a `.zmetadata` below the root is removed. The
+  [v2 spec](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html#groups) allows no key but `zarr_format` in a `.zgroup`.
+- A non-finite v2 fill value that zarr-python 3.0.0 to 3.0.6 wrote as a
+  bare `NaN`, `Infinity` or `-Infinity` is written as the string the
+  [v2 spec](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html#fill-value-encoding) uses, such as `"NaN"`.
+- A non-finite float or complex fill value in a v3 group's consolidated
+  metadata, which zarr-python 3.0.0 to 3.0.6 wrote as a bare token, is
+  written as the string the [v3 spec](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/data-types/index.html#permitted-fill-values) uses, such as `"NaN"`.
+
+## Bugs the repair readers do not undo
+
+A document with one of these is refused:
+
+- zarr-python 3.0.7 to 3.0.10 wrote the fill value of an `S` or `V`
+  array in a `.zmetadata` entry as a JSON array of byte values. The
+  array's own `.zarray` file holds the [base64 string](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html#fill-value-encoding) the v2 spec
+  requires, which the package reads.
+- zarr-python 3.0.7 and 3.0.8 wrote the fill value of a v2 datetime
+  array as an ISO 8601 string, not as a count of ticks.
+- zarr-python 3.0 and 3.1 wrote a chunk length of 0 in a v3 `regular`
+  chunk grid along a dimension that is not empty, for an explicit chunk
+  length of 0.
+- Some releases of zarr-python from 3.0 to 3.2 wrote a chunk length of
+  `true` in a v3 `regular` chunk grid for `chunks=True`, and some
+  releases of 3.0 and 3.1 wrote `false` for `chunks=False`.
diff --git a/packages/zarr-metadata/docs/validation-rules.md b/packages/zarr-metadata/docs/validation-rules.md
new file mode 100644
index 0000000000..a70d4265b7
--- /dev/null
+++ b/packages/zarr-metadata/docs/validation-rules.md
@@ -0,0 +1,86 @@
+# What the readers check
+
+The readers and model constructors enforce the declared document structure
+and a small set of context-free consistency rules, for example:
+
+- fixed format literals ([`zarr_format`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#zarr-format) and
+  [`node_type`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#node-type)),
+- finite JSON numbers outside `attributes` and the members nothing in the
+  context reads,
+- non-negative [dimensions](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#array-metadata-shape),
+- one [`dimension_names`](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#dimension-names) entry per array dimension.
+
+In a v3 document, validation also checks each [extension point](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#extension-points): the data
+type, the chunk grid, the chunk key encoding, each codec, and each storage
+transformer. Each one is checked by the definition that claims its name in
+a context. The context is `CORE_AND_EXTENSIONS_CONTEXT` unless a `context` is
+passed. If the definition rejects a configuration, the reader rejects it
+too, and a configuration key the definition does not declare is reported as
+`unknown_key`. If no definition in the context claims a name, the reader
+does not check that extension point, and the consumer decides whether to
+support it. The [Context](context.md) page shows this with an example.
+
+Some checks relate one part of a v3 document to another:
+
+- The [fill value](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#fill-value) is checked against the data type the document names, by
+  that data type's definition.
+- The [chunk grid](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#chunk-grids) is checked against the shape, by the grid's definition.
+- The codecs are checked as a [pipeline](https://github.com/zarr-developers/zarr-specs/blob/v3.1.0/docs/v3/core/index.rst#L931-L1024). In order, each codec's definition
+  checks the codec against the chunk it receives. This includes a
+  [shard's](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/codecs/sharding-indexed/index.html#configuration-parameters) inner codecs and index codecs.
+
+The readers do no arithmetic on values. For example, they do not check
+whether a fill value survives a `cast_value` round trip.
+
+## Decisions the spec leaves open
+
+Some choices that the spec text leaves open, or answers in two ways:
+
+- **`attributes` may hold `NaN`, `Infinity` and `-Infinity`.** The spec
+  [does not interpret attributes](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#attributes), and zarr-python and xarray write these
+  numbers there (for example, a CF `_FillValue`). The models read them,
+  and `to_key_value` writes them back as bare tokens, which a strict JSON
+  parser rejects. So may a member the spec does not define when no
+  definition in the context claims it: nothing reads it, so it is kept as
+  written. `check`, from `zarr_metadata.typed_json`, rejects a non-finite
+  number anywhere, including in attributes.
+- **A reader walks at most 256 levels of nesting.** A value nested deeper
+  is an `invalid_value` problem at the first level past the limit,
+  wherever it is. Every reader, writer and comparison uses one stack
+  frame per level, and `copy.deepcopy` (and `pickle` before Python 3.12)
+  uses two. A document at the limit therefore uses about half of the
+  interpreter's default recursion limit, and the rest is left for the
+  caller.
+- **`consolidated_metadata: null` is a problem.** A zarr-python 3.0.x bug
+  wrote it. The spec [requires an object](https://github.com/zarr-developers/zarr-specs/blob/fc7dd9c9beb5a50b87f9b08b00bf50fc0048482f/docs/v3/core/index.rst#L802-L816), and the package accepts only an
+  object. The [repair readers](repair.md) remove the key before reading.
+- **An extension name must follow the spec's [naming rule](https://github.com/zarr-developers/zarr-specs/blob/v3.1.0/docs/v3/core/index.rst#L1571-L1607)**,
+  `^[a-z][a-z0-9-_.]+$`, or be a URI, which earlier versions of the spec
+  required. Any other name is rejected before any definition is
+  consulted, so `""` and `"foo/bar"` are problems, not unknown extensions.
+- **`must_understand: false` is rejected at every extension point**,
+  including codecs and storage transformers, although the
+  [core spec](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#must-understand) names only the data type, chunk grid and chunk
+  key encoding. A reader that
+  skips a codec reads wrong bytes, just as a reader that skips a data type
+  reads wrong values. On an unknown top-level member, `must_understand`
+  keeps its meaning: a reader can skip that member.
+- **A v3 `regular` chunk grid's chunk lengths must be at least 1**, even
+  along a dimension of length 0. The [regular grid spec](https://zarr-specs.readthedocs.io/en/latest/v3/chunk-grids/regular-grid/index.html#description) says "Chunk
+  sizes must be greater than zero", a sentence added after v3.1.0 in
+  [zarr-specs#379](https://github.com/zarr-developers/zarr-specs/pull/379). The [core spec's wording](https://zarr-specs.readthedocs.io/en/v3.1.0/v3/core/index.html#concepts-and-terminology),
+  "non-zero when the corresponding dimensions of the arrays have non-zero
+  length", requires less, but does not explicitly allow anything more. So a document with a
+  chunk length of 0, which zarr-python 3.0 and 3.1 wrote for an empty
+  dimension, is rejected.
+- **A v2 datetime or timedelta dtype must have a unit**, as in `<M8[ns]`,
+  because the [v2 spec](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html#data-type-encoding) requires the unit in brackets. zarr-python 3 writes
+  `<M8` or `<m8` for a NumPy `datetime64` or `timedelta64` with no unit,
+  and the package refuses those dtypes. A codec's dtype parameter, such as
+  the `dtype` of a `delta` filter, may leave out the unit, because
+  numcodecs writes it that way and runs it.
+- **A v2 codec's dtype parameter is checked against the core v2 data
+  types**, whatever context the array is read in, because numcodecs reads
+  the parameter with NumPy. So a context that widens a data type, for
+  example to read `<f16`, does not widen what a codec's dtype parameter
+  may be.
diff --git a/packages/zarr-metadata/mkdocs.yml b/packages/zarr-metadata/mkdocs.yml
index b19c0932d2..2fa6a46e08 100644
--- a/packages/zarr-metadata/mkdocs.yml
+++ b/packages/zarr-metadata/mkdocs.yml
@@ -19,8 +19,16 @@ hooks:
 
 nav:
   - index.md
-  - Parsing / Validation: parsing-validation.md
-  - Context: context.md
+  - Guide:
+      - Parsing and validation: parsing-validation.md
+      - Context: context.md
+      - Models and readers: models.md
+      - What the readers check: validation-rules.md
+      - Consolidated metadata: consolidated-metadata.md
+      - Repairing known writer bugs: repair.md
+      - Writing an extension: extensions.md
+      - JSON Schema: json-schema.md
+      - Pydantic: pydantic.md
   - API Reference:
       - api/index.md
       - '<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code> <code>zarr_metadata.definition</code>': api/definition.md
diff --git a/packages/zarr-metadata/tests/test_docs.py b/packages/zarr-metadata/tests/test_docs.py
index 7726151126..9c1d72122b 100644
--- a/packages/zarr-metadata/tests/test_docs.py
+++ b/packages/zarr-metadata/tests/test_docs.py
@@ -71,3 +71,31 @@ def test_every_python_block_says_whether_it_runs() -> None:
         )
     ]
     assert unmarked == []
+
+
+def test_the_extensions_page_example_is_the_definition_module_docstring_example() -> None:
+    """The acme.lz4 example on the extensions page is, line for line, the example in the `zarr_metadata.definition` module docstring. Only the page's copy runs under these tests, so this is what keeps the docstring's copy from drifting."""
+    import textwrap
+
+    import zarr_metadata.definition
+
+    page_blocks = [
+        example
+        for example in _examples()
+        if example.path == PACKAGE_ROOT / "docs" / "extensions.md"
+        and example.prefix_settings().get("session") == "extensions"
+    ]
+    assert len(page_blocks) == 1, (
+        "expected exactly one extensions-session block on docs/extensions.md"
+    )
+    docstring = zarr_metadata.definition.__doc__
+    assert docstring is not None, "zarr_metadata.definition has no module docstring"
+    lines = docstring.splitlines()
+    marker = "from collections.abc import Iterator"
+    starts = [i for i, line in enumerate(lines) if line.strip() == marker]
+    assert len(starts) == 1, f"expected one line {marker!r} in the docstring, found {len(starts)}"
+    end = starts[0]
+    while end < len(lines) and (lines[end].startswith("    ") or lines[end].strip() == ""):
+        end += 1
+    docstring_example = textwrap.dedent("\n".join(lines[starts[0] : end])).strip()
+    assert page_blocks[0].source.strip().splitlines() == docstring_example.splitlines()