docs(reference): document v3.1 getDocuments v0/v1 and aggregate queries

CLAUDE.md

@@ -74,6 +74,18 @@ When updating documentation values that include GitHub source links:
 - Update the line anchor (`#L`) to match the correct line **in the branch the link points to**
 - When available, use the local platform repository checkout to verify line numbers against the correct branch
 
+## DAPI endpoint reference
+
+The DAPI endpoint reference is split between an overview page (`docs/reference/dapi-endpoints.md`) and per-section detail pages (`docs/reference/dapi-endpoints-*.md`). The authoritative list of endpoints lives in the platform proto at `https://github.com/dashpay/platform/tree/<branch>/packages/dapi-grpc/protos` — check the proto when adding or modifying entries.
+
+When you add or materially update an entry on a detail page, also update the matching row on `dapi-endpoints.md`:
+
+- Keep the description in sync between the two pages.
+- Prefix the overview row's description with `**Added in Dash Platform vX.Y.Z**` (new endpoints) or `**Updated in Dash Platform vX.Y.Z**` (modified endpoints), followed by `<br>` and the description. Use **bold** for the current release's annotations; older releases use *italics*.
+- For a whole new endpoint group, wrap the new section in a `:::{versionadded} X.Y.Z` admonition above its table — see Security Groups, Tokens, Address System, and Shielded Transactions for the pattern.
+
+For the full per-release endpoint review process (proto diff, example refresh, demoting annotations to italics), see [RELEASE.md](RELEASE.md).
+
 ## File Patterns
 
 - Documentation files: `docs/**/*.md`

RELEASE.md

@@ -0,0 +1,14 @@
+# Release Checklist
+
+Per-release tasks for the docs. For editing conventions, see [CLAUDE.md](CLAUDE.md).
+
+## DAPI endpoint review
+
+1. Diff the platform proto between the previous release tag and the current release branch — that's the source of truth for what changed. Proto source: `https://github.com/dashpay/platform/tree/<branch>/packages/dapi-grpc/protos`.
+2. For each affected endpoint, update both the detail page (`docs/reference/dapi-endpoints-*.md`) and the matching row on the overview page (`docs/reference/dapi-endpoints.md`), with the bold version annotation on the overview row.
+3. Demote the previous release's bold annotations on the overview page to italics.
+4. Re-run example requests against testnet and refresh response examples if necessary. Testnet state may have been wiped, so even unchanged endpoints may have stale data.
+
+## Update "Previous version" links
+
+Several pages (including the DAPI endpoints pages) link to the previous version of the docs. These links are not updated automatically. Search the site for "previous version" and update each link to point to the appropriate version.

conf.py

@@ -41,6 +41,7 @@
     '.DS_Store',
     'README.md',
     'CLAUDE.md',
+    'RELEASE.md',
     '.devcontainer',
     '.codex',
     '.local',

docs/protocol-ref/data-contract-document.md

@@ -328,6 +328,33 @@ The following example (from the [DPNS contract's `domain` document](https://gith
 }
 ```
 
+## Aggregate Query Flags
+
+:::{versionadded} 3.1.0
+:::
+
+Document types can opt into aggregate query support (count / sum / average) by setting flags at the document-type level. These flags control the underlying storage layout — once set on a published contract they cannot be changed by a contract update.
+
+There are two axes:
+
+* **Doctype-wide** (`documents*`) — applies the aggregate over the entire document type. Set at the document type root, alongside other doctype options like `documentsKeepHistory`.
+* **Per-index range** (`range*`) — extends the corresponding aggregate to range queries on indexed properties. Set on the index's property entry. Requires the matching base flag.
+
+| Flag | Type | Purpose | Required for |
+| - | - | - | - |
+| `documentsCountable` | Boolean | Doctype-wide counts (empty `where` or `==`/`IN` clauses on indexed fields). | `SELECT COUNT(*)` without a range clause. |
+| `rangeCountable` | Boolean | Per-index counts over a range. Requires `documentsCountable`. | `SELECT COUNT(*)` with a range clause or `GROUP BY <range_field>`. |
+| `documentsSummable` | String | Doctype-wide sums of the named integer property. | `SELECT SUM(<that property>)`. |
+| `rangeSummable` | Boolean | Per-index sums over a range. Requires `documentsSummable`. | `SELECT SUM(<field>)` with a range clause. |
+| `documentsAverageable` | String | Syntactic sugar for `documentsCountable: true` + `documentsSummable: "<prop>"`. | `SELECT AVG(<that property>)`. |
+| `rangeAverageable` | Boolean | Syntactic sugar for `rangeCountable: true` + `rangeSummable: true`. Requires `documentsAverageable`. | `SELECT AVG(<field>)` with a range clause. |
+
+The averageable flags desugar to the underlying count + sum flags during contract parsing — same on-disk layout — so authors who think in terms of averages get a single flag and downstream code paths (insert, query, estimation) stay unchanged. If both `documentsAverageable` and `documentsSummable` are set, they must name the same property.
+
+These flags are validated against the v1 document meta-schema and are rejected when applied to pre-v12 contracts. The full v1 meta-schema, including these flags, is defined [in rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/schema/meta_schemas/document/v1/document-meta.json).
+
+See the [`getDocuments` reference](../reference/dapi-endpoints-platform-endpoints.md#getdocuments) for the request/response shapes that consume these flags.
+
 ## Keyword Constraints
 
 There are a variety of keyword constraints currently defined for performance and security reasons. The

docs/protocol-ref/data-contract.md

@@ -740,7 +740,7 @@ property must be incremented if the contract is updated.
 
 ### Data Contract documents
 
-See the [data contract documents](./data-contract-document.md) page for details.
+See the [data contract documents](./data-contract-document.md) page for details, including the [aggregate query flags](./data-contract-document.md#aggregate-query-flags) that opt document types into count/sum/average queries.
 
 ### Data Contract config