chore: initialize from backend template 0a6dd0e

docs/httpclient/migration-guide.md

@@ -0,0 +1,64 @@
+# Migrating from `RestTemplate`
+
+`RestTemplate` is permitted only inside `…httpclient.migration`; `RestTemplateBoundaryTest` enforces
+that. New retry, Dynamic Target, and HTTP/3 capabilities are deliberately unreachable from the
+migration path — a caller that wants them moves to a Named Client Profile.
+
+## 1. Audit before changing anything
+
+```java
+RestTemplateInventory inventory = new RestTemplateInventoryScanner().scan(existingTemplate);
+```
+
+The inventory reports the request factory, message converters, interceptors, error handler, and URI
+template handler, plus findings:
+
+| Code | Severity | Meaning |
+|---|---|---|
+| `SIMPLE_REQUEST_FACTORY` | blocking | no connection pool; unsupported in production |
+| `NO_MESSAGE_CONVERTERS` | blocking | the template cannot encode or decode a body |
+| `NO_INTERCEPTORS` | warning | confirm where correlation and timeouts are applied |
+| `TIMEOUTS_NOT_INTROSPECTABLE` | informational | declare timeouts explicitly on the target profile |
+
+## 2. Bridge without changing behaviour
+
+```java
+RestClient client = new RestTemplateToRestClientAdapter().adaptChecked(existingTemplate);
+```
+
+`adaptChecked` refuses to migrate a template with a blocking finding. The bridge carries the
+existing converters, interceptors, error handler, and URI handler across, so this step changes the
+API and nothing else.
+
+## 3. Move to a Named Client Profile
+
+Turn the platform on with `APP_HTTPCLIENT_ENABLED=true` — it ships off, and while it is off none of
+the settings below are bound — then declare the upstream as `app.httpclient.clients[N]` with its
+`name` and an explicit base URL, transport, timeouts, pool, body limits, authentication, retry
+policy, redirect policy, and TLS profile. Startup validation will tell you exactly which of those is
+missing. See `docs/httpclient/configuration-reference.md` for the environment form.
+
+## 4. Move to a typed client
+
+```java
+@HttpClientProfile("payment")
+@HttpExchange("/payments")
+public interface PaymentClient {
+
+  @PostExchange
+  @HttpOperationPolicy(
+      name = "create-payment",
+      idempotency = OperationIdempotency.IDEMPOTENCY_KEY_REQUIRED,
+      retryPolicy = "payment-write")
+  PaymentResponse create(
+      @RequestHeader("Idempotency-Key") String idempotencyKey, @RequestBody PaymentRequest request);
+}
+```
+
+The interface fails startup validation unless it declares a profile, gives every method a stable
+operation name and an explicit idempotency, supplies a key parameter when the operation requires
+one, keeps a single execution model, and does not enable retry on a non-idempotent write.
+
+## 5. Retire the template
+
+Once no production package references `RestTemplate`, `RestTemplateBoundaryTest` keeps it that way.