fix(webui): one runtime warning per card, with the install instructions

Two takes on the same warning landed on this branch: an aside shown on every
transcribe.cpp card, and a badge plus note driven by whether the runtime is
actually resolvable on this host. Together a card said the same thing twice,
and the aside kept saying it after transcribe-cli was installed.

Keep the host-driven one, which clears itself once the binary resolves and
covers every engine rather than transcribe.cpp alone, and give it what the
aside had that it lacked: the deployment.md link and the reminder that the
runtime lives where the gateway runs, inside the container under Docker.
DependencyStatus carries the URL so the link is catalog data, not markup.

The Settings page keeps the aside: the engine picker offers transcribe.cpp
before any model exists, so there is no card there to carry the warning.

Author: Mr-Sunglasses

app/admin_queries.py

@@ -18,8 +18,11 @@
 # The GGUF models in the catalog need a transcribe-cli this project never ships;
 # the tile names the build and the override so a missing binary is actionable.
 TRANSCRIBE_INSTALL_HINT = (
-    "Build https://github.com/handy-computer/transcribe.cpp, then set "
-    "VOCAGATEWAY_TRANSCRIBE_BINARY to its transcribe-cli"
+    "Install transcribe-cli where the gateway runs, inside the container under "
+    "Docker, and set VOCAGATEWAY_TRANSCRIBE_BINARY if it is not on PATH"
+)
+TRANSCRIBE_DOCS_URL = (
+    "https://github.com/VocaHQ/vocagateway/blob/main/docs/deployment.md#install-transcribecpp"
 )
 PYTHON_ENGINE_INSTALL_HINT = "Install vocagateway[engines] or use the Docker image"
 # One engine paired with the single runtime it needs.
@@ -75,7 +78,11 @@ def entry_fields(self, engine: str) -> dict[str, str | None]:
         unmet = self.missing(engine)
         if unmet is None:
             return {}
-        return {"runtime_requirement": unmet.name, "runtime_hint": unmet.install_hint}
+        return {
+            "runtime_requirement": unmet.name,
+            "runtime_hint": unmet.install_hint,
+            "runtime_docs_url": unmet.docs_url,
+        }
 
     def _build(self) -> list[_EngineRuntime]:
         is_mac = self.system.os_name == "Darwin"
@@ -109,6 +116,7 @@ def _binary_tiles(self, is_mac: bool) -> list[_EngineRuntime]:
                     available=self.system.transcribe_cli_path is not None,
                     path=self.system.transcribe_cli_path,
                     install_hint=TRANSCRIBE_INSTALL_HINT,
+                    docs_url=TRANSCRIBE_DOCS_URL,
                 ),
             ),
         ]

app/schemas.py

@@ -91,6 +91,9 @@ class DependencyStatus(BaseModel):
     available: bool
     path: str | None = None
     install_hint: str | None = None
+    # Set when a hint alone cannot carry the setup, as for a tool the project
+    # does not ship and the operator has to build.
+    docs_url: str | None = None
 
 
 class SystemStatus(BaseModel):
@@ -224,6 +227,7 @@ class AdminModelEntry(BaseModel):
     # weights are still correct, so the card warns rather than hiding the button.
     runtime_requirement: str | None = None
     runtime_hint: str | None = None
+    runtime_docs_url: str | None = None
 
 
 class CustomDownloadRequest(BaseModel):

app/templates/models/model_card.html

@@ -1,5 +1,4 @@
 {% from "macros/icons.html" import active_label, info as info_icon %}
-{% from "macros/native_requirements.html" import transcribe_requirement %}
 
 {% macro language_chips(names) %}{% for name in names %}<span class="model-language-chip">{{ name }}</span>{% endfor %}{% endmacro %}
 
@@ -73,9 +72,6 @@ <h4 title="{{ entry.label }}">{{ card.display_label }}</h4>
     <p class="model-blurb" title="{{ entry.description }}">
       {{ entry.description }}
     </p>
-    {% if entry.engine == "transcribe.cpp" %}
-    {{ transcribe_requirement() }}
-    {% endif %}
     {% if entry.retired %}
     <p class="model-retirement-note muted small">
       Retired{% if entry.replacement_id %}; use {{ entry.replacement_id }}{% endif %}{% if entry.retirement_reason %}. {{ entry.retirement_reason }}{% endif %}
@@ -85,7 +81,12 @@ <h4 title="{{ entry.label }}">{{ card.display_label }}</h4>
        missing before the operator spends the bandwidth on them. The badge above
        names the requirement, so this line carries only how to satisfy it. #}
     {% if entry.runtime_requirement and entry.runtime_hint %}
-    <p class="model-runtime-note small">Not installed yet &mdash; {{ entry.runtime_hint }}.</p>
+    <p class="model-runtime-note small">
+      Not installed yet &mdash; {{ entry.runtime_hint }}.
+      {%- if entry.runtime_docs_url %}
+      <a href="{{ entry.runtime_docs_url }}" target="_blank" rel="noopener noreferrer">
+        Installation instructions</a>{% endif %}
+    </p>
     {% endif %}
   </div>
   <div class="model-toolbar">

app/webui/styles.css

@@ -1659,6 +1659,7 @@ html[data-theme="dark"] .family-models-label {
 }
 /* A model whose engine has no runtime on this host. Warn-coloured rather than
    error-coloured: the weights are fine, only the CLI or package is absent. */
+.model-runtime-note a { color: inherit; font-weight: 500; }
 .model-runtime-note {
   margin: 6px 0 0;
   padding-left: 8px;

tests/test_transcribe_cpp.py

@@ -8,7 +8,7 @@
 
 import pytest
 
-from app.admin_queries import TRANSCRIBE_INSTALL_HINT, _EngineRuntimes
+from app.admin_queries import TRANSCRIBE_DOCS_URL, TRANSCRIBE_INSTALL_HINT, _EngineRuntimes
 from app.catalog import DEFAULT_CATALOG
 from app.config import Settings
 from app.errors import EngineUnavailableError, LanguageUnsupportedError, TranscriptionProcessError
@@ -291,6 +291,7 @@ def test_engine_runtimes_names_the_missing_binary_only_while_it_is_absent(tmp_pa
     assert absent.entry_fields("transcribe.cpp") == {
         "runtime_requirement": "transcribe.cpp CLI",
         "runtime_hint": TRANSCRIBE_INSTALL_HINT,
+        "runtime_docs_url": TRANSCRIBE_DOCS_URL,
     }
 
     present = _EngineRuntimes(_system(transcribe_cli="/opt/transcribe-cli"), _settings(tmp_path))
@@ -332,15 +333,20 @@ def card(**runtime) -> str:
     warned = card(
         runtime_requirement="transcribe.cpp CLI",
         runtime_hint=TRANSCRIBE_INSTALL_HINT,
+        runtime_docs_url=TRANSCRIBE_DOCS_URL,
     )
     assert "needs transcribe.cpp CLI" in warned
     assert "Not installed yet" in warned
     assert "VOCAGATEWAY_TRANSCRIBE_BINARY" in warned
+    assert TRANSCRIBE_DOCS_URL in warned
+    assert "Installation instructions" in warned
     # The weights are still correct, so the card must not block the download.
     assert "Download" in warned
 
     ready = card()
     assert "needs transcribe.cpp CLI" not in ready
+    # The old always-on aside warned even once the runtime was installed.
+    assert "Installation instructions" not in ready
     assert "Not installed yet" not in ready
     assert "Download" in ready