docs: keep the root README focused on CLI behavior

AGENTS.md

@@ -3,7 +3,8 @@
 `CLAUDE.md` is a symlink to this file. Edit `AGENTS.md`; never replace the symlink.
 
 clickhousectl (`chctl`) is the CLI for ClickHouse and Postgres, local and in ClickHouse Cloud. Use `--help` to
-learn the current command surface. `README.md` is the user-facing doc; do not duplicate it here.
+learn the current command surface. Root `README.md` documents the CLI; the API library has its own README.
+Do not duplicate user-facing documentation here.
 
 ## Commands
 
@@ -16,7 +17,7 @@ learn the current command surface. `README.md` is the user-facing doc; do not du
   If `deprecated-fields` changed, also `cargo check --workspace --all-features`.
 
 **Done** means: `cargo fmt --all`; both clippy configurations clean; tests pass for every crate touched;
-classifier mappings updated if a file was added or renamed; `README.md` updated for user-visible behaviour;
+classifier mappings updated if a file was added or renamed; the relevant README updated for user-visible behaviour;
 work on a branch, with an associated issue and a PR.
 
 ## Workspace
@@ -181,5 +182,8 @@ Use `cargo add` with the latest version and an explicit crate, e.g. `cargo add -
 ## Git workflow and documentation
 
 - Branch per feature/issue and use the PR workflow. PRs should have an associated issue.
-- PRs should include `README.md` updates for functionality or behaviour users and developers must understand.
+- Root `README.md` sections document `clickhousectl` CLI capabilities and behaviour. Update them only for
+  functionality exposed through the CLI. API-library-only changes (including OpenAPI drift remediation) belong
+  in `crates/clickhouse-cloud-api/README.md`; do not add Rust methods, models, migration notes, or analyzer
+  changes to the root README. A library-only PR does not require a root README change.
 - Keep `AGENTS.md` up to date when development practice changes materially.

README.md

@@ -1029,9 +1029,7 @@ Upgrade-window days use `0` for Sunday, `1` for Monday, through `6` for Saturday
 Pass `--allowed-origins` on first creation or to change browser access (`'*'` explicitly allows every origin). Use `--replace-open-api-keys` with `--open-api-key` to deliberately replace the entire authorized-key list.
 The command reads the existing configuration before updating; a failed or incomplete read prevents changes to unknown fields. Avoid concurrent changes to the same query endpoint.
 
-The Rust API client's `ServiceClickhouseSettingsPatchRequest` uses a map of setting names to JSON values, and `ServiceClickhouseSettingsPatchResponse.settings` returns the applied map. The published OpenAPI now describes both fields as nonempty objects with string or integer values. Use `ServiceClickhouseSettingsPatchRequest<ServiceClickhouseSettingsMap>` and `ServiceClickhouseSettingValue` for typed requests; the default JSON-value map remains source-compatible with existing callers. Explicit `ServiceClickhouseSettingsPatchRequest<String>` callers remain supported: encoded objects are validated and serialized as objects before sending.
-
-`ServiceClickhouseSetting.value` is `Option<serde_json::Value>`: the published contract permits strings and integers. The response aliases `ServiceClickhouseSettingValueResponse` and `ServiceClickhouseSettingsMapResponse` retain arbitrary JSON to tolerate future response types. Values retain their JSON types; missing and null values remain absent. `cloud service settings get` and `list` preserve these types in `--json` output; human output displays string values without JSON quotes and numeric values as numbers.
+`cloud service settings get` and `list` preserve setting values' JSON types in `--json` output; missing and null values are omitted. Human output displays string values without JSON quotes and numeric values as numbers.
 
 `service settings schema` discovers the setting names and accepted types for a service. `settings set` changes only the names supplied: repeat `--setting NAME=JSON_VALUE`, or pass a JSON object such as `{"compatibility":"24.8","enable_analyzer":1}` with `--file` (`-` reads stdin). String values in `--setting` must retain their JSON quotes. The CLI sends settings as a JSON object and preserves each accepted value's JSON type. Numeric literals must be integers from -9223372036854775808 to 18446744073709551615; overflow, decimal and exponent literals are rejected before networking to prevent rounding. Use JSON strings for decimal or exponent values when the setting accepts them. A settings file contains the map itself, not a `{ "settings": ... }` request wrapper; malformed or empty input fails before any network request. Unknown setting names are sent to the API for validation. `settings unset` is idempotent and resets one setting to its platform default; it does not assign JSON `null`.
 

crates/clickhouse-cloud-api/AGENTS.md

@@ -3,6 +3,10 @@
 Read with the root `AGENTS.md` (commands, workspace rules, CI gates). This file covers the published API library
 and the private drift analyzer, which are always edited together.
 
+Document library capabilities, Rust caller migrations, and analyzer changes in this crate's `README.md`.
+OpenAPI drift remediation alone does not require a root `README.md` update: its feature sections describe
+CLI capabilities and behaviour, so update them only when a change is exposed through `clickhousectl`.
+
 ## Layout
 
 - `src/client.rs` — `Client` and shared HTTP machinery; endpoint methods live in private per-domain `src/client/*.rs`.

crates/clickhouse-cloud-api/README.md

@@ -32,6 +32,12 @@ Kinesis source format enums now include `Protobuf`. Set `ClickPipePostKinesisSou
 
 The beta Query API endpoint management methods are `query_api_endpoint_create`, `query_api_endpoint_get`, `query_api_endpoint_list`, `query_api_endpoint_update`, and `query_api_endpoint_delete`. Create and update take `PublicQueryApiEndpointRequest`; list accepts an optional cursor and limit (1–100) and returns `items` with `pagination.next_cursor`. User-owned endpoints can be listed and read, but cannot be updated or deleted through this API.
 
+### ClickHouse settings models
+
+`ServiceClickhouseSettingsPatchRequest` uses a map of setting names to JSON values, and `ServiceClickhouseSettingsPatchResponse.settings` returns the applied map. The published OpenAPI now describes both fields as nonempty objects with string or integer values. Use `ServiceClickhouseSettingsPatchRequest<ServiceClickhouseSettingsMap>` and `ServiceClickhouseSettingValue` for typed requests; the default JSON-value map remains source-compatible with existing callers. Explicit `ServiceClickhouseSettingsPatchRequest<String>` callers remain supported: encoded objects are validated and serialized as objects before sending.
+
+`ServiceClickhouseSetting.value` is `Option<serde_json::Value>`: the published contract permits strings and integers. The response aliases `ServiceClickhouseSettingValueResponse` and `ServiceClickhouseSettingsMapResponse` retain arbitrary JSON to tolerate future response types. Values retain their JSON types; missing and null values remain absent.
+
 ## Development
 
 ### Structure
@@ -134,7 +140,8 @@ the module trees rooted at `client.rs`, `models.rs`, and `meta.rs`, including
 private per-domain files. That same analyzer powers the scheduled live-spec
 issue, so operation, model, field, optionality, beta, deprecation, enum,
 snapshot, and stale-exemption findings share one implementation. The single
-ignored test runs the same report against the live spec.
+ignored test runs the same report against the live spec. The analyzer also checks
+inline union payload fields and request requiredness.
 
 ### Optionality exemptions