docs: add Contract sections + tag tests to contract items (Tier 2 — 10 files)

org/system-model-provider.org

@@ -13,6 +13,18 @@ Providers register themselves at boot. No API key? That provider doesn't registe
 
 =*provider-cascade*= defaults to cloud-only (all providers except ~:local~ and ~:ollama~). If you want a local fallback, set ~LOCAL_BASE_URL~ in your env and add ~:local~ to the ~PROVIDER_CASCADE~ list.
 
+** Contract
+
+1. (provider-config provider): returns the configuration plist for a
+   provider keyword, or nil if unregistered.
+2. (provider-available-p provider): returns T if the provider's API key
+   or base URL is configured.
+3. (provider-openai-request prompt system-prompt &key model provider):
+   executes an OpenAI-compatible /v1/chat/completions request. Returns
+   ~(:status :success :content ...)~ or ~(:status :error :message ...)~.
+4. (provider-cascade-initialize): reads ~PROVIDER_CASCADE~ from env and
+   sets ~*provider-cascade*~.
+
 * Implementation
 
 ** Provider registry
@@ -177,12 +189,12 @@ If API-KEY is nil, reads from environment."
 (fiveam:in-suite llm-gateway-suite)
 
 (fiveam:test test-provider-rejects-bad-keyword
-  "Verify that provider-openai-request returns :error for an unregistered provider."
+  "Edge: provider-openai-request returns :error for unregistered provider."
   (let ((result (provider-openai-request "hello" "test" :provider :not-a-real-provider)))
     (fiveam:is (eq (getf result :status) :error))))
 
 (fiveam:test test-provider-config-registered
-  "A registered provider should return its configuration plist."
+  "Contract: provider-config returns configuration plist for registered provider."
   (let ((config (provider-config :openrouter)))
     (fiveam:is (listp config))
     (fiveam:is (getf config :base-url))))