feat: initial commit

docs/updates/bundle-archive-v1.md

@@ -0,0 +1,32 @@
+# Bundle Archive v1
+
+Downloaded updates are bundle archives rather than installer executables.
+
+Archive requirements:
+
+- top-level `bundle.json`
+- payload files stored relative to the install root
+- no absolute paths
+- no `..` path traversal
+- provider checksum must match the downloaded archive before staging
+
+`bundle.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "entrypoint": "MyApp.exe",
+  "files": [
+    { "path": "MyApp.exe", "mode": "0755" },
+    { "path": "resources/config.json", "mode": "0644" }
+  ]
+}
+```
+
+Install roots:
+
+- macOS: the `.app` bundle directory
+- Windows: the directory containing the running `.exe`
+- Linux: the directory containing the running binary
+
+The helper-mode apply flow stages the archive, validates `bundle.json`, backs up existing files, copies payload files into the install root, and relaunches the app using `entrypoint`.

docs/updates/http-manifest-v1.md

@@ -0,0 +1,39 @@
+# HTTP Manifest v1
+
+The generic update provider uses a first-party JSON manifest.
+
+Schema:
+
+```json
+{
+  "schemaVersion": 1,
+  "productID": "com.example.app",
+  "releases": [
+    {
+      "id": "1.2.0",
+      "version": "1.2.0",
+      "channel": "stable",
+      "publishedAt": "2026-03-01T03:10:56Z",
+      "notesMarkdown": "Bug fixes",
+      "artifacts": [
+        {
+          "os": "darwin",
+          "arch": "arm64",
+          "kind": "bundle-archive",
+          "format": "zip",
+          "url": "https://updates.example.com/app/1.2.0/darwin-arm64.zip",
+          "sha256": "..."
+        }
+      ]
+    }
+  ]
+}
+```
+
+Rules:
+
+- `schemaVersion` must be `1`
+- `productID` must match the running app descriptor
+- `channel` is one of `stable`, `beta`, or `alpha`
+- the provider picks the highest semver above the current version for the current `os` and `arch`
+- artifact URLs are fetched with the adapter's per-provider request preparation hook