From c12bb4d55dda41a5319e3881b2caae7cae920f16 Mon Sep 17 00:00:00 2001
From: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
Date: Wed, 8 Jul 2026 18:18:32 -0700
Subject: [PATCH] docs: document multi-instance provider configuration

Add a new section to README explaining how end users configure multiple
instances of the same provider type (e.g., two Anthropic accounts with
distinct credentials) via the interactive wizard. This documents the
capability that was implemented and shipped in PR #225.

Closes documentation gap for multi-instance provider instance feature.
Generated with [Amplifier](https://github.com/microsoft/amplifier)
Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 README.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/README.md b/README.md
index 8a6cab06..373a7078 100644
--- a/README.md
+++ b/README.md
@@ -294,6 +294,33 @@ Existing installations inherit these canonical URIs at runtime as well, so
 fresh environments download the provider code via **uv** automatically. No
 manual source overrides are required for the built-in providers.
 
+### Configuring multiple instances of the same provider
+
+You can configure more than one instance of the same provider type — for
+example, two Anthropic accounts/tiers, each with its own API key.
+
+1. Run the wizard: `amplifier init` (or `amplifier provider manage` in an
+   existing project).
+2. Pick your scope first (`[w]`): `global` (your defaults everywhere),
+   `project` (team-shared, committed to git), or `local` (this machine only,
+   gitignored).
+3. Add your first instance (`[a]` → provider type, e.g. Anthropic), give it
+   an id (e.g. `anthropic-standard`), and let the wizard pick up its key from
+   the environment (e.g. `ANTHROPIC_API_KEY`) if it's already set.
+4. Add a second instance of the same type (`[a]` again) with a **different**
+   id (e.g. `anthropic-fable`). The wizard detects that the default
+   credential is already claimed and asks which env var this instance should
+   use instead — it will offer an already-set, unclaimed env var (e.g.
+   `ANTHROPIC_FABLE_API_KEY`) as the default, or suggest a name you can
+   accept or edit.
+5. Use `[p]` (Reorder priorities) to control which instance is used by
+   default.
+
+Each instance keeps its own real, named credential — never a shared or
+overwritten key, and never a plaintext secret in `settings.yaml` (real values
+live only in `~/.amplifier/keys.env`). Editing an instance later and keeping
+its existing key won't reset it back to a shared default.
+
 ## Development
 
 ### Prerequisites