MPT-24259 Write the streaming guide in docs/streaming.md

AGENTS.md

@@ -25,6 +25,7 @@ When applicable, read the repository documentation in this order:
 7. `docs/documentation.md` — repository-specific documentation rules
 8. `docs/unit_tests.md` — unit test structure and guidance
 9. `docs/e2e_tests.md` — end-to-end test setup and execution
+10. `docs/streaming.md` — streaming read mode, consumer obligations, and timeouts
 
 Then inspect the code paths relevant to the task:
 

README.md

@@ -19,6 +19,7 @@ Start with these documents:
 - [docs/e2e_tests.md](docs/e2e_tests.md): end-to-end test setup and execution
 - [docs/contributing.md](docs/contributing.md): repository-specific workflow and links to shared standards
 - [docs/documentation.md](docs/documentation.md): repository-specific documentation rules
+- [docs/streaming.md](docs/streaming.md): streaming guide — `stream()` versus `iterate()`, consumer obligations, and timeouts
 - [docs/rql.md](docs/rql.md): fluent RQL query builder guide
 - [MPT OpenAPI Spec](https://api.s1.show/public/v1/openapi.json): upstream API contract
 

docs/architecture.md

@@ -154,8 +154,9 @@ streaming read mode on a regular collection route and require the API to echo th
 `MPT-Streaming` response header, raising `MPTStreamingNotEnabledError` when it does not. They
 also verify completeness: the declared `MPT-Item-Count` is read before the first record —
 raising `MPTStreamingItemCountMissingError` when absent or unusable — and compared with the
-yielded record count once the body is fully consumed, raising `MPTStreamingIncompleteError`
-on mismatch. An iterator closed early skips the comparison. A record marked with
+count of raw records consumed once the body is fully consumed, raising
+`MPTStreamingIncompleteError` on mismatch. The count is taken before `skip_deleted` withholds
+any stub, so a filtered stub still counts. An iterator closed early skips the comparison. A record marked with
 `$meta.deleted` is a deletion stub rather than data, and is yielded as a `DeletionStub`
 instead of a model, so it still counts towards the declared item count but cannot be ingested
 as a record. A consumer that ingests no deletions can opt out with the keyword-only
@@ -185,6 +186,9 @@ unchanged, omitting whichever is unset. Validating them locally is deliberately
 the server owns pagination-input validation, and the inputs it accepts in streaming mode are
 still changing.
 
+See [the streaming guide](streaming.md) for the consumer-facing contract these mixins
+implement.
+
 Example service definition:
 
 ```python
@@ -216,8 +220,8 @@ Transport-level settings (`base_url`, `timeout`, `retries`) are grouped in the
 constructors as `transport=TransportSettings(...)`. Timeouts resolve per connection phase:
 `connect_timeout`, `read_timeout`, `write_timeout` and `pool_timeout` each fall back to
 `timeout`, and the dataclass exposes two profiles — `request_timeout` for regular requests and
-`stream_timeout`, which substitutes the longer `stream_read_timeout` for the read phase because
-a streamed response defers its first byte until the server has built the result set. To resolve the base URL from the
+`stream_timeout`, whose read phase is the larger of `stream_read_timeout` and `read_timeout`,
+because a streamed response defers its first byte until the server has built the result set. To resolve the base URL from the
 `MPT_API_BASE_URL` environment variable instead, pass `EnvTransportSettings()` (the
 default when no transport is given); the clients themselves never read the environment.
 The resolved settings are handed to the authentication provider through
@@ -254,6 +258,7 @@ Client, transport, and API errors use the following hierarchy:
 MPTError
 ├── MPTStreamingError                       # base for streaming-mode failures
 │   ├── MPTStreamingNotEnabledError         # response did not confirm streaming mode
+│   ├── MPTStreamingFormatMismatchError     # Content-Type differed from the requested format
 │   ├── MPTStreamingItemCountMissingError   # no usable MPT-Item-Count declared
 │   ├── MPTStreamingIncompleteError         # record count differed from MPT-Item-Count
 │   └── MPTStreamingTruncatedError          # body ended before the HTTP message completed

docs/documentation.md

@@ -13,13 +13,20 @@ This file documents repository-specific documentation rules only.
 - Topic-specific documentation must live in the matching file under [`docs/`](.).
 - Shared engineering rules must be linked from `mpt-extension-skills` instead of copied into this repository.
 - When changing setup, usage, testing, or architecture behavior, update the corresponding document in the same change.
-- `docs/usage.md` is the source of truth for installation, configuration, examples, and supported command entry points.
+- `docs/usage.md` is the source of truth for installation, configuration, general usage
+  examples, and supported command entry points.
+- `docs/streaming.md` is the source of truth for the streaming read mode: when to stream,
+  the wire formats, consumer obligations, timeouts, and streaming examples. `docs/usage.md`
+  carries only a short orientation and links here, so streaming guidance must not be
+  duplicated there.
 
 ## Current Documentation Map
 
 - [`README.md`](../README.md): overview, quick start, and documentation map
 - [`AGENTS.md`](../AGENTS.md): AI-agent entry point and reading order
 - [`usage.md`](usage.md): install, configure, and use the client
+- [`streaming.md`](streaming.md): streaming read mode — access pattern, wire formats,
+  consumer obligations, and timeouts
 - [`architecture.md`](architecture.md): repository structure and major abstractions
 - [`local-development.md`](local-development.md): Docker-only local setup and execution
 - [`testing.md`](testing.md): repository-specific testing strategy