app-platform: derive launch URLs from manifests

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.