feat(assets): probe-first resolver + SPOT for IMAGE_NAME/PORT + README screenshot

Probe-first asset resolution (regression fix)
---------------------------------------------

cache_manager.cache_file() returned either a relative cache path
(success) or None (failure). The previous app.py fallback
asset['cache'] = cached or asset['source'] mixed both types into
one field, which the template wrapped in url_for('static', ...)
regardless — producing broken
/static/https://file.infinito.nexus/.../logo.png URLs whenever the
source couldn't be downloaded.

- New app/utils/asset_resolver.py: HEAD-probes the URL (3 s
  timeout, image/* content type). On hit, embed directly via a
  new external_url field — no download required. On miss, fall
  back to cache_manager.cache_file. If that also fails, expose
  the source URL via external_url so the browser shows the alt
  text instead of an empty src.
- app.py exposes an asset_src(asset) context processor that
  picks external_url first, then url_for('static', cache),
  so the template never wraps an absolute URL in a static prefix.
- Templates (base, navigation, card) switch to asset_src(...) and
  gate the card image branch on cache or external_url.
- 16 unit tests cover every probe/cache/fallback branch; one live
  integration test exercises the canonical
  https://file.infinito.nexus/assets/img/logo.png to prove the
  probe-first path works end-to-end (cache dir stays empty).
- config.sample.yaml: new Infinito.Nexus card driven by the same
  canonical asset URL.

Single source of truth for IMAGE_NAME and PORT
----------------------------------------------

- env.example is now the only place the literal values live.
- Makefile and docker-compose.yml reference \$(IMAGE_NAME) /
  \${IMAGE_NAME:?…} (same for PORT); no defaults, no silent
  fallbacks.
- New make env / make config bootstrap .env / app/config.yaml
  from their checked-in templates. Idempotent.
- All container-using targets depend on the two bootstrap targets
  so a fresh checkout runs in a single invocation.
- Recipes source .env at recipe-execution time so they pick up a
  freshly bootstrapped .env in the same make invocation.

README
------

- Screenshot added under the title.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

tests/integration/test_asset_resolver_live.py

@@ -0,0 +1,85 @@
+"""Live network verification of the probe-first asset resolution path.
+
+The unit tests in ``tests/unit/test_asset_resolver.py`` cover every
+branch with mocks. This integration test exercises the real
+``https://file.infinito.nexus/assets/img/logo.png`` endpoint that
+``app/config.sample.yaml`` references for the Infinito.Nexus card. A
+green run proves the production resolver behaviour end-to-end:
+
+* probe (HEAD ``image/*``) succeeds against the canonical Infinito.Nexus
+  asset host, so ``external_url`` is populated directly and **no**
+  download is performed (the cache directory stays empty).
+
+The download-fallback branch (probe fails → ``cache_manager.cache_file``
+serves the asset locally) is intentionally not exercised against a live
+endpoint here — it is covered by mocked unit tests because every
+candidate "HEAD-fails, GET-succeeds" public URL we tried was flaky
+(Nextcloud's ``/download`` endpoint sporadically times out on HEAD even
+when GET works), which would make this guard test non-deterministic.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import unittest
+from tempfile import TemporaryDirectory
+from urllib.parse import urlparse
+
+import requests
+
+from app.utils.asset_resolver import resolve_asset_cache
+from app.utils.cache_manager import CacheManager
+
+INFINITO_LOGO_URL = "https://file.infinito.nexus/assets/img/logo.png"
+
+_SKIP_LIVE_NETWORK = os.environ.get("PORTFOLIO_SKIP_LIVE_NETWORK_TESTS") == "1"
+
+
+def _reachable(url: str) -> bool:
+    try:
+        return requests.head(url, allow_redirects=True, timeout=5).ok
+    except requests.RequestException:
+        return False
+
+
+@unittest.skipIf(
+    _SKIP_LIVE_NETWORK,
+    "PORTFOLIO_SKIP_LIVE_NETWORK_TESTS=1 — skipping live network tests",
+)
+class TestAssetResolverLive(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        if not _reachable(INFINITO_LOGO_URL):
+            raise unittest.SkipTest(
+                f"{urlparse(INFINITO_LOGO_URL).netloc} unreachable from this runner"
+            )
+
+    def test_infinito_nexus_logo_resolves_via_external_url_without_download(self):
+        with TemporaryDirectory() as tmp:
+            cache_dir = os.path.join(tmp, "cache")
+            cache_manager = CacheManager(cache_dir)
+            asset = {"source": INFINITO_LOGO_URL}
+
+            resolve_asset_cache(asset, cache_manager)
+
+            self.assertIsNone(
+                asset["cache"],
+                f"Expected probe-first path to skip download for {INFINITO_LOGO_URL}",
+            )
+            self.assertEqual(
+                asset["external_url"],
+                INFINITO_LOGO_URL,
+                "Probe-success URL must land in external_url so the template "
+                "embeds it directly instead of routing through /static/.",
+            )
+            self.assertEqual(
+                os.listdir(cache_dir),
+                [],
+                "Cache directory must stay empty when probe succeeds — "
+                "downloading would waste bandwidth.",
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_asset_resolver.py

@@ -0,0 +1,188 @@
+import unittest
+from unittest.mock import Mock, patch
+
+import requests
+
+from app.utils.asset_resolver import (
+    _probe_image_url,
+    asset_src,
+    resolve_asset_cache,
+)
+
+
+def _url_for_static(filename):
+    return f"/static/{filename}"
+
+
+def _always_probes_false(_url):
+    return False
+
+
+def _always_probes_true(_url):
+    return True
+
+
+class TestResolveAssetCache(unittest.TestCase):
+    def test_probe_success_skips_cache_and_embeds_directly(self):
+        cache_manager = Mock()
+        asset = {"source": "https://example.test/logo.png"}
+
+        resolve_asset_cache(asset, cache_manager, probe=_always_probes_true)
+
+        self.assertIsNone(asset["cache"])
+        self.assertEqual(asset["external_url"], "https://example.test/logo.png")
+        cache_manager.cache_file.assert_not_called()
+
+    def test_local_cache_path_assigned_when_probe_fails_but_download_succeeds(self):
+        cache_manager = Mock()
+        cache_manager.cache_file.return_value = "cache/logo_abc.png"
+        asset = {"source": "https://example.test/logo.png"}
+
+        resolve_asset_cache(asset, cache_manager, probe=_always_probes_false)
+
+        self.assertEqual(asset["cache"], "cache/logo_abc.png")
+        self.assertIsNone(asset["external_url"])
+        cache_manager.cache_file.assert_called_once_with(
+            "https://example.test/logo.png"
+        )
+
+    def test_external_url_fallback_when_probe_and_download_both_fail(self):
+        cache_manager = Mock()
+        cache_manager.cache_file.return_value = None
+        asset = {"source": "https://file.infinito.nexus/assets/img/logo.png"}
+
+        resolve_asset_cache(asset, cache_manager, probe=_always_probes_false)
+
+        self.assertIsNone(asset["cache"])
+        self.assertEqual(
+            asset["external_url"],
+            "https://file.infinito.nexus/assets/img/logo.png",
+        )
+
+    def test_missing_source_leaves_both_fields_none(self):
+        cache_manager = Mock()
+        probe = Mock()
+        asset = {"class": "fa-solid fa-link"}
+
+        resolve_asset_cache(asset, cache_manager, probe=probe)
+
+        self.assertIsNone(asset["cache"])
+        self.assertIsNone(asset["external_url"])
+        cache_manager.cache_file.assert_not_called()
+        probe.assert_not_called()
+
+    def test_empty_source_treated_as_missing(self):
+        cache_manager = Mock()
+        probe = Mock()
+        asset = {"source": ""}
+
+        resolve_asset_cache(asset, cache_manager, probe=probe)
+
+        self.assertIsNone(asset["cache"])
+        self.assertIsNone(asset["external_url"])
+        cache_manager.cache_file.assert_not_called()
+        probe.assert_not_called()
+
+
+class TestProbeImageUrl(unittest.TestCase):
+    def _response(self, content_type, raise_exc=None):
+        resp = Mock()
+        if raise_exc:
+            resp.raise_for_status.side_effect = raise_exc
+        else:
+            resp.raise_for_status.return_value = None
+        resp.headers = {"Content-Type": content_type}
+        return resp
+
+    @patch("app.utils.asset_resolver.requests.head")
+    def test_returns_true_for_image_content_type(self, mock_head):
+        mock_head.return_value = self._response("image/png")
+
+        self.assertTrue(_probe_image_url("https://example.test/logo.png"))
+
+    @patch("app.utils.asset_resolver.requests.head")
+    def test_returns_true_for_svg_with_charset_suffix(self, mock_head):
+        mock_head.return_value = self._response("image/svg+xml; charset=utf-8")
+
+        self.assertTrue(_probe_image_url("https://example.test/logo.svg"))
+
+    @patch("app.utils.asset_resolver.requests.head")
+    def test_returns_false_for_non_image_content_type(self, mock_head):
+        mock_head.return_value = self._response("text/html")
+
+        self.assertFalse(_probe_image_url("https://example.test/404"))
+
+    @patch("app.utils.asset_resolver.requests.head")
+    def test_returns_false_when_http_status_not_ok(self, mock_head):
+        mock_head.return_value = self._response(
+            "image/png",
+            raise_exc=requests.HTTPError("404 Not Found"),
+        )
+
+        self.assertFalse(_probe_image_url("https://example.test/missing.png"))
+
+    @patch("app.utils.asset_resolver.requests.head")
+    def test_returns_false_on_network_error(self, mock_head):
+        mock_head.side_effect = requests.ConnectionError("dns failure")
+
+        self.assertFalse(_probe_image_url("https://unreachable.test/logo.png"))
+
+    @patch("app.utils.asset_resolver.requests.head")
+    def test_follows_redirects_with_short_timeout(self, mock_head):
+        mock_head.return_value = self._response("image/png")
+
+        _probe_image_url("https://example.test/logo.png")
+
+        mock_head.assert_called_once_with(
+            "https://example.test/logo.png",
+            allow_redirects=True,
+            timeout=3,
+        )
+
+
+class TestAssetSrc(unittest.TestCase):
+    def test_returns_static_url_for_local_cache_path(self):
+        asset = {"cache": "cache/logo_abc.png", "external_url": None}
+
+        self.assertEqual(
+            asset_src(asset, _url_for_static),
+            "/static/cache/logo_abc.png",
+        )
+
+    def test_returns_absolute_url_unchanged_for_external_url(self):
+        # Regression: previously the template wrapped this through
+        # url_for('static', ...) and produced /static/https://... — a
+        # URL-in-URL the browser resolved against the dashboard host.
+        asset = {
+            "cache": None,
+            "external_url": "https://file.infinito.nexus/assets/img/logo.png",
+        }
+
+        self.assertEqual(
+            asset_src(asset, _url_for_static),
+            "https://file.infinito.nexus/assets/img/logo.png",
+        )
+
+    def test_external_url_wins_over_cache_when_both_present(self):
+        asset = {
+            "cache": "cache/logo.png",
+            "external_url": "https://override.test/logo.png",
+        }
+
+        self.assertEqual(
+            asset_src(asset, _url_for_static),
+            "https://override.test/logo.png",
+        )
+
+    def test_returns_empty_string_when_neither_field_is_set(self):
+        asset = {"cache": None, "external_url": None}
+
+        self.assertEqual(asset_src(asset, _url_for_static), "")
+
+    def test_returns_empty_string_for_none_or_empty_asset(self):
+        self.assertEqual(asset_src(None, _url_for_static), "")
+        self.assertEqual(asset_src({}, _url_for_static), "")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_navigation_template.py

@@ -25,6 +25,14 @@ class TestNavigationTemplate(unittest.TestCase):
         environment.globals["url_for"] = lambda _endpoint, filename: (
             f"/static/{filename}"
         )
+        environment.globals["asset_src"] = lambda asset: (
+            (asset or {}).get("external_url")
+            or (
+                f"/static/{(asset or {}).get('cache')}"
+                if (asset or {}).get("cache")
+                else ""
+            )
+        )
 
         rendered = environment.get_template("moduls/navigation.html.j2").render(
             menu_type="header",