conductor(track-update): qwen_llama_grok - spec notes for nagent_review + docs refresh

4 surgical additions to the spec, no task changes:

1. Result return type: Added a coordination note in §3.1 (Data-
   Oriented Design) explaining that the shared send_openai_compatible
   helper should return Result[NormalizedResponse, ErrorInfo] from
   day 1, not NormalizedResponse + ProviderError raise. This is so
   the downstream data_oriented_error_handling_20260606 track is
   a small mechanical pass over new code, not a second migration.
   References nagent_review Pitfall #4 (provider history divergence)
   and the ErrorKind.PROVIDER_HISTORY_DIVERGED_FROM_UI use case.

2. Declarative read, not behavioral dispatch: Added clarification
   to §6 (UX Adaptation) that the capability matrix is a *read* of
   declarative data, not a new dispatch layer. Per nagent_review
   Pitfall #1 (opaque function calling in the Application is the
   correct choice; nagent-style protocol is for Meta-Tooling),
   UI elements are visible/enabled/disabled/hidden but the
   *behavior* they invoke is unchanged. Three concrete examples
   added: screenshot button, cost panel, cache panel.

3. PROVIDERS source of truth: Added a NOTE in §3.2 (Module Layout)
   that src/models.py:79-86 PROVIDERS is the existing single
   source of truth for the (vendor, model) enumeration. The
   capability registry reads from this constant rather than
   introducing a parallel list. Cross-references
   docs/guide_models.md.

4. Docs touchpoint: Expanded Phase 6 (Docs + Archive) in §9 to
   note that docs/guide_ai_client.md needs the new providers +
   the shared helper documented, and that
   docs/guide_context_aggregation.md (added 2026-06-08) is the
   reference for the aggregate.py pipeline that all new providers
   use.

5. See Also cross-references: Added 3 new entries to §13.2:
   - docs/guide_context_aggregation.md (the new pipeline guide)
   - conductor/tracks/nagent_review_20260608/report.md (§1, §5, §15)
   - conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md
     (§1, §2, §9)

No plan.md changes. Plan tasks are task-level and will flow from
the spec changes when the track is re-planned.

conductor/tracks/qwen_llama_grok_integration_20260606/spec.md

@@ -52,6 +52,8 @@ The user's design philosophy (referencing Ryan Fleury's code/data separation, Mi
   4. Updates the vendor's history with the normalized response.
   5. Returns the text content to `ai_client.send()`.
 
+> **Coordination with `data_oriented_error_handling_20260606`.** This track is *upstream* of the Fleury-pattern `Result[T]` refactor. The shared helper should return `Result[NormalizedResponse, ErrorInfo]` from day 1 (rather than `NormalizedResponse` and raise `ProviderError` on failure), so the subsequent data_oriented_error_handling track is a small mechanical pass over the new code rather than a second migration. Per nagent_review Pitfall #4 (provider history divergence), the helper is also a natural place to add an `ErrorKind.PROVIDER_HISTORY_DIVERGED_FROM_UI` error case. **Concrete change in code:** `def send_openai_compatible(...) -> Result[NormalizedResponse, ErrorInfo]`. The `Result` type is imported from the new `src/result_types.py` (created by the data_oriented_error_handling track); for this track, the helper can stub it locally as a `Tuple[NormalizedResponse, Optional[ErrorInfo]]` and the data_oriented_error_handling track does the mechanical conversion. Either way, the *error shape* is `ErrorInfo`, defined in this spec's §5.1 below.
+
 This means:
 - **Adding a new OpenAI-compatible vendor** = 50 lines of glue (client init + capability declaration + history storage), not 300 lines of duplicated logic.
 - **Anthropic/Gemini/DeepKeep** stay per-vendor code paths; the data-oriented refactor doesn't apply to them because their unique APIs are not OpenAI-compatible-shaped.
@@ -65,7 +67,7 @@ src/
   vendor_capabilities.py           # NEW: VendorCapabilities dataclass, registry, get_capabilities()
   openai_compatible.py             # NEW: shared OpenAI-compatible send helper
   cost_tracker.py                  # Modified: add Qwen/Llama/Grok pricing
-  models.py                        # Modified: add provider metadata for Qwen/Llama/Grok
+  models.py                        # Modified: add provider metadata for Qwen/Llama/Grok. NOTE: `models.PROVIDERS` (line 79-86) is the existing single source of truth for the (vendor, model) enumeration. The capability registry in `vendor_capabilities.py` reads from this constant — it does NOT introduce a parallel list.
   gui_2.py                         # Modified: register Qwen/Llama/Grok in PROVIDERS; capability-driven UI
   app_controller.py                # Modified: same
   credentials_template.toml        # Modified: add [qwen], [llama], [grok] sections
@@ -356,6 +358,13 @@ The GUI reads `get_capabilities(active_vendor, active_model)` once per render fr
 
 The adaptations are gated on the capability value, not on vendor name. The `gui_2.py` change is one new helper: `def _get_active_capabilities(self) -> VendorCapabilities: return get_capabilities(self._provider, self._model)`. The render functions query this once at the top of their scope.
 
+> **Important: the matrix is a *declarative read*, not a behavioral dispatch.** Per nagent_review Pitfall #1 (opaque function calling in the Application is the correct choice; nagent's regex-tag protocol is right for the Meta-Tooling, not the Application), the capability matrix must not introduce new per-vendor code paths in the GUI. UI elements that depend on capabilities should be *visible/enabled/disabled/hidden* based on the matrix value, but the *behavior* they invoke is unchanged. Concretely:
+> - The screenshot button is *hidden* when `vision: false` — but when it *is* shown, it calls the same `mcp_client.dispatch("image_attachment", ...)` it always did.
+> - The cost panel shows "—" when `cost_tracking: false` — but the *underlying cost computation* is the same function; only the display differs.
+> - The cache panel is *hidden* when `caching: false` — but the cache calls themselves are not gated on the matrix; they're gated on the provider's actual cache availability (which the matrix *describes*, not *enforces*).
+>
+> This is the same data-oriented principle as the rest of the track: the matrix is *data*, the behavior is *code*, and they meet only at the UI render boundary.
+
 ## 7. Configuration
 
 ### 7.1 `pyproject.toml` — new dependency
@@ -422,7 +431,7 @@ grok_model = "grok-2-vision"
 | **Phase 3 — Grok + Llama via shared helper** | Implement `_send_grok()` and `_send_llama()`. Both call `send_openai_compatible()`. Add `[grok]` and `[llama]` credentials sections. Register in PROVIDERS lists. | Medium. New code paths, but lighter than Qwen (OpenAI-compatible). |
 | **Phase 4 — MiniMax refactor** | Refactor `_send_minimax()` to use the shared helper. Verify all existing `tests/test_minimax_provider.py` tests pass. | Medium-High. Touching working code. Mitigated by existing test coverage. |
 | **Phase 5 — UX adaptation + integration** | Add `_get_active_capabilities()` to `gui_2.py`. Apply the 9 UI adaptations from §6. Run the full test suite. | Low. UI-only changes. |
-| **Phase 6 — Docs + archive** | Update `docs/guide_ai_client.md` to document the new vendors, the capability matrix, and the shared helper. Update `docs/guide_models.md` for the new PROVIDERS entries. Archive the track. | Low. |
+| **Phase 6 — Docs + archive** | Update `docs/guide_ai_client.md` to document the new vendors, the capability matrix, and the shared helper. Update `docs/guide_models.md` for the new PROVIDERS entries. Archive the track. **Docs touchpoint (added 2026-06-08):** `docs/guide_ai_client.md` "AI Client" row in the docs index should be updated to list 8 providers (was 5) and the new `send_openai_compatible()` helper section. The 2026-06-08 docs refresh introduced `docs/guide_context_aggregation.md` which references the `aggregate.run()` pipeline that all new providers use; verify the cross-link is still accurate. | Low. |
 
 Each phase has its own checkpoint commit and git note.
 
@@ -463,8 +472,11 @@ Each phase has its own checkpoint commit and git note.
 
 ### 13.2 Project References
 
-- `docs/guide_ai_client.md` — current `ai_client.py` architecture; will be updated in Phase 6 to document the matrix and the shared helper.
-- `docs/guide_models.md` — current PROVIDERS constant and provider metadata; will be updated in Phase 6.
+- `docs/guide_ai_client.md` — current `ai_client.py` architecture; will be updated in Phase 6 to document the matrix and the shared helper. Specifically: the per-provider history globals (`_anthropic_history`, `_deepseek_history`, `_minimax_history`) documented at lines 123-132 are the **state-management shape** that the new 3 vendors should follow in Phase 2/3. (Per `guide_state_lifecycle.md §4`, the per-provider lock pattern is the established convention.)
+- `docs/guide_models.md` — current PROVIDERS constant and provider metadata; will be updated in Phase 6. Per `docs/guide_models.md §"Data Models"`, the FileItem schema (line 510) is the model layer the capability matrix composes with, not replaces.
+- `docs/guide_context_aggregation.md` — added 2026-06-08; documents the `aggregate.py` pipeline that all new providers will route through. The new provider adapters' "build file items" stage should compose with `aggregate.build_file_items()` and the 7 `view_mode` values, not introduce a parallel aggregation path.
+- `conductor/tracks/nagent_review_20260608/report.md` — added 2026-06-08; specifically §1 (Durable work), §5 (The loop), and §15 Pitfalls #2 and #4 (per-provider history globals and stateful singleton) inform the data-oriented framing of this track.
+- `conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md` — added 2026-06-08; specifically §1 (state visibility), §2 (readable conversation log), and §9 (edit-the-input) inform the helper's `Result` return type recommendation.
 - `conductor/tracks/openai_integration_20260308/` — closest prior art (single provider, OpenAI-compatible).
 - `conductor/tracks/zhipu_integration_20260308/` — second prior art (single provider, custom API).
 - `conductor/tracks/startup_speedup_20260606/` — example of an active track in this project (same convention).