docs: surface PolyKV by name (umbrella def, §3.4 retitle, per-pool tiering semantics) — sync from git fbc32c1f3a

USAGE.md

@@ -152,7 +152,7 @@ to `.exe` (Windows needs the extension) can.
 | KV quantization (scalar) | f16 | `-ctk` / `-ctv` | capacity |
 | TurboQuant / TCQ KV tiers | off | `-ctk`/`-ctv turbo*` | capacity |
 | Auto KV-tier policy | **off** | `OPENCOTI_KV_AUTO_TIER=1` | capacity (policy) |
-| SharedKVPool | off (per request) | `shared_pool_slot` JSON field | multi-agent capacity |
+| PolyKV pool (SharedKVPool) | off (per request) | `shared_pool_slot` JSON field | multi-agent capacity |
 | Rolling-KV window / spill | **auto** (engages only under pressure) | `--vram-target`, `--kv-residency-mode` | capacity |
 | Mixed-KV spilled tail | off | `-ctkt` / `-ctvt` | capacity |
 | DCA long-context | **off** | `--dca on` | context extension |
@@ -170,7 +170,14 @@ Every boot flag also has an env twin
 
 ---
 
-## 3. KV capacity stack
+## 3. KV capacity stack — PolyKV
+
+**PolyKV** is the umbrella name for this whole stack: the compressed
+shared KV pool. Concretely it is the KV quantization tiers of §3.1
+plus the multi-agent SharedKVPool of §3.4, stacking with the
+auto-tier policy (§3.2) and the rolling-KV window (§3.3). If you
+arrived here looking for "PolyKV" from an announcement: §3.4 is the
+shared-prefix pool itself; §3.1 is what the pooled cells are made of.
 
 These four features share one goal — **fit more context / more
 sessions in fixed VRAM** — and are designed to stack. Recommended
@@ -253,7 +260,7 @@ prompt-cache-reuse are guarded off (requests bounded at `n_ctx`);
 the compute-buffer reserve for long contexts is measured
 automatically at boot (two-pass reserve — no knob).
 
-### 3.4 SharedKVPool (multi-agent shared prefix)
+### 3.4 PolyKV SharedKVPool (multi-agent shared prefix)
 
 N agents attending **one physical copy** of a common prefix (system
 prompt + tool defs). Per-request JSON, no CLI flag:
@@ -271,6 +278,23 @@ Composes with KV quantization (the pool holds quantized cells) and
 with session KV-reuse. The pool is read-only for consumers; each
 agent's divergent suffix is private.
 
+**Tiering is pinned per-pool, never per-session.** The K/V tiers —
+including the mixed-KV recent-window ⊕ compressed-tail pair — are
+properties of the boot-allocated cache tensors, chosen once at boot
+(by you or by auto-tier) before any session exists. The window/tail
+boundary is a per-layer residency budget over the *physical cell
+axis*, so a prefix cell is in the resident window or evicted (and
+quantized exactly once, on eviction) for **all** sequences
+simultaneously. Sharing itself is not copy-on-write: a sharer joins
+the prefix by adding its sequence bit to the existing cells, and a
+diverging session just appends private suffix cells — there is no
+per-session copy that could be re-quantized, and no way for two
+sessions to see the same prefix at different tiers. The flip side:
+you cannot give one session a higher-precision read of a shared
+prefix than another; that would require forking the prefix into a
+private copy, which is exactly the O(N) memory cost the pool exists
+to avoid.
+
 ---
 
 ## 4. Long context
@@ -505,12 +529,12 @@ currently appear only in the server log.
 
 ## 8. Composition matrix
 
-| | quant-KV | auto-tier | rolling-KV | SharedKVPool | DCA | sparse-attn | MTP | RYS |
+| | quant-KV | auto-tier | rolling-KV | PolyKV pool | DCA | sparse-attn | MTP | RYS |
 |---|---|---|---|---|---|---|---|---|
 | **quant-KV** | — | K-only honors | ✅ (tiles dequant-on-lift) | ✅ | ✅ | ✅ (the win case) | ✅ (turbo+MTP is the top decode combo) | ✅ |
 | **auto-tier** | | — | ✅ (it *manages* spill) | ✅ | ✅ (probes in DCA state) | ✅ | ✅ | ✅ (sizing is eff-plan-aware) |
 | **rolling-KV** | | | — | ✅ | ✅ | ✅ | ✅ | ✅ (validated: window spill × RYS on hybrid) |
-| **SharedKVPool** | | | | — | ✅ | ✅ | ✅ | untested |
+| **PolyKV pool (SharedKVPool)** | | | | — | ✅ | ✅ | ✅ | untested |
 | **DCA** | | | | | — | ✅ | ✅ (dual-ctx) | ✅ (eff→src mapped) |
 | **sparse-attn** | | | | | | — | ✅ | ✅ |
 | **MTP** | | | | | | | — | ✅ (draft runs base stack; target keeps RYS) |