docs+test: add TEST-282/TEST-283 for REQ-263/REQ-265; update README + LEDGER

REQ coverage gaps fixed:
- TEST-282 (TestHFSyncPersistsBucketScores): verifies sync_from_huggingface_blocking
  creates scores.json with 'bucket_scores' dict; each entry has reasoning_score,
  conversational_score, longform_score, model_name keys
- TEST-283 (TestHFTokenInHeaders): verifies SPECSMITH_HF_TOKEN sets token_set=True,
  rate_limit_tier contains 'authenticated', and Authorization: Bearer header is
  captured in mocked _fetch_page request

Governance state:
- docs/TESTS.md: TEST-282 and TEST-283 entries added (REQ-263, REQ-265)
- .specsmith/testcases.json: synced 258 -> 260 entries
- docs/LEDGER.md: WI-0512-AI (REQ-263..REQ-281) and WI-0512-GAPS entries added

Documentation:
- README.md: added 'AI Model Intelligence' section covering HF leaderboard sync,
  model capability profiles, LLM client fallback, endpoint presets, suggest-profiles,
  Kairos bucket score columns; updated 50+ CLI commands list

All 31 test_ai_intelligence.py tests pass; ruff clean.

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: tbitcs

.specsmith/testcases.json

@@ -2628,6 +2628,28 @@
     "expected_behavior": {},
     "confidence": 1.0
   },
+  {
+    "id": "TEST-282",
+    "title": "HF Leaderboard Sync Persists Bucket Scores to JSON",
+    "description": "`sync_from_huggingface_blocking(force_static=True, scores_path=tmp_path/\"scores.json\")` creates the file at the given path, whose JSON root contains a `\"bucket_scores\"` dict. Each entry has `reasoning_score`, `conversational_score`, `longform_score`, and `model_name` keys.",
+    "requirement_id": "REQ-263",
+    "type": "unit",
+    "verification_method": "pytest",
+    "input": {},
+    "expected_behavior": {},
+    "confidence": 1.0
+  },
+  {
+    "id": "TEST-283",
+    "title": "HF Token Included in Request Headers When Set",
+    "description": "When `SPECSMITH_HF_TOKEN` is set to a non-empty string, `test_hf_connection()` returns `{\"token_set\": true}` and the rate_limit_tier includes \"authenticated\". The `_fetch_page` request (captured via mock) includes `Authorization: Bearer <token>` in its headers.",
+    "requirement_id": "REQ-265",
+    "type": "unit",
+    "verification_method": "pytest",
+    "input": {},
+    "expected_behavior": {},
+    "confidence": 1.0
+  },
   {
     "id": "TEST-263",
     "title": "HF Leaderboard Static Fallback Loads Without Network",

README.md

@@ -477,6 +477,92 @@ requirement, test, and work-item identifiers Specsmith assigned.
 
 ---
 
+## AI Model Intelligence
+
+specsmith ships a complete AI model intelligence layer for tracking, scoring, and routing
+to the best available LLM for each task type.
+
+### HF Open LLM Leaderboard Sync (REQ-263..REQ-269)
+
+Syncs benchmark data from the HuggingFace Open LLM Leaderboard and computes three
+task-specific bucket scores — **reasoning**, **conversational**, and **longform** — for
+every model. A 40+ model static fallback ensures scores are always available even without
+network access.
+
+```bash
+specsmith model-intel sync                  # sync from HF leaderboard (static fallback if offline)
+specsmith model-intel scores                # list all cached bucket scores
+specsmith model-intel scores --model gpt-4o # show scores for a specific model
+specsmith model-intel recommendations       # top-10 models for reasoning bucket
+specsmith model-intel recommendations --bucket conversational  # or longform
+specsmith model-intel connection            # test HF API connectivity + token status
+```
+
+Set `SPECSMITH_HF_TOKEN` for authenticated access (1000 req/5min instead of 500).
+Scores persist to `~/.specsmith/model_scores.json`. Background sync runs 15s after startup
+then daily.
+
+**Bucket formulas (normalised 0-100):**
+- Reasoning = 0.35×MATH + 0.30×GPQA + 0.25×BBH + 0.10×IFEval
+- Conversational = 0.40×IFEval + 0.35×MMLU-PRO + 0.25×BBH
+- Longform = 0.35×MUSR + 0.35×IFEval + 0.30×MMLU-PRO
+
+### Model Capability Profiles (REQ-270..REQ-271)
+
+40+ pre-built model profiles cover all major providers (OpenAI, Anthropic, Google, Mistral,
+Meta Llama, Qwen, DeepSeek, and local Ollama variants). Each profile specifies:
+`max_tokens`, `prompt_style` (sections/xml/markdown), `supports_vision`,
+`supports_tool_calls`, `reasoning_mode`, and `context_window`.
+
+Context-aware history trimming preserves system messages while summarising older turns when
+the token budget is exceeded:
+
+```python
+from specsmith.agent.model_profiles import get_profile, trim_history
+
+profile = get_profile("qwen2.5:14b")   # exact or prefix match; returns default if unknown
+messages = trim_history(messages, budget_chars=12000)
+```
+
+### LLM Client with Provider Fallback (REQ-275..REQ-277)
+
+`LLMClient` wraps multiple providers with automatic fallback on 429 / 401 errors,
+O-series parameter translation (`max_completion_tokens`, temperature=1, developer role),
+and vLLM guided-JSON payload injection:
+
+```python
+from specsmith.agent.llm_client import LLMClient
+
+client = LLMClient([
+    {"provider_type": "cloud", "model": "gpt-4o", ...},
+    {"provider_type": "ollama", "model": "qwen2.5:14b", ...},  # local fallback
+])
+result = client.chat([{"role": "user", "content": "hello"}])
+```
+
+### Endpoint Presets + Suggest Profiles (REQ-278..REQ-280)
+
+A registry of 10+ pre-configured endpoint presets for common cloud and local LLM providers:
+
+```bash
+specsmith agent endpoint-presets            # list all presets (vllm, lm_studio, openrouter, etc.)
+specsmith agent endpoint-presets --json     # machine-readable output
+specsmith agent suggest-profiles            # suggest optimal profiles based on env (API keys, hardware)
+specsmith agent suggest-profiles --json     # structured suggestions with bucket/role annotations
+```
+
+Suggestions are read-only (never persisted) and inspect `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
+`GOOGLE_API_KEY`, and local Ollama availability.
+
+### Kairos AI Providers — Bucket Score Columns (REQ-281)
+
+The Kairos **Agents > AI Providers** table gained three new columns — **R** (reasoning),
+**C** (conversational), **L** (longform) — showing each provider's HF bucket scores inline.
+A **Sync Scores** button triggers a background sync from the HF leaderboard without
+interrupting the active session.
+
+---
+
 ## Kairos — Flagship Terminal Client
 
 **[Kairos](https://github.com/BitConcepts/kairos)** is the recommended terminal client for specsmith.
@@ -556,7 +642,9 @@ Supported tools: **Synthesis:** vivado, quartus, radiant, diamond, gowin.
 
 **Workflow:** `phase show/set/next/list` `ledger add/list` `req list/add/gaps/trace`
 
-**Agent:** `run` `agent run/plan/status/verify/improve/reports` `agent providers/tools/skills`
+**Agent:** `run` `agent run/plan/status/verify/improve/reports` `agent providers/tools/skills` `agent suggest-profiles` `agent endpoint-presets`
+
+**Model Intel:** `model-intel sync` `model-intel scores` `model-intel recommendations` `model-intel connection`
 
 **Ollama:** `ollama list/available/gpu/pull/suggest`
 

docs/LEDGER.md

@@ -122,3 +122,21 @@
 - **REQs affected**: REQ-248,REQ-249,REQ-250,REQ-251,REQ-252,REQ-253,REQ-254,REQ-255,REQ-256,REQ-257,REQ-258,REQ-259,REQ-260,REQ-261,REQ-262
 - **Status**: complete
 - **Chain hash**: auto
+
+
+## 2026-05-12T13:00 --- WI-0512-AI: Glossa-lab AI patterns ported to specsmith (REQ-263..REQ-281)
+- **Author**: oz-agent
+- **Type**: feature
+- **REQs affected**: REQ-263,REQ-264,REQ-265,REQ-266,REQ-267,REQ-268,REQ-269,REQ-270,REQ-271,REQ-272,REQ-273,REQ-274,REQ-275,REQ-276,REQ-277,REQ-278,REQ-279,REQ-280,REQ-281
+- **Description**: Ported 7 AI intelligence systems from glossa-lab: HF Open LLM Leaderboard sync with paginated fetch, bucket scoring (reasoning/conversational/longform), static fallback, and CLI (`model-intel scores/sync/recommendations/connection`); 40+ model capability profiles with context-aware history trimming; LLMClient with O-series parameter translation, vLLM guided-JSON, and provider fallback; EMA-based rate limit scheduler with adaptive concurrency; endpoint preset registry (10+ presets) with `/api/model-intel/*` REST endpoints; `agent suggest-profiles` and `agent endpoint-presets` CLI commands; Kairos AI Providers page bucket score columns and Sync Scores button. ARCHITECTURE.md §21-27 added. 280 REQs, 258 TESTs. All CI green.
+- **Status**: complete
+- **Chain hash**: auto
+
+
+## 2026-05-12T13:06 --- WI-0512-GAPS: Arch/req/test gap audit + TEST-282/TEST-283 added (REQ-263, REQ-265)
+- **Author**: oz-agent
+- **Type**: test
+- **REQs affected**: REQ-263,REQ-265
+- **Description**: Audit revealed REQ-263 (HF paginated sync persists bucket scores) and REQ-265 (HF API token in Authorization header) lacked explicit pytest coverage. Added TEST-282 (`TestHFSyncPersistsBucketScores` — verifies scores.json created with bucket_scores dict and all required keys per entry) and TEST-283 (`TestHFTokenInHeaders` — verifies token_set flag, rate_limit_tier, and Authorization header capture via mock). Both entries added to docs/TESTS.md. `specsmith sync` updated testcases.json to 260 entries.
+- **Status**: complete
+- **Chain hash**: auto

docs/TESTS.md

@@ -2605,6 +2605,28 @@
 - **Expected Behavior:** JSON stub displayed; file updated after add
 - **Confidence:** 0.8
 
+## TEST-282. HF Leaderboard Sync Persists Bucket Scores to JSON
+- **ID:** TEST-282
+- **Title:** HF Leaderboard Sync Persists Bucket Scores to JSON
+- **Description:** `sync_from_huggingface_blocking(force_static=True, scores_path=tmp_path/"scores.json")` creates the file at the given path, whose JSON root contains a `"bucket_scores"` dict. Each entry has `reasoning_score`, `conversational_score`, `longform_score`, and `model_name` keys.
+- **Requirement ID:** REQ-263
+- **Type:** unit
+- **Verification Method:** pytest
+- **Input:** tmp_path/"scores.json" as scores_path; force_static=True
+- **Expected Behavior:** file created; contains bucket_scores dict; at least one entry with all required keys
+- **Confidence:** 1.0
+
+## TEST-283. HF Token Included in Request Headers When Set
+- **ID:** TEST-283
+- **Title:** HF Token Included in Request Headers When Set
+- **Description:** When `SPECSMITH_HF_TOKEN` is set to a non-empty string, `test_hf_connection()` returns `{"token_set": true}` and the rate_limit_tier includes "authenticated". The `_fetch_page` request (captured via mock) includes `Authorization: Bearer <token>` in its headers.
+- **Requirement ID:** REQ-265
+- **Type:** unit
+- **Verification Method:** pytest
+- **Input:** SPECSMITH_HF_TOKEN="hf_test_token" in environment
+- **Expected Behavior:** token_set==true; rate_limit_tier contains "authenticated"
+- **Confidence:** 1.0
+
 ## TEST-263. HF Leaderboard Static Fallback Loads Without Network
 - **ID:** TEST-263
 - **Title:** HF Leaderboard Static Fallback Loads Without Network

tests/test_ai_intelligence.py

@@ -482,3 +482,123 @@ def test_suggestions_are_inert(self) -> None:
             assert not providers_path.exists() or True  # safe: we didn't create it
         else:
             assert providers_path.read_text() == content_before
+
+
+# ---------------------------------------------------------------------------
+# TEST-282 — HF sync persists bucket scores to JSON (REQ-263)
+# ---------------------------------------------------------------------------
+
+
+class TestHFSyncPersistsBucketScores:
+    def test_scores_file_created_with_bucket_scores_key(self, tmp_path: Path) -> None:
+        """TEST-282: sync creates file with bucket_scores dict containing required keys."""
+        import json
+
+        from specsmith.agent.hf_leaderboard import sync_from_huggingface_blocking
+
+        scores_path = tmp_path / "scores.json"
+        sync_from_huggingface_blocking(scores_path=scores_path, force_static=True)
+
+        assert scores_path.is_file(), "scores.json must be created"
+        data = json.loads(scores_path.read_text(encoding="utf-8"))
+        assert "bucket_scores" in data, "file must have 'bucket_scores' dict"
+
+    def test_each_entry_has_required_keys(self, tmp_path: Path) -> None:
+        """TEST-282: each bucket_scores entry has reasoning_score, conversational_score, etc."""
+        import json
+
+        from specsmith.agent.hf_leaderboard import sync_from_huggingface_blocking
+
+        scores_path = tmp_path / "scores.json"
+        sync_from_huggingface_blocking(scores_path=scores_path, force_static=True)
+
+        data = json.loads(scores_path.read_text(encoding="utf-8"))
+        bucket_scores = data["bucket_scores"]
+        assert len(bucket_scores) >= 1
+
+        required_keys = {"reasoning_score", "conversational_score", "longform_score", "model_name"}
+        for model_name, entry in bucket_scores.items():
+            missing = required_keys - set(entry.keys())
+            assert not missing, f"Entry '{model_name}' missing keys: {missing}"
+
+
+# ---------------------------------------------------------------------------
+# TEST-283 — HF token included in request headers when set (REQ-265)
+# ---------------------------------------------------------------------------
+
+
+class TestHFTokenInHeaders:
+    def test_token_set_returns_true_when_configured(self) -> None:
+        """TEST-283: token_set==True and rate_limit_tier contains 'authenticated'."""
+        import urllib.error
+
+        from specsmith.agent.hf_leaderboard import test_hf_connection
+
+        # Mock urlopen to avoid network: raise URLError so the probe short-circuits
+        with (
+            patch.dict(os.environ, {"SPECSMITH_HF_TOKEN": "hf_test_token"}, clear=False),
+            patch(
+                "specsmith.agent.hf_leaderboard.urllib.request.urlopen",
+                side_effect=urllib.error.URLError("offline"),
+            ),
+        ):
+            result = test_hf_connection()
+
+        assert result["token_set"] is True
+        assert "authenticated" in result["rate_limit_tier"]
+
+    def test_token_absent_returns_false_and_anonymous_tier(self) -> None:
+        """TEST-283: no token → token_set==False and tier contains 'anonymous'."""
+        import urllib.error
+
+        from specsmith.agent.hf_leaderboard import test_hf_connection
+
+        env = {k: v for k, v in os.environ.items() if k != "SPECSMITH_HF_TOKEN"}
+        with (
+            patch.dict(os.environ, env, clear=True),
+            patch(
+                "specsmith.agent.hf_leaderboard.urllib.request.urlopen",
+                side_effect=urllib.error.URLError("offline"),
+            ),
+        ):
+            result = test_hf_connection()
+
+        assert result["token_set"] is False
+        assert "anonymous" in result["rate_limit_tier"]
+
+    def test_fetch_page_sends_authorization_header(self) -> None:
+        """TEST-283: _sync_inner sends Authorization: Bearer <token> when token is set."""
+        import urllib.error
+
+        from specsmith.agent.hf_leaderboard import sync_from_huggingface_blocking
+
+        captured_headers: list[dict[str, str]] = []
+
+        def fake_urlopen(req: object, **kwargs: object) -> object:  # noqa: ANN001
+            # Capture headers from the request and raise to abort the sync
+            captured_headers.append(dict(getattr(req, "headers", {})))
+            raise urllib.error.URLError("offline")
+
+        with (
+            patch.dict(os.environ, {"SPECSMITH_HF_TOKEN": "hf_test_token"}, clear=False),
+            patch(
+                "specsmith.agent.hf_leaderboard.urllib.request.urlopen",
+                side_effect=fake_urlopen,
+            ),
+        ):
+            # force_static=False so _fetch_page is actually invoked
+            result = sync_from_huggingface_blocking(force_static=False)
+
+        # sync falls back to static when network is unavailable
+        assert result["errors"] == 0
+        # Verify that at least one request included the Authorization header
+        assert captured_headers, "urlopen must have been called at least once"
+        auth_values = [
+            v
+            for hdrs in captured_headers
+            for k, v in hdrs.items()
+            if k.lower() == "authorization"
+        ]
+        assert any(
+            "Bearer hf_test_token" in v for v in auth_values
+        ), f"No Authorization header found in captured requests: {captured_headers}"