docs: explain named provider instances

[shivros]

Summary

Documents the already-implemented named provider-instance contract for agents and operators:

• default + named TOML structure and exact IRIS_<TYPE>__<INSTANCE>__<FIELD> convention;
• backward-compatible default email environment variables;
• discovery through /providers / iris providers, provider_instance attribution, and explicit send_message.provider routing.

Validation

• cargo test -p iris-providers — 104 passed
• cargo build --all-targets
• cargo test --all-targets — 214 passed
• cargo clippy --all-targets -- -D warnings
• cargo fmt --all -- --check
• cargo run -p iris-codegen --bin iris-codegen -- check
• git diff --check

Scope boundary

No production configuration, credentials, deployment, release, or live mailbox validation is included. The deployed instance remains on the legacy provider configuration; this PR makes the merged multi-instance contract usable and discoverable.

[shivros]

🤖 Automated Review Panel

Reviewer A — GPT-5.6-terra

Finding (fixed): The initial text did not show how a discovered instance ID maps into a concrete request. Added /providers response-shape and send_message body examples.

Reviewer B — independent review

APPROVE. The documentation accurately describes the named-instance TOML/env convention, default compatibility, discoverability, and explicit routing.

Both reviewers assessed the task goal: agent-visible, provider-agnostic named instance configuration without credential disclosure.

[shivros]

Auto-Merge Gate — approved

Confidence: 0.93

This focused documentation PR accurately describes the already-implemented named-provider-instance contract: configuration, backward-compatible default environment variables, discovery, attribution, and explicit routing. It changes only README.md; the review panel found and corrected the initial discoverability gap before approval.

Checks observed: Test, Format Check, Clippy, Secret Scan, Dependency Audit, and Creed context drift — all successful.

Scope limit: This approval covers the documentation slice only. It does not claim a production configuration, release, deployment, or live mailbox validation; those remain tracked in COD-457.