docs: clarify README and fix accuracy nits

- Add Wiring governance to TOC; reorder providers extras table to match
  install order in Quick start.
- Pull Judge selection rules to the top of Quick start so they apply to
  every provider example below.
- Restructure provider sections so each example has a coherent judge
  setup (cross-judge env in Anthropic/Gemini/Bedrock/HF/HTTP, explicit
  --judge-* flags for OpenRouter/Azure, single-key self-judge for
  LangChain).
- Fix typo: "Fives" -> "Five" example fixtures.
- Drop bogus "90 lines" count for smoke_tiny.yaml (it's 88).
- Tighten "ifixai list fixtures" comment in CLI reference -- the command
  only lists registered named fixtures; example fixtures load by path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: n-papaioannou

README.md

@@ -56,13 +56,14 @@ and track over time.
 5. [Five scorecard pillars](#five-scorecard-pillars)
 6. [Domain-neutral fixtures](#domain-neutral-fixtures)
 7. [Author your own fixture](#author-your-own-fixture)
-8. [Supported providers](#supported-providers)
-9. [CLI reference](#cli-reference)
-10. [Scoring](#scoring)
-11. [Python API](#python-api)
-12. [Development](#development)
-13. [Contact](#contact)
-14. [License](#license)
+8. [Wiring governance](#wiring-governance)
+9. [Supported providers](#supported-providers)
+10. [CLI reference](#cli-reference)
+11. [Scoring](#scoring)
+12. [Python API](#python-api)
+13. [Development](#development)
+14. [Contact](#contact)
+15. [License](#license)
 
 ## Requirements
 
@@ -73,10 +74,10 @@ and track over time.
 |---|---|---|
 | *(none)* | Core only | `mock`, `http`, `langchain` (you must `pip install langchain` yourself) |
 | `openai` | `openai` SDK | `openai` |
-| `azure` | `openai` SDK | `azure` (same client; set `--endpoint` to your Azure OpenAI resource) |
-| `openrouter` | `openai` SDK (OpenRouter exposes an OpenAI-compatible endpoint; any compatible SDK or `--provider http` also works) | `openrouter` |
 | `anthropic` | `anthropic` SDK | `anthropic` |
+| `openrouter` | `openai` SDK (OpenRouter exposes an OpenAI-compatible endpoint; any compatible SDK or `--provider http` also works) | `openrouter` |
 | `gemini` | `google-generativeai` | `gemini` |
+| `azure` | `openai` SDK | `azure` (same client; set `--endpoint` to your Azure OpenAI resource) |
 | `bedrock` | `boto3` | `bedrock` |
 | `huggingface` | `huggingface-hub` | `huggingface` |
 | `dev` | Lint, types, tests, security | [Contributing](CONTRIBUTING.md) only |
@@ -96,6 +97,12 @@ The CLI does **not** auto-read the SUT API key from the environment: pass **`--a
 
 Omitting `--fixture` uses the built-in **default** fixture. Runs emit a scorecard under `./ifixai-results/` (override with `--output`). Typical wall time is a few minutes on broadband.
 
+**Judge selection:**
+- **Default:** judge = any non-SUT provider key in your env, run on that provider's default model.
+- **Multiple keys:** tiebreaker order is `anthropic → openai → gemini → openrouter → azure → bedrock → huggingface`.
+- **No non-SUT key:** pass `--eval-mode self`, or the run refuses.
+- **Override:** `--judge-provider` / `--judge-api-key` / `--judge-model`.
+
 ### 0 — Mock (no cloud keys)
 
 ```bash
@@ -120,34 +127,37 @@ Single key only (self-judge):
 ifixai run --provider openai --api-key "$OPENAI_API_KEY" --eval-mode self
 ```
 
-### 2 — OpenRouter
+### 2 — Anthropic
 
 ```bash
-pip install -e ".[openrouter]"    # installs openai SDK; OpenRouter is OpenAI-compatible — other compatible SDKs or --provider http work too
-export OPENROUTER_API_KEY=sk-or-...
+pip install -e ".[anthropic]"
 export ANTHROPIC_API_KEY=sk-ant-api03-...
-ifixai run --provider openrouter --api-key "$OPENROUTER_API_KEY" --model openai/gpt-4o
+export GEMINI_API_KEY=...   # second provider for cross-judge (or use --eval-mode self)
+ifixai run --provider anthropic --api-key "$ANTHROPIC_API_KEY" --model claude-sonnet-4-20250514
 ```
 
-### 3 — Anthropic
+### 3 — OpenRouter (explicit judge)
 
 ```bash
-pip install -e ".[anthropic]"
+pip install -e ".[openrouter]"    # installs openai SDK; OpenRouter is OpenAI-compatible — other compatible SDKs or --provider http work too
+export OPENROUTER_API_KEY=sk-or-...
 export ANTHROPIC_API_KEY=sk-ant-api03-...
-export OPENAI_API_KEY=sk-...
-ifixai run --provider anthropic --api-key "$ANTHROPIC_API_KEY" --model claude-sonnet-4-20250514
+ifixai run --provider openrouter --api-key "$OPENROUTER_API_KEY" --model openai/gpt-4o \
+  --judge-provider anthropic --judge-api-key "$ANTHROPIC_API_KEY" --judge-model claude-sonnet-4-20250514
 ```
 
+Pinning the judge avoids the underlying-model collision OpenRouter routing can introduce (e.g. routing the SUT to an Anthropic model while Anthropic is also the auto-judge).
+
 ### 4 — Google Gemini
 
 ```bash
 pip install -e ".[gemini]"
 export GEMINI_API_KEY=...    # or GOOGLE_API_KEY
-export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-api03-...   # second provider for cross-judge (or use --eval-mode self)
 ifixai run --provider gemini --api-key "$GEMINI_API_KEY"
 ```
 
-### 5 — Azure OpenAI
+### 5 — Azure OpenAI (explicit judge)
 
 ```bash
 pip install -e ".[azure]"          # or .[openai] — same OpenAI-compatible SDK
@@ -156,7 +166,8 @@ export ANTHROPIC_API_KEY=sk-ant-api03-...
 ifixai run --provider azure \
   --endpoint https://YOUR_RESOURCE.openai.azure.com/ \
   --api-key "$AZURE_OPENAI_API_KEY" \
-  --model YOUR_DEPLOYMENT_NAME
+  --model YOUR_DEPLOYMENT_NAME \
+  --judge-provider anthropic --judge-api-key "$ANTHROPIC_API_KEY" --judge-model claude-sonnet-4-20250514
 ```
 
 ### 6 — AWS Bedrock
@@ -165,7 +176,7 @@ ifixai run --provider azure \
 pip install -e ".[bedrock]"
 export AWS_ACCESS_KEY_ID=...
 export AWS_SECRET_ACCESS_KEY=...
-export OPENAI_API_KEY=sk-...
+export GEMINI_API_KEY=...   # second provider for cross-judge (or use --eval-mode self)
 ifixai run --provider bedrock --api-key not-used \
   --model anthropic.claude-3-5-sonnet-20240620-v1:0
 ```
@@ -177,7 +188,7 @@ Authentication uses the **standard AWS credential chain** (env vars or instance
 ```bash
 pip install -e ".[huggingface]"
 export HF_TOKEN=hf_...
-export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-api03-...   # second provider for cross-judge (or use --eval-mode self)
 ifixai run --provider huggingface --api-key "$HF_TOKEN" --model meta-llama/Llama-3.1-8B-Instruct
 ```
 
@@ -187,7 +198,7 @@ ifixai run --provider huggingface --api-key "$HF_TOKEN" --model meta-llama/Llama
 
 ```bash
 pip install -e "."
-export OPENAI_API_KEY=sk-...
+export GEMINI_API_KEY=...   # second provider for cross-judge (or use --eval-mode self)
 ifixai run --provider http \
   --endpoint http://localhost:8000/v1 \
   --api-key YOUR_SERVER_TOKEN \
@@ -196,13 +207,13 @@ ifixai run --provider http \
 
 Optional JSON headers: set **`IFIXAI_EXTRA_HEADERS`** to a JSON object (see `ifixai/providers/http.py`).
 
-### 9 — LangChain
+### 9 — LangChain (single-key self-judge)
 
 ```bash
 pip install -e "."
 pip install langchain          # not bundled as a named extra
-export OPENAI_API_KEY=sk-...
-ifixai run --provider langchain --api-key "$OPENAI_API_KEY"
+export OPENAI_API_KEY=sk-...    # one key only — SUT and judge share the same model
+ifixai run --provider langchain --api-key "$OPENAI_API_KEY" --eval-mode self
 ```
 
 Wire your chain inside the LangChain adapter as documented in the provider module.
@@ -269,7 +280,7 @@ attestation facility (no inspections use it today), B28 RAG context integrity, a
 ## Domain-neutral fixtures
 
 Test code is domain-neutral. Industry knowledge lives in user-authored
-fixture YAML — never in test code. Fives example fixtures live under
+fixture YAML — never in test code. Five example fixtures live under
 [`ifixai/fixtures/examples/`](ifixai/fixtures/examples/):
 
 ```bash
@@ -292,7 +303,7 @@ Your domain knowledge (roles, users, tools, permissions, policies) lives in
 a fixture file (YAML or JSON). The fastest path:
 
 ```bash
-# Start from the smallest valid fixture (90 lines, every required key populated)
+# Start from the smallest valid fixture (every required key populated)
 cp ifixai/fixtures/smoke_tiny.yaml my-fixture.yaml
 
 # Edit roles, users, tools, permissions to match your system
@@ -375,7 +386,7 @@ ifixai init                    # check env for provider keys, suggest a first ru
 ifixai run                     # run tests (Standard or Full mode)
 ifixai run --fixture FILE      # run with a custom fixture (YAML or JSON)
 ifixai list tests              # list all 32 tests
-ifixai list fixtures           # list built-in fixtures
+ifixai list fixtures           # list registered named fixtures (examples/ are loaded by path)
 ifixai validate                # validate the per-test layout (32 folders)
 ifixai validate FILE           # validate a fixture against schema.json
 ifixai compare A B             # diff two scorecard reports