@serviceai/api-spec 1.2.433 → 1.6.1

package/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: ServiceAi API
-  version: 1.2.433
+  version: 1.6.1
   description: >-
     Source-of-truth API contract for ServiceAi. Generated from `shared/schema.ts` Zod schemas by
     `scripts/build-api-spec.ts`. Versioning policy: see `docs/api-versioning.md`. The hand-written docs/ios-contract.md
@@ -32,6 +32,8 @@ tags:
     description: Job (project) lifecycle surface.
   - name: chatty
     description: Realtime voice-enabled AI assistant.
+  - name: checklists
+    description: 'Job checklists: the voice walk-through draft.'
   - name: time-tracking
     description: >-
       The clock. A work day is the master clock and the payroll number; time entries sit inside it and say where the
@@ -44,6 +46,18 @@ tags:
   - name: account
     description: 'The signed-in person''s own account: asking for it to be deleted.'
 components:
+  securitySchemes:
+    UserBearer:
+      type: http
+      scheme: bearer
+    BrowserSession:
+      type: apiKey
+      in: cookie
+      name: connect.sid
+    BrowserAuthCookie:
+      type: apiKey
+      in: cookie
+      name: auth_token
   schemas:
     ErrorEnvelope:
       type: object
@@ -89,7 +103,7 @@ components:
       properties:
         apiVersion:
           type: string
-          example: 1.2.433
+          example: 1.6.1
         minClientVersion:
           type: string
           example: 1.0.0
@@ -164,11 +178,11 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
         lastContactDate:
           type:
             - string
             - 'null'
+          format: date-time
         parentContactId:
           type:
             - integer
@@ -281,6 +295,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         qboLastPushedHash:
           type:
             - string
@@ -293,6 +308,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         deletedBy:
           type:
             - string
@@ -432,7 +448,6 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
         featureTier:
           type:
             - string
@@ -447,7 +462,6 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
         parentScanId:
           type:
             - integer
@@ -464,7 +478,6 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
         doorwayLinks:
           anyOf:
             - type: string
@@ -475,7 +488,6 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
           description: >-
             Persisted append-room doorway links on a composite scan. Each link carries both a `sourceOpeningKind` (the
             appended child scan's entry side — always `door` in practice, since iOS does not capture openings on a
@@ -493,7 +505,6 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
         cleanupPipelineVersion:
           type:
             - string
@@ -516,7 +527,6 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
         deviceTrack:
           anyOf:
             - type: string
@@ -527,15 +537,12 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
         referencePhotoKeys:
           type:
             - array
             - 'null'
           items:
-            type:
-              - string
-              - 'null'
+            type: string
         metricCorrection:
           type:
             - number
@@ -566,6 +573,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         captureMode:
           type:
             - string
@@ -580,6 +588,12 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
+        clientScanId:
+          type:
+            - string
+            - 'null'
+          maxLength: 64
         floorPlanAssetId:
           type:
             - string
@@ -614,6 +628,42 @@ components:
             - 'null'
           minimum: -2147483648
           maximum: 2147483647
+        sourceSketchId:
+          type:
+            - integer
+            - 'null'
+          minimum: -2147483648
+          maximum: 2147483647
+        takeoffPagePixelsPerMeter:
+          type:
+            - number
+            - 'null'
+          minimum: -140737488355328
+          maximum: 140737488355327
+        takeoffPageOffsetX:
+          type:
+            - number
+            - 'null'
+          minimum: -140737488355328
+          maximum: 140737488355327
+        takeoffPageOffsetY:
+          type:
+            - number
+            - 'null'
+          minimum: -140737488355328
+          maximum: 140737488355327
+        takeoffPageWidthPx:
+          type:
+            - integer
+            - 'null'
+          minimum: -2147483648
+          maximum: 2147483647
+        takeoffPageHeightPx:
+          type:
+            - integer
+            - 'null'
+          minimum: -2147483648
+          maximum: 2147483647
         floorId:
           type:
             - integer
@@ -632,6 +682,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         deletedBy:
           type:
             - string
@@ -687,10 +738,12 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         dueDate:
           type:
             - string
             - 'null'
+          format: date-time
         allDay:
           type:
             - boolean
@@ -713,7 +766,6 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
         assignedContactIds:
           anyOf:
             - type: string
@@ -724,7 +776,6 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
         isPersonal:
           type:
             - boolean
@@ -745,7 +796,6 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
         relatedFiles:
           anyOf:
             - type: string
@@ -756,7 +806,6 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
         reminder:
           type:
             - string
@@ -769,6 +818,7 @@ components:
             - 1_hour
             - 1_day
             - 1_week
+            - null
         reminderNotificationId:
           type:
             - integer
@@ -793,6 +843,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         parentTaskId:
           type:
             - integer
@@ -803,6 +854,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         isRecurrenceException:
           type:
             - boolean
@@ -817,7 +869,6 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
         displayIndex:
           type:
             - integer
@@ -828,6 +879,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         deletedBy:
           type:
             - string
@@ -865,6 +917,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         deletedBy:
           type:
             - string
@@ -916,15 +969,12 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
         tags:
           type:
             - array
             - 'null'
           items:
-            type:
-              - string
-              - 'null'
+            type: string
         uploadedBy:
           type:
             - string
@@ -933,6 +983,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         deletedBy:
           type:
             - string
@@ -971,6 +1022,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         deletedBy:
           type:
             - string
@@ -1063,7 +1115,6 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
         terms:
           type:
             - string
@@ -1080,14 +1131,17 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         sentAt:
           type:
             - string
             - 'null'
+          format: date-time
         approvedAt:
           type:
             - string
             - 'null'
+          format: date-time
         approvedBy:
           type:
             - string
@@ -1096,6 +1150,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         rejectionReason:
           type:
             - string
@@ -1104,6 +1159,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         signatureMeta:
           anyOf:
             - type: string
@@ -1114,7 +1170,6 @@ components:
               additionalProperties: {}
             - type: array
               items: {}
-            - type: 'null'
         signatureProvider:
           type:
             - string
@@ -1139,6 +1194,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         revisionNotes:
           type:
             - string
@@ -1147,6 +1203,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         convertedToInvoiceId:
           type:
             - integer
@@ -1157,6 +1214,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         voidedBy:
           type:
             - string
@@ -1189,6 +1247,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         qboId:
           type:
             - string
@@ -1201,6 +1260,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         qboLastPushedHash:
           type:
             - string
@@ -1221,6 +1281,17 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
+        sourceKind:
+          type:
+            - string
+            - 'null'
+        takeoffScanId:
+          type:
+            - integer
+            - 'null'
+          minimum: -2147483648
+          maximum: 2147483647
         createdBy:
           type:
             - string
@@ -1229,6 +1300,7 @@ components:
           type:
             - string
             - 'null'
+          format: date-time
         deletedBy:
           type:
             - string
@@ -1342,8 +1414,10 @@ components:
                               type: boolean
                             isOpening:
                               type: boolean
+                          additionalProperties: {}
                         captureMethod:
                           type: string
+                      additionalProperties: {}
                   doors:
                     type: array
                     items:
@@ -1365,6 +1439,10 @@ components:
                         height:
                           type: number
                           exclusiveMinimum: 0
+                        sillHeightM:
+                          type: number
+                          minimum: 0
+                          maximum: 50
                         hostWallIndex:
                           type:
                             - integer
@@ -1375,13 +1453,13 @@ components:
                           minimum: 0
                         swingHand:
                           type: string
-                          enum: &ref_0
+                          enum:
                             - left
                             - right
                             - none
                         placementSource:
                           type: string
-                          enum: &ref_1
+                          enum:
                             - auto
                             - manual
                       required:
@@ -1409,6 +1487,10 @@ components:
                         height:
                           type: number
                           exclusiveMinimum: 0
+                        sillHeightM:
+                          type: number
+                          minimum: 0
+                          maximum: 50
                         hostWallIndex:
                           type:
                             - integer
@@ -1419,10 +1501,15 @@ components:
                           minimum: 0
                         swingHand:
                           type: string
-                          enum: *ref_0
+                          enum:
+                            - left
+                            - right
+                            - none
                         placementSource:
                           type: string
-                          enum: *ref_1
+                          enum:
+                            - auto
+                            - manual
                       required:
                         - position
                         - width
@@ -1448,6 +1535,10 @@ components:
                         height:
                           type: number
                           exclusiveMinimum: 0
+                        sillHeightM:
+                          type: number
+                          minimum: 0
+                          maximum: 50
                         hostWallIndex:
                           type:
                             - integer
@@ -1458,10 +1549,15 @@ components:
                           minimum: 0
                         swingHand:
                           type: string
-                          enum: *ref_0
+                          enum:
+                            - left
+                            - right
+                            - none
                         placementSource:
                           type: string
-                          enum: *ref_1
+                          enum:
+                            - auto
+                            - manual
                       required:
                         - position
                         - width
@@ -1500,6 +1596,7 @@ components:
                       required:
                         - id
                         - position
+                      additionalProperties: {}
                   objects:
                     type: array
                     items:
@@ -1528,6 +1625,7 @@ components:
                               type: number
                         rotation:
                           type: number
+                      additionalProperties: {}
                   boundaryPolygon:
                     type: array
                     items:
@@ -1545,6 +1643,7 @@ components:
                     maxLength: 4096
                   entryDoorwayId:
                     type: string
+                additionalProperties: {}
                 description: >-
                   Mobile-upload scan room. `doors`, `windows`, and `openings` are three distinct non-overlapping arrays
                   — array membership IS the discriminator (there is no `kind` / `type` field on the item itself).
@@ -1554,6 +1653,7 @@ components:
                   an `entryDoorwayId` target.
           required:
             - rooms
+          additionalProperties: {}
           description: >-
             RoomPlan JSON envelope. `rooms[]` carries the per-room geometry
             (walls/doors/windows/openings/pins/objects/boundaryPolygon). iOS continues to upload positions in the
@@ -1701,6 +1801,7 @@ components:
       required:
         - roomPlanJSON
         - name
+      additionalProperties: {}
       description: >-
         POST /api/jobs/:jobId/scans/mobile-upload body. v5 of the LiDAR contract (Task #879) — additive over v3/v4.
         Required: `roomPlanJSON` (object with nested `rooms` array) + `name`. All v3 and v4 payloads remain accepted
@@ -1755,6 +1856,29 @@ components:
         - manualMeasurements
         - scanRoomSnapshots
         - roomConnections
+    EventStreamTicketResponse:
+      type: object
+      properties:
+        ticket:
+          type: string
+          minLength: 1
+          maxLength: 8192
+      required:
+        - ticket
+      additionalProperties: false
+    StreamAuthenticationError:
+      type: object
+      properties:
+        message:
+          type: string
+        code:
+          type: string
+          enum:
+            - IMPERSONATION_UNAVAILABLE
+            - SUPPORT_IMPERSONATION_UNAVAILABLE
+            - auth_unavailable
+      required:
+        - message
     JobSummary:
       type: object
       properties:
@@ -2174,7 +2298,7 @@ components:
           description: Null at the office — see siteType.
         siteType:
           type: string
-          enum: &ref_2
+          enum:
             - job
             - office
         workDayId:
@@ -2213,8 +2337,8 @@ components:
             - 'null'
         source:
           type: string
-          description: '''manual'' (a button press) or ''auto'' (the resolver).'
           example: auto
+          description: '''manual'' (a button press) or ''auto'' (the resolver).'
         excludedFromBudget:
           type: boolean
           description: >-
@@ -2263,6 +2387,7 @@ components:
           enum:
             - away
             - no_location
+            - null
           description: >-
             Job time started by hand away from the job ('away') or with no usable location ('no_location'); null for a
             normal start. The office decides it.
@@ -2279,6 +2404,7 @@ components:
             - approved
             - not_approved
             - moved
+            - null
           description: >-
             The office's decision on a flagged start; null while it waits. 'not_approved' stays on the timesheet but off
             the job's costing.
@@ -2379,8 +2505,8 @@ components:
           description: Null while the day is running.
         openedBy:
           type: string
-          description: '''tech'' (the button), ''admin'', or ''job_clock_in''.'
           example: tech
+          description: '''tech'' (the button), ''admin'', or ''job_clock_in''.'
         closedBy:
           type:
             - string
@@ -2685,7 +2811,9 @@ components:
           description: Null for the office fence (siteType 'office').
         siteType:
           type: string
-          enum: *ref_2
+          enum:
+            - job
+            - office
         jobName:
           type: string
         jobNumber:
@@ -2752,7 +2880,9 @@ components:
             - 'null'
         siteType:
           type: string
-          enum: *ref_2
+          enum:
+            - job
+            - office
           description: Defaults to 'office' when jobId is null, else 'job'.
         kind:
           type: string
@@ -2788,10 +2918,11 @@ components:
           type:
             - string
             - 'null'
-          enum: &ref_5
+          enum:
             - ios
             - web
             - android
+            - null
         autoClockEnabled:
           type: boolean
           description: The user's auto-clock toggle at crossing time. False → the crossing is logged but never acted on.
@@ -2843,8 +2974,8 @@ components:
           type:
             - string
             - 'null'
-          description: Why the batch was dropped. On 'no_consent' the client should clear its queue rather than retry.
           example: no_consent
+          description: Why the batch was dropped. On 'no_consent' the client should clear its queue rather than retry.
         resolver:
           type:
             - object
@@ -2894,16 +3025,16 @@ components:
           type: boolean
         dwellSeconds:
           type: integer
-          description: >-
-            How long a device must stay on one side of a fence before it counts. A choice from a fixed set of steps, not
-            a free number: a tech driving past a job must not be clocked in, and one walking in must not wait. An older
-            org may still have a free value stored; the server snaps it to the nearest step, so read this value rather
-            than assuming what was configured.
           enum:
             - 30
             - 60
             - 100
             - 120
+          description: >-
+            How long a device must stay on one side of a fence before it counts. A choice from a fixed set of steps, not
+            a free number: a tech driving past a job must not be clocked in, and one walking in must not wait. An older
+            org may still have a free value stored; the server snaps it to the nearest step, so read this value rather
+            than assuming what was configured.
         staleShiftHours:
           type: integer
         autoCloseHours:
@@ -3045,14 +3176,14 @@ components:
           type:
             - string
             - 'null'
-          description: '''HH:MM'' local. Null = all day, and always null for ''off'' and ''pto''.'
           example: '08:00'
+          description: '''HH:MM'' local. Null = all day, and always null for ''off'' and ''pto''.'
         endTime:
           type:
             - string
             - 'null'
-          description: An end at or before the start means the shift runs overnight into the next day.
           example: '17:00'
+          description: An end at or before the start means the shift runs overnight into the next day.
         kind:
           type: string
           enum:
@@ -3115,7 +3246,7 @@ components:
             - rejected
         kind:
           type: string
-          enum: &ref_7
+          enum:
             - pto
             - sick
             - 'off'
@@ -3323,82 +3454,1317 @@ components:
       description: >-
         The signed-in person's request to have their account deleted. pending: waiting for the company; completed: the
         company marked it done; cancelled: the company cancelled it (asking again starts a new one).
-  parameters: {}
-paths:
-  /api/version:
-    get:
-      summary: Cross-platform version handshake manifest.
-      tags:
-        - version
-      responses:
-        '200':
-          description: Always returned. Body is the canonical handshake manifest.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/VersionManifest'
-  /api/ping:
-    get:
-      summary: Liveness probe. Bypasses the version handshake.
-      tags:
-        - version
-      responses:
-        '200':
-          description: Static OK envelope.
+    DoorwayEditCommand:
+      oneOf:
+        - type: object
+          properties:
+            action:
+              type: string
+              enum:
+                - delete
+            roomId:
+              type: integer
+              exclusiveMinimum: 0
+            openingId:
+              type: string
+              pattern: ^[A-Za-z0-9:_-]{1,128}$
+            revision:
+              type: string
+              pattern: ^[a-f0-9]{64}$
+            confirmed:
+              type: boolean
+              enum:
+                - true
+          required:
+            - action
+            - roomId
+            - openingId
+            - revision
+            - confirmed
+          additionalProperties: false
+        - type: object
+          properties:
+            action:
+              type: string
+              enum:
+                - undo
+            token:
+              type: string
+              minLength: 1
+              maxLength: 1500100
+          required:
+            - action
+            - token
+          additionalProperties: false
+        - type: object
+          properties:
+            action:
+              type: string
+              enum:
+                - connect
+            rooms:
+              type: array
+              items:
+                type: object
+                properties:
+                  id:
+                    type: integer
+                    exclusiveMinimum: 0
+                  revision:
+                    type: string
+                    pattern: ^[a-f0-9]{64}$
+                  geometry:
+                    type: object
+                    additionalProperties: {}
+                required:
+                  - id
+                  - revision
+                  - geometry
+                additionalProperties: false
+            links:
+              type: array
+              items:
+                type: object
+                properties:
+                  roomAId:
+                    type: integer
+                    exclusiveMinimum: 0
+                  roomBId:
+                    type: integer
+                    exclusiveMinimum: 0
+                  doorAIndex:
+                    type: integer
+                    minimum: 0
+                    maximum: 63
+                  doorBIndex:
+                    type: integer
+                    minimum: 0
+                    maximum: 63
+                required:
+                  - roomAId
+                  - roomBId
+                  - doorAIndex
+                  - doorBIndex
+                additionalProperties: false
+              minItems: 1
+              maxItems: 64
+          required:
+            - action
+            - rooms
+            - links
+          additionalProperties: false
+    DoorwayEditResult:
+      type: object
+      properties:
+        ok:
+          type: boolean
+          enum:
+            - true
+        token:
+          type: string
+        roomIds:
+          type: array
+          items:
+            type: integer
+      required:
+        - ok
+        - token
+        - roomIds
+    WalkthroughDraftRequest:
+      type: object
+      properties:
+        transcript:
+          type: array
+          items:
+            type: object
+            properties:
+              text:
+                type: string
+                minLength: 1
+                maxLength: 1000
+              startedAt:
+                type: string
+                format: date-time
+              endedAt:
+                type: string
+                format: date-time
+            required:
+              - text
+              - startedAt
+              - endedAt
+          minItems: 1
+          maxItems: 400
+        photos:
+          type: array
+          items:
+            type: object
+            properties:
+              assetId:
+                type: string
+                minLength: 1
+                maxLength: 64
+              capturedAt:
+                type: string
+                format: date-time
+              roomHint:
+                type:
+                  - string
+                  - 'null'
+                maxLength: 200
+              sketchRoomId:
+                type:
+                  - integer
+                  - 'null'
+                exclusiveMinimum: 0
+              capturePose:
+                type:
+                  - object
+                  - 'null'
+                properties:
+                  x:
+                    type: number
+                  'y':
+                    type: number
+                  z:
+                    type: number
+                  floorId:
+                    type:
+                      - integer
+                      - 'null'
+                    exclusiveMinimum: 0
+                  sketchId:
+                    type:
+                      - integer
+                      - 'null'
+                    exclusiveMinimum: 0
+                  scanSessionId:
+                    type: string
+                    maxLength: 64
+                  scanRoomLocalId:
+                    type: string
+                    maxLength: 128
+                  scanRoomName:
+                    type: string
+                    maxLength: 200
+            required:
+              - assetId
+              - capturedAt
+          maxItems: 200
+        sections:
+          type: array
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+                minLength: 1
+                maxLength: 200
+              startedAt:
+                type: string
+                format: date-time
+              sketchRoomId:
+                type:
+                  - integer
+                  - 'null'
+                exclusiveMinimum: 0
+            required:
+              - name
+              - startedAt
+          maxItems: 100
+        roomsFrom:
+          type: string
+          enum:
+            - speech
+            - scan
+      required:
+        - transcript
+    ChecklistDraft:
+      type: object
+      properties:
+        name:
+          type: string
+        sections:
+          type: array
+          items:
+            type: object
+            properties:
+              key:
+                type: string
+              title:
+                type: string
+              sketchRoomId:
+                type:
+                  - integer
+                  - 'null'
+              kind:
+                type: string
+                enum:
+                  - room
+                  - custom
+                  - not_sure
+              items:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    key:
+                      type: string
+                    itemText:
+                      type: string
+                    description:
+                      type:
+                        - string
+                        - 'null'
+                    itemType:
+                      type: string
+                      enum:
+                        - checkbox
+                        - yes/no
+                        - text
+                        - number
+                        - date
+                        - dropdown
+                        - multi-select
+                        - photo
+                        - signature
+                    required:
+                      type: boolean
+                    options:
+                      type:
+                        - object
+                        - 'null'
+                      additionalProperties: {}
+                    referenceMedia:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          assetId:
+                            type: string
+                            minLength: 1
+                            maxLength: 64
+                          caption:
+                            type:
+                              - string
+                              - 'null'
+                            maxLength: 300
+                          order:
+                            type: integer
+                            minimum: 0
+                        required:
+                          - assetId
+                      maxItems: 10
+                    hints:
+                      type: array
+                      items:
+                        type: string
+                        enum:
+                          - photo_required
+                          - yes_no
+                          - required
+                          - reading
+                    roomSource:
+                      type: string
+                      enum:
+                        - pose
+                        - named
+                        - vision
+                        - time
+                        - none
+                    spokenAt:
+                      type: string
+                    quote:
+                      type:
+                        - string
+                        - 'null'
+                  required:
+                    - key
+                    - itemText
+                    - description
+                    - itemType
+                    - required
+                    - options
+                    - referenceMedia
+                    - hints
+                    - roomSource
+                    - spokenAt
+                    - quote
+            required:
+              - key
+              - title
+              - sketchRoomId
+              - kind
+              - items
+        photos:
+          type: array
+          items:
+            type: object
+            properties:
+              assetId:
+                type: string
+              capturedAt:
+                type: string
+              sectionKey:
+                type:
+                  - string
+                  - 'null'
+              roomSource:
+                type: string
+                enum:
+                  - pose
+                  - named
+                  - vision
+                  - time
+                  - none
+              itemKeys:
+                type: array
+                items:
+                  type: string
+            required:
+              - assetId
+              - capturedAt
+              - sectionKey
+              - roomSource
+              - itemKeys
+        visionUsed:
+          type: boolean
+        model:
+          type:
+            - string
+            - 'null'
+        promptVersion:
+          type: string
+      required:
+        - name
+        - sections
+        - photos
+        - visionUsed
+        - model
+        - promptVersion
+    WalkthroughDraftResponse:
+      type: object
+      properties:
+        status:
+          type: string
+          enum:
+            - completed
+            - running
+            - failed
+        runId:
+          type:
+            - integer
+            - 'null'
+        draft:
+          type:
+            - object
+            - 'null'
+          properties:
+            name:
+              type: string
+            sections:
+              type: array
+              items:
+                type: object
+                properties:
+                  key:
+                    type: string
+                  title:
+                    type: string
+                  sketchRoomId:
+                    type:
+                      - integer
+                      - 'null'
+                  kind:
+                    type: string
+                    enum:
+                      - room
+                      - custom
+                      - not_sure
+                  items:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        key:
+                          type: string
+                        itemText:
+                          type: string
+                        description:
+                          type:
+                            - string
+                            - 'null'
+                        itemType:
+                          type: string
+                          enum:
+                            - checkbox
+                            - yes/no
+                            - text
+                            - number
+                            - date
+                            - dropdown
+                            - multi-select
+                            - photo
+                            - signature
+                        required:
+                          type: boolean
+                        options:
+                          type:
+                            - object
+                            - 'null'
+                          additionalProperties: {}
+                        referenceMedia:
+                          type: array
+                          items:
+                            type: object
+                            properties:
+                              assetId:
+                                type: string
+                                minLength: 1
+                                maxLength: 64
+                              caption:
+                                type:
+                                  - string
+                                  - 'null'
+                                maxLength: 300
+                              order:
+                                type: integer
+                                minimum: 0
+                            required:
+                              - assetId
+                          maxItems: 10
+                        hints:
+                          type: array
+                          items:
+                            type: string
+                            enum:
+                              - photo_required
+                              - yes_no
+                              - required
+                              - reading
+                        roomSource:
+                          type: string
+                          enum:
+                            - pose
+                            - named
+                            - vision
+                            - time
+                            - none
+                        spokenAt:
+                          type: string
+                        quote:
+                          type:
+                            - string
+                            - 'null'
+                      required:
+                        - key
+                        - itemText
+                        - description
+                        - itemType
+                        - required
+                        - options
+                        - referenceMedia
+                        - hints
+                        - roomSource
+                        - spokenAt
+                        - quote
+                required:
+                  - key
+                  - title
+                  - sketchRoomId
+                  - kind
+                  - items
+            photos:
+              type: array
+              items:
+                type: object
+                properties:
+                  assetId:
+                    type: string
+                  capturedAt:
+                    type: string
+                  sectionKey:
+                    type:
+                      - string
+                      - 'null'
+                  roomSource:
+                    type: string
+                    enum:
+                      - pose
+                      - named
+                      - vision
+                      - time
+                      - none
+                  itemKeys:
+                    type: array
+                    items:
+                      type: string
+                required:
+                  - assetId
+                  - capturedAt
+                  - sectionKey
+                  - roomSource
+                  - itemKeys
+            visionUsed:
+              type: boolean
+            model:
+              type:
+                - string
+                - 'null'
+            promptVersion:
+              type: string
+          required:
+            - name
+            - sections
+            - photos
+            - visionUsed
+            - model
+            - promptVersion
+        sortRun:
+          type:
+            - object
+            - 'null'
+          properties:
+            status:
+              type: string
+              enum:
+                - running
+                - completed
+                - failed
+            total:
+              type: integer
+            done:
+              type: integer
+          required:
+            - status
+            - total
+            - done
+        message:
+          type:
+            - string
+            - 'null'
+      required:
+        - status
+        - runId
+        - draft
+        - sortRun
+        - message
+    ChattyListJobChecklistsArguments:
+      type: object
+      properties:
+        jobId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+      description: '`arguments` of the Chatty tool `list_job_checklists` (POST /api/chatty-voice/tools/execute).'
+    ChattyListJobChecklistsData:
+      type: array
+      items:
+        type: object
+        properties:
+          id:
+            type: integer
+          name:
+            type: string
+          status:
+            type:
+              - string
+              - 'null'
+          completionPercentage:
+            type: number
+          templateId:
+            type:
+              - integer
+              - 'null'
+        required:
+          - id
+          - name
+          - status
+          - completionPercentage
+          - templateId
+      description: '`data` of a successful `list_job_checklists` call (`success: true`).'
+    ChattyGetChecklistArguments:
+      type: object
+      properties:
+        checklistId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        checklistName:
+          type: string
+        jobId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+      description: '`arguments` of the Chatty tool `get_checklist` (POST /api/chatty-voice/tools/execute).'
+    ChattyGetChecklistData:
+      type: object
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        status:
+          type:
+            - string
+            - 'null'
+        completionPercentage:
+          type: number
+        jobId:
+          type:
+            - integer
+            - 'null'
+        items:
+          type: array
+          items:
+            type: object
+            properties:
+              id:
+                type: integer
+              itemText:
+                type: string
+              itemType:
+                type: string
+              required:
+                type: boolean
+              done:
+                type: boolean
+              value:
+                type:
+                  - string
+                  - 'null'
+              section:
+                type:
+                  - string
+                  - 'null'
+              referencePhotos:
+                type: integer
+            required:
+              - id
+              - itemText
+              - itemType
+              - required
+              - done
+              - value
+              - section
+              - referencePhotos
+      required:
+        - id
+        - name
+        - status
+        - completionPercentage
+        - jobId
+        - items
+      description: '`data` of a successful `get_checklist` call (`success: true`).'
+    ChattyCreateChecklistArguments:
+      type: object
+      properties:
+        jobId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        name:
+          type: string
+        templateId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        templateName:
+          type: string
+        notes:
+          type: string
+        items:
+          type: array
+          items:
+            type: string
+      description: '`arguments` of the Chatty tool `create_checklist` (POST /api/chatty-voice/tools/execute).'
+    ChattyCreateChecklistData:
+      type: object
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        jobId:
+          type: integer
+        itemCount:
+          type: integer
+        templateId:
+          type: integer
+        sections:
+          type: array
+          items:
+            type: object
+            properties:
+              title:
+                type: string
+              items:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    itemText:
+                      type: string
+                    itemType:
+                      type: string
+                      enum:
+                        - checkbox
+                        - yes/no
+                        - text
+                        - number
+                        - date
+                        - dropdown
+                        - multi-select
+                        - photo
+                        - signature
+                    required:
+                      type: boolean
+                  required:
+                    - itemText
+                    - itemType
+                    - required
+            required:
+              - title
+              - items
+      required:
+        - id
+        - name
+        - jobId
+        - itemCount
+      description: '`data` of a successful `create_checklist` call (`success: true`).'
+    ChattyAddChecklistItemArguments:
+      type: object
+      properties:
+        checklistId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        checklistName:
+          type: string
+        jobId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        itemText:
+          type: string
+        itemType:
+          type: string
+          enum:
+            - checkbox
+            - yes/no
+            - text
+            - number
+            - date
+            - dropdown
+            - multi-select
+            - photo
+            - signature
+        required:
+          type: boolean
+        description:
+          type: string
+        sectionName:
+          type: string
+      required:
+        - itemText
+      description: '`arguments` of the Chatty tool `add_checklist_item` (POST /api/chatty-voice/tools/execute).'
+    ChattyAddChecklistItemData:
+      type: object
+      properties:
+        id:
+          type: integer
+        checklistId:
+          type: integer
+        itemText:
+          type: string
+        itemType:
+          type: string
+          enum:
+            - checkbox
+            - yes/no
+            - text
+            - number
+            - date
+            - dropdown
+            - multi-select
+            - photo
+            - signature
+        required:
+          type: boolean
+        section:
+          type:
+            - string
+            - 'null'
+      required:
+        - id
+        - checklistId
+        - itemText
+        - itemType
+        - required
+        - section
+      description: '`data` of a successful `add_checklist_item` call (`success: true`).'
+    ChattyCompleteChecklistItemArguments:
+      type: object
+      properties:
+        checklistId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        checklistName:
+          type: string
+        jobId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        itemId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        itemText:
+          type: string
+        completed:
+          type: boolean
+      description: '`arguments` of the Chatty tool `complete_checklist_item` (POST /api/chatty-voice/tools/execute).'
+    ChattyCompleteChecklistItemData:
+      type: object
+      properties:
+        checklistId:
+          type: integer
+        itemId:
+          type: integer
+        completed:
+          type: boolean
+      required:
+        - checklistId
+        - itemId
+        - completed
+      description: '`data` of a successful `complete_checklist_item` call (`success: true`).'
+    ChattySetChecklistItemAnswerArguments:
+      type: object
+      properties:
+        checklistId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        checklistName:
+          type: string
+        jobId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        itemId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        itemText:
+          type: string
+        value:
+          type: string
+      required:
+        - value
+      description: '`arguments` of the Chatty tool `set_checklist_item_answer` (POST /api/chatty-voice/tools/execute).'
+    ChattySetChecklistItemAnswerData:
+      type: object
+      properties:
+        checklistId:
+          type: integer
+        itemId:
+          type: integer
+        value:
+          type: string
+      required:
+        - checklistId
+        - itemId
+        - value
+      description: '`data` of a successful `set_checklist_item_answer` call (`success: true`).'
+    ChattyAttachReferencePhotoToItemArguments:
+      type: object
+      properties:
+        checklistId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        checklistName:
+          type: string
+        jobId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        itemId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        itemText:
+          type: string
+        photoId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        caption:
+          type: string
+      required:
+        - photoId
+      description: '`arguments` of the Chatty tool `attach_reference_photo_to_item` (POST /api/chatty-voice/tools/execute).'
+    ChattyAttachReferencePhotoToItemData:
+      type: object
+      properties:
+        checklistId:
+          type: integer
+        itemId:
+          type: integer
+        referenceMedia:
+          type: array
+          items:
+            type: object
+            properties:
+              assetId:
+                type: string
+                minLength: 1
+                maxLength: 64
+              caption:
+                type:
+                  - string
+                  - 'null'
+                maxLength: 300
+              order:
+                type: integer
+                minimum: 0
+            required:
+              - assetId
+      required:
+        - checklistId
+        - itemId
+        - referenceMedia
+      description: '`data` of a successful `attach_reference_photo_to_item` call (`success: true`).'
+    ChattyDraftChecklistFromJobPhotosArguments:
+      type: object
+      properties:
+        jobId:
+          anyOf:
+            - type: integer
+              exclusiveMinimum: 0
+            - type: string
+              pattern: ^\d+$
+        name:
+          type: string
+        create:
+          type: boolean
+      description: '`arguments` of the Chatty tool `draft_checklist_from_job_photos` (POST /api/chatty-voice/tools/execute).'
+    ChattyDraftChecklistFromJobPhotosData:
+      type: object
+      properties:
+        id:
+          type: integer
+        jobId:
+          type: integer
+        name:
+          type: string
+        items:
+          type: array
+          items:
+            type: object
+            properties:
+              itemText:
+                type: string
+              photos:
+                type: integer
+            required:
+              - itemText
+              - photos
+        unsortedPhotos:
+          type: integer
+        created:
+          type: boolean
+      required:
+        - name
+        - items
+        - unsortedPhotos
+        - created
+      description: '`data` of a successful `draft_checklist_from_job_photos` call (`success: true`).'
+  parameters: {}
+paths:
+  /api/version:
+    get:
+      summary: Cross-platform version handshake manifest.
+      tags:
+        - version
+      responses:
+        '200':
+          description: Always returned. Body is the canonical handshake manifest.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VersionManifest'
+  /api/ping:
+    get:
+      summary: Liveness probe. Bypasses the version handshake.
+      tags:
+        - version
+      responses:
+        '200':
+          description: Static OK envelope.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    enum:
+                      - ok
+                  timestamp:
+                    type: string
+                  env:
+                    type:
+                      - string
+                      - 'null'
+                required:
+                  - status
+                  - timestamp
+                  - env
+  /api/me/features:
+    get:
+      summary: Capability discovery — iOS calls on launch to gate UI affordances.
+      tags:
+        - auth
+        - features
+      parameters:
+        - &ref_0
+          name: X-Client-Version
+          in: header
+          required: false
+          schema:
+            type: string
+            example: 1.0.0
+          description: Semver of the calling app build. Drives the 426 / soft-upgrade handshake.
+      responses:
+        '200':
+          description: Flat feature map. Unknown / missing flags must be treated as false by the client.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FeatureFlags'
+        '426':
+          description: Client major below minClientVersion.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UpgradeRequiredEnvelope'
+  /api/impersonate/native-read-ticket:
+    post:
+      tags:
+        - auth
+      summary: Authorize an exact browser-native download URL for the current support session.
+      description: >-
+        Requires the current typed support session and X-Support-Impersonation: 1. A narrow fixed GET allowlist only;
+        record permissions still run on every GET. Admission lasts at most 15 minutes and never outlives the original
+        one-hour support grant. The same browser session is required; URL alone is insufficient. GET/Range retries
+        recheck current authority. Response is no-store with no-referrer. No user bearer is issued.
+      security:
+        - BrowserSession: []
+      parameters:
+        - schema:
+            type: string
+            enum:
+              - '1'
+          required: true
+          name: X-Support-Impersonation
+          in: header
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                url:
+                  type: string
+                  minLength: 1
+                  maxLength: 1024
+              required:
+                - url
+              additionalProperties: false
+      responses:
+        '200':
+          description: Exact relative URL and terminal admission deadline.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  url:
+                    type: string
+                    minLength: 1
+                    maxLength: 8192
+                  expiresAt:
+                    type: integer
+                    exclusiveMinimum: 0
+                required:
+                  - url
+                  - expiresAt
+                additionalProperties: false
+        '400':
+          description: Unsupported destination or malformed request.
+        '401':
+          description: No authenticated session.
+        '403':
+          description: Support authority unavailable; explicit exit required.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StreamAuthenticationError'
+        '503':
+          description: Authentication lookup temporarily unavailable.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StreamAuthenticationError'
+  /api/events/ticket:
+    post:
+      tags:
+        - auth
+      summary: Create a short-lived stream-only admission ticket from the current authenticated actor.
+      description: >-
+        Connect within at most 60 seconds using GET /api/events?ticket=.... The ticket preserves the real principal,
+        effective target and original login/impersonation deadlines; it cannot authenticate ordinary API requests. It is
+        never a target-user bearer token. Response Cache-Control is no-store. An invalid temporary context returns 403
+        and must be explicitly exited, without dropping the real login.
+      security:
+        - UserBearer: []
+        - BrowserSession: []
+        - BrowserAuthCookie: []
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties: {}
+              additionalProperties: false
+      responses:
+        '200':
+          description: Opaque ticket, usable only for short-lived stream admission.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EventStreamTicketResponse'
+        '400':
+          description: Unexpected request fields.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                  errors:
+                    type: array
+                    items: {}
+                required:
+                  - message
+                  - errors
+        '401':
+          description: Real principal is missing, deleted, revoked or expired.
           content:
             application/json:
               schema:
-                type: object
-                properties:
-                  status:
-                    type: string
-                    enum:
-                      - ok
-                  timestamp:
-                    type: string
-                  env:
-                    type:
-                      - string
-                      - 'null'
-                required:
-                  - status
-                  - timestamp
-                  - env
-  /api/me/features:
+                $ref: '#/components/schemas/StreamAuthenticationError'
+        '403':
+          description: Impersonation is unavailable; explicitly exit before continuing as the real principal.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StreamAuthenticationError'
+        '503':
+          description: Authentication lookup unavailable; retry without discarding credentials.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StreamAuthenticationError'
+  /api/events:
     get:
-      summary: Capability discovery — iOS calls on launch to gate UI affordances.
       tags:
         - auth
-        - features
+      summary: Open the authenticated server-sent event stream.
+      description: >-
+        New clients use a stream-only ticket in the ticket query parameter. Legacy authenticated connections remain
+        supported. A supplied invalid ticket never falls back to another credential. Current user, session and
+        revocation state is rechecked before admission and each delivery batch/heartbeat. Original authority deadlines
+        also close idle or blocked sockets. A stream:resync hint means refresh authorized snapshots; this stream is not
+        a replay log.
       parameters:
-        - &ref_3
-          name: X-Client-Version
-          in: header
-          required: false
-          schema:
+        - schema:
             type: string
-            example: 1.0.0
-          description: Semver of the calling app build. Drives the 426 / soft-upgrade handshake.
+            minLength: 1
+            maxLength: 8192
+          required: false
+          name: ticket
+          in: query
       responses:
         '200':
-          description: Flat feature map. Unknown / missing flags must be treated as false by the client.
+          description: Bounded SSE hints and heartbeat comments until disconnect or authority expiry.
+          content:
+            text/event-stream:
+              schema:
+                type: string
+        '401':
+          description: Ticket/source authentication expired, revoked or invalid.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/FeatureFlags'
-        '426':
-          description: Client major below minClientVersion.
+                $ref: '#/components/schemas/StreamAuthenticationError'
+        '403':
+          description: Legacy temporary context is unavailable.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/UpgradeRequiredEnvelope'
+                $ref: '#/components/schemas/StreamAuthenticationError'
+        '503':
+          description: Authorization temporarily unavailable; retry with backoff.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StreamAuthenticationError'
   /api/jobs/{jobId}/scans/mobile-upload:
     post:
       summary: iOS LiDAR scan upload. v2 fields are additive — v1 payloads remain byte-identical.
       tags:
         - lidar
       parameters:
-        - *ref_3
+        - *ref_0
         - schema:
             type: integer
             exclusiveMinimum: 0
@@ -3453,7 +4819,7 @@ paths:
       tags:
         - lidar
       parameters:
-        - *ref_3
+        - *ref_0
         - schema:
             type: integer
             exclusiveMinimum: 0
@@ -3586,7 +4952,7 @@ paths:
       tags:
         - jobs
       parameters:
-        - *ref_3
+        - *ref_0
       responses:
         '200':
           description: Array of jobs.
@@ -3607,7 +4973,7 @@ paths:
       tags:
         - jobs
       parameters:
-        - *ref_3
+        - *ref_0
       requestBody:
         content:
           application/json:
@@ -3632,7 +4998,7 @@ paths:
       tags:
         - jobs
       parameters:
-        - *ref_3
+        - *ref_0
         - schema:
             type: integer
             exclusiveMinimum: 0
@@ -3664,7 +5030,7 @@ paths:
       tags:
         - chatty
       parameters:
-        - *ref_3
+        - *ref_0
       requestBody:
         content:
           application/json:
@@ -3701,7 +5067,7 @@ paths:
       tags:
         - chatty
       parameters:
-        - *ref_3
+        - *ref_0
         - schema:
             type: string
           required: true
@@ -3734,7 +5100,7 @@ paths:
       tags:
         - chatty
       parameters:
-        - *ref_3
+        - *ref_0
         - schema:
             type: string
           required: true
@@ -3761,7 +5127,7 @@ paths:
       tags:
         - auth
       parameters:
-        - *ref_3
+        - *ref_0
       responses:
         '200':
           description: Authenticated user.
@@ -3787,7 +5153,7 @@ paths:
       tags:
         - crm
       parameters:
-        - *ref_3
+        - *ref_0
       responses:
         '200':
           description: Array of contacts.
@@ -3845,11 +5211,11 @@ paths:
                               additionalProperties: {}
                             - type: array
                               items: {}
-                            - type: 'null'
                         lastContactDate:
                           type:
                             - string
                             - 'null'
+                          format: date-time
                         parentContactId:
                           type:
                             - integer
@@ -3962,6 +5328,7 @@ paths:
                           type:
                             - string
                             - 'null'
+                          format: date-time
                         qboLastPushedHash:
                           type:
                             - string
@@ -3974,6 +5341,7 @@ paths:
                           type:
                             - string
                             - 'null'
+                          format: date-time
                         deletedBy:
                           type:
                             - string
@@ -3997,7 +5365,7 @@ paths:
       tags:
         - crm
       parameters:
-        - *ref_3
+        - *ref_0
       requestBody:
         content:
           application/json:
@@ -4050,11 +5418,11 @@ paths:
                       additionalProperties: {}
                     - type: array
                       items: {}
-                    - type: 'null'
                 lastContactDate:
                   type:
                     - string
                     - 'null'
+                  format: date-time
                 parentContactId:
                   type:
                     - integer
@@ -4167,6 +5535,7 @@ paths:
                   type:
                     - string
                     - 'null'
+                  format: date-time
                 qboLastPushedHash:
                   type:
                     - string
@@ -4179,6 +5548,7 @@ paths:
                   type:
                     - string
                     - 'null'
+                  format: date-time
                 deletedBy:
                   type:
                     - string
@@ -4240,11 +5610,11 @@ paths:
                             additionalProperties: {}
                           - type: array
                             items: {}
-                          - type: 'null'
                       lastContactDate:
                         type:
                           - string
                           - 'null'
+                        format: date-time
                       parentContactId:
                         type:
                           - integer
@@ -4357,6 +5727,7 @@ paths:
                         type:
                           - string
                           - 'null'
+                        format: date-time
                       qboLastPushedHash:
                         type:
                           - string
@@ -4369,6 +5740,7 @@ paths:
                         type:
                           - string
                           - 'null'
+                        format: date-time
                       deletedBy:
                         type:
                           - string
@@ -4393,7 +5765,7 @@ paths:
       tags:
         - photos
       parameters:
-        - *ref_3
+        - *ref_0
         - schema:
             type: integer
             exclusiveMinimum: 0
@@ -4436,7 +5808,7 @@ paths:
       tags:
         - lidar
       parameters:
-        - *ref_3
+        - *ref_0
         - schema:
             type: integer
             exclusiveMinimum: 0
@@ -4459,7 +5831,7 @@ paths:
       tags:
         - lidar
       parameters:
-        - *ref_3
+        - *ref_0
         - schema:
             type: integer
             exclusiveMinimum: 0
@@ -4506,6 +5878,10 @@ paths:
                               height:
                                 type: number
                                 exclusiveMinimum: 0
+                              sillHeightM:
+                                type: number
+                                minimum: 0
+                                maximum: 50
                               hostWallIndex:
                                 type:
                                   - integer
@@ -4516,10 +5892,15 @@ paths:
                                 minimum: 0
                               swingHand:
                                 type: string
-                                enum: *ref_0
+                                enum:
+                                  - left
+                                  - right
+                                  - none
                               placementSource:
                                 type: string
-                                enum: *ref_1
+                                enum:
+                                  - auto
+                                  - manual
                               duplicateOf:
                                 type: object
                                 properties:
@@ -4568,6 +5949,10 @@ paths:
                               height:
                                 type: number
                                 exclusiveMinimum: 0
+                              sillHeightM:
+                                type: number
+                                minimum: 0
+                                maximum: 50
                               hostWallIndex:
                                 type:
                                   - integer
@@ -4578,10 +5963,15 @@ paths:
                                 minimum: 0
                               swingHand:
                                 type: string
-                                enum: *ref_0
+                                enum:
+                                  - left
+                                  - right
+                                  - none
                               placementSource:
                                 type: string
-                                enum: *ref_1
+                                enum:
+                                  - auto
+                                  - manual
                             required:
                               - position
                               - width
@@ -4610,6 +6000,10 @@ paths:
                               height:
                                 type: number
                                 exclusiveMinimum: 0
+                              sillHeightM:
+                                type: number
+                                minimum: 0
+                                maximum: 50
                               hostWallIndex:
                                 type:
                                   - integer
@@ -4620,10 +6014,15 @@ paths:
                                 minimum: 0
                               swingHand:
                                 type: string
-                                enum: *ref_0
+                                enum:
+                                  - left
+                                  - right
+                                  - none
                               placementSource:
                                 type: string
-                                enum: *ref_1
+                                enum:
+                                  - auto
+                                  - manual
                             required:
                               - position
                               - width
@@ -4686,7 +6085,7 @@ paths:
       tags:
         - lidar
       parameters:
-        - *ref_3
+        - *ref_0
         - schema:
             type: integer
             exclusiveMinimum: 0
@@ -4767,6 +6166,10 @@ paths:
                                   height:
                                     type: number
                                     exclusiveMinimum: 0
+                                  sillHeightM:
+                                    type: number
+                                    minimum: 0
+                                    maximum: 50
                                   hostWallIndex:
                                     type:
                                       - integer
@@ -4777,10 +6180,15 @@ paths:
                                     minimum: 0
                                   swingHand:
                                     type: string
-                                    enum: *ref_0
+                                    enum:
+                                      - left
+                                      - right
+                                      - none
                                   placementSource:
                                     type: string
-                                    enum: *ref_1
+                                    enum:
+                                      - auto
+                                      - manual
                                   duplicateOf:
                                     type: object
                                     properties:
@@ -4830,6 +6238,10 @@ paths:
                                   height:
                                     type: number
                                     exclusiveMinimum: 0
+                                  sillHeightM:
+                                    type: number
+                                    minimum: 0
+                                    maximum: 50
                                   hostWallIndex:
                                     type:
                                       - integer
@@ -4840,10 +6252,15 @@ paths:
                                     minimum: 0
                                   swingHand:
                                     type: string
-                                    enum: *ref_0
+                                    enum:
+                                      - left
+                                      - right
+                                      - none
                                   placementSource:
                                     type: string
-                                    enum: *ref_1
+                                    enum:
+                                      - auto
+                                      - manual
                                 required:
                                   - position
                                   - width
@@ -4872,6 +6289,10 @@ paths:
                                   height:
                                     type: number
                                     exclusiveMinimum: 0
+                                  sillHeightM:
+                                    type: number
+                                    minimum: 0
+                                    maximum: 50
                                   hostWallIndex:
                                     type:
                                       - integer
@@ -4882,10 +6303,15 @@ paths:
                                     minimum: 0
                                   swingHand:
                                     type: string
-                                    enum: *ref_0
+                                    enum:
+                                      - left
+                                      - right
+                                      - none
                                   placementSource:
                                     type: string
-                                    enum: *ref_1
+                                    enum:
+                                      - auto
+                                      - manual
                                 required:
                                   - position
                                   - width
@@ -4941,7 +6367,7 @@ paths:
       tags:
         - chatty
       parameters:
-        - *ref_3
+        - *ref_0
       responses:
         '200':
           description: Bare array of tool definitions.
@@ -5043,7 +6469,7 @@ paths:
       tags:
         - chatty
       parameters:
-        - *ref_3
+        - *ref_0
       requestBody:
         content:
           application/json:
@@ -5118,7 +6544,7 @@ paths:
       tags:
         - chatty
       parameters:
-        - *ref_3
+        - *ref_0
       responses:
         '200':
           description: System instructions + knowledge-base / workflow-stage load flags.
@@ -5168,7 +6594,7 @@ paths:
       tags:
         - chatty
       parameters:
-        - *ref_3
+        - *ref_0
       requestBody:
         content:
           application/json:
@@ -5285,7 +6711,7 @@ paths:
       tags:
         - chatty
       parameters:
-        - *ref_3
+        - *ref_0
       responses:
         '200':
           description: Fresh CSRF token.
@@ -5321,7 +6747,7 @@ paths:
       tags:
         - chatty
       parameters:
-        - *ref_3
+        - *ref_0
         - name: X-CSRF-Token
           in: header
           required: true
@@ -5409,8 +6835,8 @@ paths:
       tags:
         - time-tracking
       parameters:
-        - *ref_3
-        - &ref_4
+        - *ref_0
+        - &ref_1
           name: X-Day-Clock
           in: header
           required: false
@@ -5457,8 +6883,8 @@ paths:
       tags:
         - time-tracking
       parameters:
-        - *ref_3
-        - *ref_4
+        - *ref_0
+        - *ref_1
       requestBody:
         content:
           application/json:
@@ -5486,7 +6912,11 @@ paths:
                   type:
                     - string
                     - 'null'
-                  enum: *ref_5
+                  enum:
+                    - ios
+                    - web
+                    - android
+                    - null
                 occurredAt:
                   type:
                     - string
@@ -5593,8 +7023,8 @@ paths:
       tags:
         - time-tracking
       parameters:
-        - *ref_3
-        - *ref_4
+        - *ref_0
+        - *ref_1
       description: >-
         A late Clock Out (T6): with tapElapsedMs proving its time, it keeps its real time however old. When the safety
         net already closed the day (the automatic close), a proven Clock Out earlier than that close replaces it
@@ -5627,7 +7057,11 @@ paths:
                   type:
                     - string
                     - 'null'
-                  enum: *ref_5
+                  enum:
+                    - ios
+                    - web
+                    - android
+                    - null
                 occurredAt:
                   type:
                     - string
@@ -5732,8 +7166,8 @@ paths:
       tags:
         - time-tracking
       parameters:
-        - *ref_3
-        - &ref_6
+        - *ref_0
+        - &ref_2
           name: X-Sites
           in: header
           required: false
@@ -5800,7 +7234,7 @@ paths:
       tags:
         - time-tracking
       parameters:
-        - *ref_3
+        - *ref_0
       responses:
         '200':
           description: Effective settings, clamped.
@@ -5838,7 +7272,7 @@ paths:
       tags:
         - time-tracking
       parameters:
-        - *ref_3
+        - *ref_0
         - name: scope
           in: query
           required: false
@@ -5903,8 +7337,8 @@ paths:
       tags:
         - time-tracking
       parameters:
-        - *ref_3
-        - *ref_6
+        - *ref_0
+        - *ref_2
         - name: scope
           in: query
           required: false
@@ -5953,8 +7387,8 @@ paths:
       tags:
         - time-tracking
       parameters:
-        - *ref_3
-        - *ref_6
+        - *ref_0
+        - *ref_2
         - name: userId
           in: query
           required: false
@@ -6031,9 +7465,9 @@ paths:
       tags:
         - time-tracking
       parameters:
-        - *ref_3
-        - *ref_6
-        - *ref_4
+        - *ref_0
+        - *ref_2
+        - *ref_1
       requestBody:
         content:
           application/json:
@@ -6047,7 +7481,9 @@ paths:
                   description: Omit or null together with siteType 'office'.
                 siteType:
                   type: string
-                  enum: *ref_2
+                  enum:
+                    - job
+                    - office
                 userId:
                   type: string
                   description: Clock someone else in. Requires time_tracking.edit_all.
@@ -6091,7 +7527,11 @@ paths:
                   type:
                     - string
                     - 'null'
-                  enum: *ref_5
+                  enum:
+                    - ios
+                    - web
+                    - android
+                    - null
                 canConfirmAway:
                   type: boolean
                   description: >-
@@ -6210,9 +7650,9 @@ paths:
       tags:
         - time-tracking
       parameters:
-        - *ref_3
-        - *ref_6
-        - *ref_4
+        - *ref_0
+        - *ref_2
+        - *ref_1
       requestBody:
         content:
           application/json:
@@ -6225,7 +7665,9 @@ paths:
                     - 'null'
                 siteType:
                   type: string
-                  enum: *ref_2
+                  enum:
+                    - job
+                    - office
                 userId:
                   type: string
                   description: Requires time_tracking.edit_all.
@@ -6256,7 +7698,11 @@ paths:
                   type:
                     - string
                     - 'null'
-                  enum: *ref_5
+                  enum:
+                    - ios
+                    - web
+                    - android
+                    - null
                 tapElapsedMs:
                   type:
                     - integer
@@ -6341,7 +7787,7 @@ paths:
       tags:
         - time-tracking
       parameters:
-        - *ref_3
+        - *ref_0
       requestBody:
         content:
           application/json:
@@ -6492,7 +7938,7 @@ paths:
       tags:
         - time-tracking
       parameters:
-        - *ref_3
+        - *ref_0
         - schema:
             type: integer
           required: true
@@ -6552,7 +7998,7 @@ paths:
       tags:
         - time-tracking
       parameters:
-        - *ref_3
+        - *ref_0
         - schema:
             type: integer
           required: true
@@ -6586,7 +8032,11 @@ paths:
                   type:
                     - string
                     - 'null'
-                  enum: *ref_5
+                  enum:
+                    - ios
+                    - web
+                    - android
+                    - null
               required:
                 - kind
                 - lat
@@ -6660,7 +8110,7 @@ paths:
       tags:
         - time-tracking
       parameters:
-        - *ref_3
+        - *ref_0
       requestBody:
         content:
           application/json:
@@ -6710,7 +8160,11 @@ paths:
                   type:
                     - string
                     - 'null'
-                  enum: *ref_5
+                  enum:
+                    - ios
+                    - web
+                    - android
+                    - null
               required:
                 - pings
       responses:
@@ -6756,7 +8210,7 @@ paths:
       tags:
         - time-tracking
       parameters:
-        - *ref_3
+        - *ref_0
         - name: since
           in: query
           required: false
@@ -6825,7 +8279,7 @@ paths:
       tags:
         - schedule
       parameters:
-        - *ref_3
+        - *ref_0
         - name: date
           in: query
           required: false
@@ -6861,7 +8315,7 @@ paths:
       tags:
         - schedule
       parameters:
-        - *ref_3
+        - *ref_0
       requestBody:
         content:
           application/json:
@@ -6870,7 +8324,10 @@ paths:
               properties:
                 kind:
                   type: string
-                  enum: *ref_7
+                  enum:
+                    - pto
+                    - sick
+                    - 'off'
                 startDate:
                   type: string
                   format: date
@@ -6936,7 +8393,7 @@ paths:
       tags:
         - account
       parameters:
-        - *ref_3
+        - *ref_0
       requestBody:
         content:
           application/json:
@@ -6997,7 +8454,7 @@ paths:
       tags:
         - account
       parameters:
-        - *ref_3
+        - *ref_0
       responses:
         '200':
           description: The newest request, whatever its status.
@@ -7035,4 +8492,212 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/UpgradeRequiredEnvelope'
+  /api/sketches/{sketchId}/doorway-edits:
+    post:
+      tags:
+        - lidar
+      summary: Save a confirmed shared-doorway edit atomically, or undo it.
+      description: >-
+        Requires authenticated organization and job access. Delete removes both linked openings and only their doorway
+        connection. Undo receipts are user/scope-bound, expire after eight hours, and reject intervening geometry or
+        connection changes. Connect is supported for sketches only. Room reads provide openingId and openingRevision;
+        existing records are not backfilled.
+      parameters:
+        - name: sketchId
+          in: path
+          required: true
+          schema:
+            type: integer
+            minimum: 1
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DoorwayEditCommand'
+      responses:
+        '200':
+          description: Committed both rooms and their connection changes; token reverses this action.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DoorwayEditResult'
+        '400':
+          description: Invalid command or missing explicit confirmation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '401':
+          description: Authentication required.
+        '403':
+          description: Job access denied.
+        '404':
+          description: Scope not found in the organization.
+        '409':
+          description: Stale or ambiguous opening identity, or undo would overwrite newer work.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+  /api/floors/{floorId}/doorway-edits:
+    post:
+      tags:
+        - lidar
+      summary: Save a confirmed shared-doorway edit atomically, or undo it.
+      description: >-
+        Requires authenticated organization and job access. Delete removes both linked openings and only their doorway
+        connection. Undo receipts are user/scope-bound, expire after eight hours, and reject intervening geometry or
+        connection changes. Connect is supported for sketches only. Room reads provide openingId and openingRevision;
+        existing records are not backfilled.
+      parameters:
+        - name: floorId
+          in: path
+          required: true
+          schema:
+            type: integer
+            minimum: 1
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DoorwayEditCommand'
+      responses:
+        '200':
+          description: Committed both rooms and their connection changes; token reverses this action.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DoorwayEditResult'
+        '400':
+          description: Invalid command or missing explicit confirmation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '401':
+          description: Authentication required.
+        '403':
+          description: Job access denied.
+        '404':
+          description: Scope not found in the organization.
+        '409':
+          description: Stale or ambiguous opening identity, or undo would overwrite newer work.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+  /api/projects/{projectId}/documents/draft-from-walkthrough:
+    post:
+      tags:
+        - checklists
+      summary: Turn a voice walk-through (timed transcript + photos) into a checklist draft.
+      description: >-
+        Returns a DRAFT only; nothing is saved to the job. The phone's review screen creates the checklist with POST
+        /api/projects/{projectId}/documents (custom `items`, carrying `referenceMedia`). Sections come from, in order:
+        the camera pose of a scan, the room the tech named (the item's words, the photo's room chip, a section opened),
+        the AI Image Sort's room for the item's photo (add-on), then the last room mentioned; items with no signal go to
+        Not sure. GPS is never used. Item types come from spoken hints only (checkbox unless "photo required", "yes or
+        no" or a reading; "required" sets the flag). Reference photos are the shots taken from 10 s before a sentence to
+        20 s after it. 200 when the draft is ready at once; 202 with `runId` while the photos go through an AI vision
+        sort (poll the runs route). Requires the job (404 otherwise) and the Create Checklists permission (403). Photos
+        that are not the organization's assets are left out.
+      parameters:
+        - &ref_3
+          name: projectId
+          in: path
+          required: true
+          schema:
+            type: integer
+            minimum: 1
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WalkthroughDraftRequest'
+      responses:
+        '200':
+          description: The draft (status completed).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WalkthroughDraftResponse'
+        '202':
+          description: A vision sort runs first (status running); poll GET …/draft-from-walkthrough/runs/{runId}.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WalkthroughDraftResponse'
+        '400':
+          description: No transcript, or a wrong shape.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '401':
+          description: Authentication required.
+        '403':
+          description: The role cannot create checklists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '404':
+          description: Job not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '502':
+          description: The AI's answer could not be used.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '503':
+          description: AI is not configured.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+  /api/projects/{projectId}/documents/draft-from-walkthrough/runs/{runId}:
+    get:
+      tags:
+        - checklists
+      summary: Poll a walk-through draft that waits for an AI vision sort.
+      description: >-
+        Status `running` (with the sort's progress in `sortRun`) until the draft is ready, then `completed` with
+        `draft`, or `failed` with `message`. A run that stops making progress is marked failed on the next poll and
+        never re-run.
+      parameters:
+        - *ref_3
+        - name: runId
+          in: path
+          required: true
+          schema:
+            type: integer
+            minimum: 1
+      responses:
+        '200':
+          description: The run's envelope.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WalkthroughDraftResponse'
+        '401':
+          description: Authentication required.
+        '403':
+          description: The role cannot create checklists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '404':
+          description: Job or run not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
 webhooks: {}