Add: windows mvp - transparent bugs not fixed

docs/API_SPEC.md

@@ -0,0 +1,80 @@
+# Sprimo Frontend API Specification (v1)
+
+Base URL: `http://127.0.0.1:<port>`
+
+Auth: `Authorization: Bearer <token>` required on all endpoints except `/v1/health`.
+
+## Endpoints
+
+### `GET /v1/health`
+
+- Auth: none
+- Response `200`:
+
+```json
+{
+  "version": "0.1.0",
+  "build": "dev",
+  "uptime_seconds": 12,
+  "active_sprite_pack": "default",
+  "capabilities": {
+    "supports_click_through": true,
+    "supports_transparency": true,
+    "supports_tray": true,
+    "supports_global_hotkey": true,
+    "supports_skip_taskbar": true
+  }
+}
+```
+
+### `GET /v1/state`
+
+- Auth: required
+- Response `200`: current frontend snapshot.
+- Response `401`: missing/invalid token.
+- Includes optional `last_error` diagnostic field for latest runtime command-application error.
+
+### `POST /v1/command`
+
+- Auth: required
+- Body: one command envelope.
+- Response `202`: accepted.
+- Response `400`: malformed JSON.
+- Response `401`: missing/invalid token.
+- Runtime note for `SetSpritePack`:
+  - successful load switches sprite atlas immediately.
+  - failed load keeps current in-memory sprite/animation unchanged and reports the failure via `/v1/state.last_error`.
+
+### `POST /v1/commands`
+
+- Auth: required
+- Body: ordered array of command envelopes.
+- Response `202`: accepted.
+- Response `400`: malformed JSON.
+- Response `401`: missing/invalid token.
+- Commands are applied in-order by the frontend runtime after transport acceptance.
+
+## Command Envelope
+
+```json
+{
+  "id": "2d95f8a8-65cc-4309-8f76-4881949d7f4b",
+  "ts_ms": 1737000000000,
+  "command": {
+    "type": "set_state",
+    "payload": {
+      "state": "active",
+      "ttl_ms": null
+    }
+  }
+}
+```
+
+## Error Response
+
+```json
+{
+  "code": "unauthorized",
+  "message": "missing or invalid bearer token"
+}
+```