Document structured capacity errors

docs/roadmap/capacity-errors.md

@@ -1,6 +1,6 @@
 # Structured Capacity Errors
 
-**Status:** Accepted.
+**Status:** Complete.
 
 ## Purpose
 

docs/roadmap/future.md

@@ -33,9 +33,7 @@ consumers.
 
 ## Ideas
 
-Structured capacity errors have been selected for active planning in the
-[focused feature roadmap](capacity-errors.md). No other ideas currently await
-selection.
+No ideas currently await selection.
 
 ## Entry Format
 

docs/roadmap/implementation.md

@@ -1,6 +1,6 @@
 # Structured Capacity Errors Implementation Plan
 
-**Status:** Ready for implementation.
+**Status:** Complete.
 
 ## Purpose
 

docs/roadmap/notarius-promptkit-wishlist.md

@@ -205,8 +205,8 @@ resolution.
 
 ## Priority 4: Structured Capacity Errors
 
-**Disposition:** Accepted into the
-[structured capacity errors](capacity-errors.md) feature roadmap.
+**Disposition:** Implemented behavior. See the consumer guide's
+[Handle Errors](../consumers/pkg-promptkit.md#handle-errors) section.
 
 ### Downstream need
 
@@ -215,46 +215,16 @@ provider-neutral application error. When multiple backends are active,
 operators would benefit from knowing which backend rejected admission without
 parsing an error string or exposing endpoint details.
 
-### Current integration
+### Implemented behavior
 
-PromptKit provides the useful `ErrCapacityExceeded` sentinel. Notarius can
-classify the failure reliably, but it retains only a sanitized diagnostic
-string as additional context.
-
-### Requested capability
-
-Add a typed error that continues to match `ErrCapacityExceeded`:
-
-```go
-type CapacityError struct {
-	BackendID string
-}
-
-func (e *CapacityError) Is(target error) bool {
-	return target == ErrCapacityExceeded
-}
-```
-
-The exact implementation may use `Unwrap` or another idiomatic mechanism. The
-important properties are compatibility with `errors.Is` and discoverability
-through `errors.As`.
-
-### Design considerations
-
-- Include the stable backend ID.
-- Do not expose the backend endpoint, credential environment, credential
-  value, request content, or other sensitive configuration.
-- Consider including the configured concurrency and queue limits if they are
-  useful and safe, but backend identity alone provides most of the downstream
-  value.
-- Add a retry delay only if PromptKit can provide a meaningful value. A full
-  queue does not necessarily imply a reliable `Retry-After` duration.
-- Keep retry and backoff policy with the consuming application. PromptKit
-  should classify the admission failure rather than silently retry it.
+PromptKit now retains the broad capacity classification while allowing
+Notarius to obtain the selected backend ID without parsing diagnostic text.
+The consumer guide owns the application workflow, including retry and backoff
+policy.
 
 ### Value to Notarius
 
-This would improve operational diagnostics and future metrics while preserving
+This improves operational diagnostics and future metrics while preserving
 the provider-neutral error boundary used by Notarius.
 
 ## Capabilities PromptKit Already Provides Well
@@ -311,7 +281,8 @@ Notarius would be:
 1. Add atomic execution that returns prepared details and the completed result.
 2. Add a semantic execution-target digest, preferably alongside profile
    inspection.
-3. Add a typed capacity error carrying backend identity.
+3. Use the implemented typed capacity error where backend admission diagnostics
+   are needed.
 
 The first addresses a concrete execution workaround. The second would improve
 checkpoint correctness and reduce coupling. The third is operational polish.

docs/roadmap/weatherreporter-promptkit-wishlist.md

@@ -282,18 +282,16 @@ the existing sentinel remain available.
 
 ### Structured Capacity Errors
 
-**Disposition:** Accepted into the
-[structured capacity errors](capacity-errors.md) feature roadmap.
+**Disposition:** Implemented behavior. See the consumer guide's
+[Handle Errors](../consumers/pkg-promptkit.md#handle-errors) section.
 
-The typed capacity error proposed by the
-[Notarius wishlist](notarius-promptkit-wishlist.md#priority-4-structured-capacity-errors)
-would improve Weatherreporter diagnostics by exposing the stable backend ID
-without parsing error text.
+PromptKit now exposes the stable backend ID for capacity rejection without
+requiring Weatherreporter to parse error text.
 
 Weatherreporter currently generates batch reports sequentially and constructs
 one engine per invocation, so engine-local capacity exhaustion is unlikely in
-the initial design. The feature would become more valuable if report
-generation later becomes concurrent or PromptKit engines become longer-lived.
+the initial design. The typed error becomes more valuable if report generation
+later becomes concurrent or PromptKit engines become longer-lived.
 It should not block adoption.
 
 ### Semantic Execution-Target Fingerprints
@@ -364,8 +362,8 @@ Weatherreporter would be:
 2. Consider eager source validation after evaluating whether the two exact
    inspection APIs are sufficient.
 3. Add structured generation errors.
-4. Add structured capacity errors and semantic execution-target fingerprints
-   as lower-priority operational improvements.
+4. Use structured capacity errors and consider semantic execution-target
+   fingerprints as lower-priority operational improvements.
 
 The first item removes the only material integration workaround. Prompt and
 profile inspection improve fail-fast validation. The remaining items improve