Document bounded output repair

docs/consumers/pkg-promptkit.md

@@ -173,6 +173,29 @@ semantics. The
 [OpenAI-compatible integration contract](../integrations/openai-compatible-chat.md)
 owns the built-in client's outbound HTTP behavior.
 
+### Repair A Structured Result
+
+Set a small additional-call budget when a structurally invalid result can be
+corrected automatically:
+
+```go
+request.Validation = &promptkit.OutputContract{
+	Format:         promptkit.FormatJSON,
+	ValidationMode: promptkit.ValidationJSONSchema,
+	SchemaPath:     "events.schema.json",
+	RepairAttempts: 1,
+}
+```
+
+Each repair attempt is another model call, so it can increase latency and
+usage; `RunResult.Usage` is cumulative and `Validation.RepairAttempts` reports
+calls actually started. Exhaustion still returns the final failed validation
+result. `basic` validation can also repair an empty candidate, but structural
+validity is not evidence of factual or domain correctness. See the
+[output-contract format reference](../formats.md#output-contract) and
+[`OutputContract` GoDoc](../../types.go) for the exact budget and eligibility
+rules.
+
 ## Inputs, Profiles, And Overrides
 
 Use `File`, `Inline`, or `InlineWithURI` to construct request inputs. A request