openapi.yaml: document Device endpoints + schemas

Layer 1 of the agent's reviewer (per the agent's docs/SPEC.md)
checks OpenAPI parity between Rails ↔ iOS networking ↔ Android
repository layers. Adding the Device controller without the
corresponding spec entries means PRs #3-5 (the iOS/Android push
registration clients) wouldn't have a contract to integrate against
and would fail Layer 1 contract-parity scan.

Adds:
- Tag: Devices
- Path POST /devices: idempotent register; 201 on create, 200 on
  touch, 422 on validation error
- Path DELETE /devices/{deviceId}: 204 no_content, 404 if device
  isn't owned by current_shopkeeper
- Schemas: DeviceAttributes, Device, DeviceCreateRequest
  (jsonapi-style envelope to match the rest of the API)

YAML parses; paths now 25, schemas now 38.

Author: dadachi

docs/openapi.yaml

@@ -369,6 +369,58 @@ components:
         attributes:
           $ref: '#/components/schemas/PermissionAttributes'
 
+    DeviceAttributes:
+      type: object
+      properties:
+        token:
+          type: string
+          description: Push token (APNs device token for ios, FCM registration token for android)
+        platform:
+          type: string
+          enum: [ios, android]
+        bundle_id:
+          type: string
+          nullable: true
+          description: Bundle identifier of the registering app (helps disambiguate when one shopkeeper uses multiple variants generated by the agent)
+        last_active_at:
+          type: string
+          format: date-time
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    Device:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        type:
+          type: string
+          enum: [device]
+        attributes:
+          $ref: '#/components/schemas/DeviceAttributes'
+
+    DeviceCreateRequest:
+      type: object
+      required: [device]
+      properties:
+        device:
+          type: object
+          required: [token, platform]
+          properties:
+            token:
+              type: string
+            platform:
+              type: string
+              enum: [ios, android]
+            bundle_id:
+              type: string
+              nullable: true
+
     # --- Auth Resources ---
 
     ShopkeeperSignIn:
@@ -708,6 +760,8 @@ tags:
     description: Email confirmation for shopkeeper accounts
   - name: Auth - Password Reset
     description: Forgot password and reset password flow
+  - name: Devices
+    description: Register and unregister mobile devices for push notifications
   - name: Permissions
     description: Retrieve permissions and app configuration metadata
   - name: Me
@@ -992,6 +1046,63 @@ paths:
           $ref: '#/components/responses/Unauthorized'
 
   # ──────────────── Permissions ────────────────
+  # ──────────────── Devices ────────────────
+  /devices:
+    post:
+      operationId: registerDevice
+      summary: Register a mobile device for push notifications (idempotent upsert)
+      tags: [Devices]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DeviceCreateRequest'
+      responses:
+        '201':
+          description: Device created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    $ref: '#/components/schemas/Device'
+        '200':
+          description: Device already registered, last_active_at touched
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    $ref: '#/components/schemas/Device'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+
+  /devices/{deviceId}:
+    parameters:
+      - name: deviceId
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+
+    delete:
+      operationId: unregisterDevice
+      summary: Unregister a mobile device (sign-out, app uninstall, etc.)
+      tags: [Devices]
+      responses:
+        '204':
+          description: Device deleted
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
   /permissions:
     get:
       operationId: listPermissions