Baseline: distribution workspace before observability redesign

.agents/subplans/04-http-api-and-install.md

@@ -0,0 +1,104 @@
+# Subplan 04 - HTTP API And Install Experience
+
+## Goal
+
+Expose release management and install/download flows through `distd`.
+
+## API Slices
+
+Slice 1 - Server Skeleton:
+
+- config loading
+- routing
+- JSON request/response helpers
+- error response shape
+- health endpoint
+
+Slice 2 - Auth:
+
+- bearer token parsing
+- scope checks
+- audit actor resolution
+
+Slice 3 - Apps And Releases:
+
+- create/list/get apps
+- create/list/get releases
+- publish release
+- promote/rollback channel
+
+Slice 4 - Uploads And Downloads:
+
+- streaming upload endpoint
+- digest validation
+- resumable upload optional for later
+- download endpoint with content length and SHA-256 headers
+
+Slice 5 - Public Install Pages:
+
+- app page by slug/channel
+- platform detection
+- QR/deep link support
+- authenticated and public modes
+
+## iOS Install Rules
+
+Normal iOS devices cannot install arbitrary IPA files from a web page.
+
+Supported modes:
+
+- TestFlight link: open Apple's TestFlight flow.
+- Enterprise/MDM: serve signed HTTPS manifest plist for enrolled devices.
+- Artifact only: allow authenticated IPA download without claiming mobile
+  install support.
+
+Acceptance:
+
+- The UI labels iOS install mode accurately.
+- Enterprise install requires HTTPS and a valid manifest.
+- Artifact-only mode does not display a misleading "Install on iPhone" action.
+
+## Android APK Install Rules
+
+Supported modes:
+
+- Direct APK download.
+- Optional install instructions shown only when relevant.
+- SHA-256 visible in download metadata.
+
+Acceptance:
+
+- APK download is access-controlled according to app/channel policy.
+
+## Desktop Install Rules
+
+macOS:
+
+- notarization status displayed when available
+- download zip/dmg/pkg
+
+Linux:
+
+- tar/appimage/deb/rpm metadata
+
+Windows:
+
+- installer zip/exe/msi metadata
+- signature status displayed when available
+
+## API Contract
+
+All JSON endpoints should return:
+
+- stable status code
+- error code
+- message
+- request id
+- optional details
+
+Downloads should include:
+
+- `Content-Length`
+- `Content-Type`
+- `X-Artifact-SHA256`
+- cache policy by channel