app-platform: derive launch URLs from manifests

docs/APP-PACKAGING-MIGRATION-PLAN.md

@@ -38,6 +38,7 @@ As of the current `1.8-alpha` workstream:
 - Derived host facts and secret-file-backed environment variables are represented with `container.derived_env` and `container.secret_env`.
 - Catalog metadata generation is implemented by `scripts/generate-app-catalog.py`.
 - App-session launch ports/titles and new-tab launch behavior now have a generated TypeScript metadata path from manifests, with manual overrides preserved for companion UIs and aliases that do not have manifest-owned metadata yet.
+- Runtime package listings now derive LAN launch URLs from manifest-owned `interfaces.main` declarations or HTTP app ports before falling back to legacy compatibility aliases.
 - Release drift checking is implemented by `scripts/check-app-catalog-drift.py --release --strict`.
 - The canonical catalog and the UI public catalog are expected to remain byte-for-byte synced after generation.
 - Runtime validation has already moved many simple and moderate apps into the manifest/orchestrator path, including Filebrowser, Vaultwarden, Portainer, Uptime Kuma, Grafana, Gitea, Nextcloud, SearXNG, Nostr Relay, PhotoPrism, Jellyfin, Meshtastic, and several Bitcoin-adjacent apps.

docs/app-developer-guide.md

@@ -122,11 +122,35 @@ app:
 | `app.health_check` | HTTP or TCP health check settings |
 | `app.devices` | Explicit device paths |
 | `app.metadata` | Catalog-facing presentation metadata such as icon, category, tier, repo/source, author, feature bullets, and launch hints |
+| `app.interfaces.main` | Optional primary UI launch surface with `port`, `protocol`, and `path` |
 
 Additional extension keys may exist for current integrations, for example Bitcoin, Lightning, or app-specific launch/interface metadata. Treat extension keys as transitional unless they are documented as reusable platform primitives.
 
 Use `metadata.launch.open_in_new_tab: true` when the app UI is known to reject iframe embedding with headers such as `X-Frame-Options` or restrictive CSP. The frontend app-session metadata is generated from this flag during release work.
 
+### Launch Interfaces
+
+If an app exposes a user-facing web UI, declare its primary launch surface in
+`interfaces.main`. Runtime package listings prefer this interface over inferred
+port mappings, which matters for apps that expose non-UI service ports or use a
+companion wait/proxy UI.
+
+```yaml
+interfaces:
+  main:
+    name: Web UI
+    description: Primary app interface
+    type: ui
+    port: 8180
+    protocol: http
+    path: /
+```
+
+For simple HTTP apps without `interfaces.main`, Archipelago can still infer the
+launch URL from the first declared TCP host port when the app has an HTTP health
+check. TCP-only service ports, such as Bitcoin RPC/P2P, are not treated as UI
+launch URLs.
+
 ## Security Requirements
 
 These are enforced by the marketplace/catalog pipeline and the node. Non-compliant apps are flagged.