docs: take the retry duty back into the library

The GatewayUnavailableError docstring told callers to catch it and
retry later, which reads as an invitation for every downstream to write
its own retry layer. Two layers drift -- the library retunes its
backoff and the caller never hears, the caller changes its patience and
the telemetry cannot see it -- and after that nothing can answer how
long a call actually waited or how many attempts it made.

Call-level retry, backoff, source switching and cooldown waiting all
live in the library. The exception means that budget is spent. Retrying
past it is task-level retry, a different thing, and stays outside
(ARCH 7.2, single-layer retry). Also states what retry_after_s means
now and points at CIRCUIT_OPEN.

src/polygateway/errors.py

@@ -116,9 +116,20 @@ class ResultInvalidError(PolyGatewayError):
 
 
 class GatewayUnavailableError(PolyGatewayError):
-    """scope 级暂时不可用;业务侧 catch 本类做延期重投(CHS arq 模式)。
+    """scope 级暂时不可用: 库的**调用级**预算已经耗尽。
 
-    `retry_after_s` 非可选(0 = 可立即重试),承 CHS ProviderUnavailableError。
+    **职责边界(issue #14)**: 调用级的重试、退避、换源、等待冷却全部在库内,
+    不需要下游再写一层——两边各写一份必然漂移(库调了退避曲线而下游不知道,
+    下游改了等待上限而库的遥测算不进去),漂移之后"这次调用到底等了多久、
+    试了几次"就没有单一事实源答得出来。本异常表示那份预算(重试预算或 stall
+    预算)已经用完。下游据此再投是**任务级重试**,与调用级重试语义不同,由
+    业务自行在库外包(ARCH §7.2 单层重试原则)。
+
+    熔断开路时是当场抛本类还是先等冷却过去,由 `{SCOPE}__CIRCUIT_OPEN`
+    决定(缺省 fail_fast;单源 scope 建议配 wait)。
+
+    `retry_after_s` 非可选,语义是"距离**确定**可再试的时刻还有多久";
+    `0` 表示不存在确定的等待时刻(可立即重试),承 CHS ProviderUnavailableError。
     """
 
     def __init__(