test/docs: add rig fallback coverage, fuzz env parsing, expand usage guide

Author: HendrikReh

PLAN.md

@@ -177,8 +177,8 @@ This living document tracks implementation progress for the LLM-Guard project, d
 
 ### Next Steps (Quick Reference)
 
-1. ⚒️ Advance Phase 7 with remaining fuzzing (streaming ingestion edge cases, LLM adapter mocks).
-2. 📘 Expand Phase 8 documentation (usage guide landing in `docs/USAGE.md` can seed the README refresh).
+1. ⚒️ Advance Phase 7 with remaining fuzzing (tail CLI edge cases, LLM mock fallbacks, health command coverage).
+2. 📘 Expand Phase 8 documentation (embed rig screenshots, add FAQ/troubleshooting, refresh README examples).
 3. 🧪 Finalise Phase 9 with refreshed CLI tests demonstrating the rig-backed providers.
 
 Keep this list in sync with the checkboxes above as you iterate.

README.md

@@ -208,11 +208,10 @@ export LLM_GUARD_API_VERSION=2024-02-15-preview
   --provider noop
 
 # Debug mode (dump raw provider verdict payloads on parse errors)
-./target/release/llm-guard scan --file samples/chat.txt --with-llm \
-  --provider anthropic --debug
+./target/release/llm-guard --debug scan --file samples/chat.txt --with-llm
 
-# Health check against configured providers (uses llm_providers.yaml if present)
-./target/release/llm-guard health --providers-config llm_providers.yaml
+# Rig-backed health diagnostics (respects llm_providers.yaml overrides)
+./target/release/llm-guard --debug health --provider openai
 ```
 
 **Streaming Mode:**

crates/llm-guard-core/src/llm/rig_adapter.rs

@@ -615,4 +615,20 @@ mod tests {
         assert!(verdict.rationale.contains("anthropic"));
         assert!(!verdict.mitigation.is_empty());
     }
+
+    #[test]
+    fn parse_verdict_returns_fallback_for_invalid_json() {
+        let verdict =
+            parse_verdict_json("not-json", "openai", "gpt-test").expect("should fallback");
+        assert_eq!(verdict.label, "unknown");
+        assert!(verdict.rationale.contains("openai"));
+    }
+
+    #[test]
+    fn truncate_adds_ellipsis_when_exceeding_limit() {
+        let long = "abcdefghijklmnopqrstuvwxyz";
+        let truncated = truncate(long, 10);
+        assert!(truncated.ends_with('…'));
+        assert_eq!(truncated.chars().count(), 11);
+    }
 }

docs/USAGE.md

@@ -472,6 +472,16 @@ llm-guard scan --file /var/log/chatbot.log --tail --with-llm --json | \
 
 ---
 
+## Rig Provider Troubleshooting
+
+- **`API key must be provided`** — Ensure `LLM_GUARD_API_KEY` (or provider profile entry) is set and non-empty. Noop provider is the only exception.
+- **`requires endpoint` (Azure)** — Supply `--endpoint` or `LLM_GUARD_ENDPOINT` pointing to your Azure resource (e.g., `https://example.openai.azure.com`).
+- **`requires deployment`** — Provide `--deployment`/`LLM_GUARD_DEPLOYMENT` or reuse `--model` as the deployment name.
+- **Empty or non-JSON verdicts** — Enable `--debug` to log raw provider responses; the rig adapter will fall back to an "unknown" verdict rather than panic.
+- **HTTP 401/403** — Regenerate API keys or confirm tenant/project values (Anthropic/Gemini frequently require project/workspace settings).
+
+---
+
 ## Related Documentation
 
 - **[README.md](../README.md)** — Project overview, features, and AI workflow insights