@serviceai/api-spec 1.2.434 → 1.6.1

package/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: ServiceAi API
-  version: 1.2.434
+  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.434
+          example: 1.6.1
         minClientVersion:
           type: string
           example: 1.0.0
@@ -1842,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:
@@ -3519,20 +3556,964 @@ components:
     DoorwayEditResult:
       type: object
       properties:
-        ok:
+        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
-          enum:
-            - true
-        token:
+      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
-        roomIds:
+        items:
           type: array
           items:
-            type: integer
+            type: object
+            properties:
+              itemText:
+                type: string
+              photos:
+                type: integer
+            required:
+              - itemText
+              - photos
+        unsortedPhotos:
+          type: integer
+        created:
+          type: boolean
       required:
-        - ok
-        - token
-        - roomIds
+        - name
+        - items
+        - unsortedPhotos
+        - created
+      description: '`data` of a successful `draft_checklist_from_job_photos` call (`success: true`).'
   parameters: {}
 paths:
   /api/version:
@@ -3602,6 +4583,181 @@ paths:
             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:
+                $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:
+      tags:
+        - auth
+      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:
+        - schema:
+            type: string
+            minLength: 1
+            maxLength: 8192
+          required: false
+          name: ticket
+          in: query
+      responses:
+        '200':
+          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/StreamAuthenticationError'
+        '403':
+          description: Legacy temporary context is unavailable.
+          content:
+            application/json:
+              schema:
+                $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.
@@ -7432,4 +8588,116 @@ paths:
             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: {}