Document bounded output repair

docs/formats.md

@@ -126,7 +126,7 @@ outbound integration determines its wire representation.
 | `format` | yes | `text`, `markdown`, or `json`. |
 | `validation_mode` | yes | `none`, `basic`, `json`, or `json_schema`. |
 | `schema_path` | for `json_schema` | Path to a schema in the configured schema source. |
-| `repair_attempts` | no | Integer zero or greater; omitted means zero. |
+| `repair_attempts` | no | Integer from zero through three; omitted means zero. A positive value requires `basic`, `json`, or `json_schema` validation. |
 
 The validation modes behave as follows:
 
@@ -136,9 +136,15 @@ The validation modes behave as follows:
 - `json_schema` requires valid JSON that satisfies the selected schema.
 
 `format` controls output artifact metadata. JSON Schema mode also supplies the
-schema to compatible model clients as structured-output metadata. The public
-engine does not install an output repairer, so its validation is single-pass
-even when a positive `repair_attempts` value is present.
+schema to compatible model clients as structured-output metadata. Plain `json`
+validation accepts every valid JSON value and does not request a provider-native
+JSON-object constraint.
+
+`repair_attempts` counts additional generation calls after a failed validation.
+Zero is single-pass. With a positive eligible budget, Promptkit stops at the
+first valid candidate. If the budget is exhausted, it returns the final
+candidate and its complete failed validation result; generation and operational
+validation failures remain errors. `none` never permits repair.
 
 A request-level `OutputContract` replaces the complete prompt output contract.
 It does not merge individual fields. If its format is empty, Promptkit uses