openapi: 3.0.3 info: title: Duvo Public Agent Folders ClarityV2 API description: Public API for programmatic access to Duvo. Authenticate with API keys created in the Duvo dashboard. version: 1.0.0 servers: - url: https://api.duvo.ai description: Production server tags: - name: ClarityV2 description: Manage Clarity v2 process snapshots, transformation proposals, and the extra-capture-request follow-up loop paths: /v2/clarity-v2/processes/{process_id}: get: operationId: getClarityProcess tags: - ClarityV2 description: 'Get the v2 read model for a clarity process: the process row (with operational fields like generation_error, generation_progress, custom_prompt), its captures, and the lightweight version arrays for both snapshot tabs. The full payload of any specific snapshot is fetched lazily via the unified per-snapshot detail endpoint (`GET .../snapshots/:kind/:id`); this read model deliberately doesn''t carry it so the response stays small.' parameters: - schema: default: full type: string enum: - full - lite in: query name: captures required: false description: Capture payload mode. `full` (default) embeds each capture's transcript content. `lite` omits `transcript`/`videoTranscript` (returned as null) and relies on the `hasTranscript`/`hasVideoTranscript` flags; fetch content on demand via `GET .../captures/:capture_id`. - schema: type: string format: uuid in: path name: process_id required: true description: The clarity process id security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: process: type: object properties: id: type: string format: uuid description: Clarity process id team_id: type: string format: uuid description: Owning team id user_id: type: string format: uuid description: Creator user id name: type: string description: Process name status: type: string enum: - draft - collecting - generating - generating-current-process - generating-transformation-proposal - review - complete - generation_failed description: Lifecycle status visibility: type: string enum: - team - restricted description: Process visibility. 'team' is workspace-visible to full members; 'restricted' is visible to the creator, org admins, workspace managers/admins, and accepted grant holders. version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Schema version (always 2 here) generation_error: nullable: true description: Error message from the most recent failed generation, if any type: string generation_progress: nullable: true description: Live progress checklist while a generation is in flight; null otherwise. Field names inside the payload are camelCase, matching the legacy v1 generation-progress shape. type: object properties: steps: type: array items: type: object properties: key: type: string label: type: string status: type: string enum: - pending - in_progress - complete order: type: number count: type: number required: - key - label - status - order additionalProperties: false required: - steps additionalProperties: false custom_prompt: nullable: true description: User-supplied custom prompt that steers generation type: string created_at: type: string description: ISO 8601 creation timestamp updated_at: type: string description: ISO 8601 last-update timestamp required: - id - team_id - user_id - name - status - visibility - version - generation_error - generation_progress - custom_prompt - created_at - updated_at additionalProperties: false current_process_versions: type: array items: type: object properties: id: type: string format: uuid description: Snapshot id process_id: type: string format: uuid description: Parent clarity_process id parent_current_process_id: nullable: true description: Parent current-process snapshot this draft forked from type: string format: uuid created_at: type: string description: ISO 8601 creation timestamp status: type: string enum: - live - historic - draft - generating description: Versioning state. Only one 'live' row per process at a time; drafts may be edited or generating before promotion. creator_type: type: string enum: - human - ai description: Whether this row was created by a user edit ('human') or an AI pipeline run ('ai'). user_id: nullable: true description: Creator user id (the human who edited or triggered the run). type: string format: uuid sandbox_id: nullable: true description: E2B sandbox id that produced AI rows; null for user edits. type: string last_session_id: nullable: true description: Claude SDK session id for artifact-chat follow-up reuse. type: string required: - id - process_id - parent_current_process_id - created_at - status - creator_type - user_id - sandbox_id - last_session_id additionalProperties: false description: All non-deleted current-process snapshots, newest first. Lightweight rows (no `data`) for the version-picker UI. Clients lazy-fetch the live (or selected) snapshot via the per-snapshot detail endpoint. transformation_proposal_versions: type: array items: type: object properties: id: type: string format: uuid description: Proposal id process_id: type: string format: uuid description: Parent clarity_process id clarity_current_process_id: type: string format: uuid description: The current-process snapshot this proposal was generated against (provenance only; the live proposal can target any current-process snapshot). parent_transformation_proposal_id: nullable: true description: Parent transformation-proposal snapshot this draft forked from type: string format: uuid created_at: type: string description: ISO 8601 creation timestamp status: type: string enum: - live - historic - draft - generating description: Versioning state. Only one 'live' row per process at a time; drafts may be edited or generating before promotion. creator_type: type: string enum: - human - ai description: Whether this row was created by a user edit ('human') or an AI pipeline run ('ai'). user_id: nullable: true description: Creator user id (the human who edited or triggered the run). type: string format: uuid sandbox_id: nullable: true description: E2B sandbox id that produced AI rows; null for user edits. type: string last_session_id: nullable: true description: Claude SDK session id for artifact-chat follow-up reuse. type: string extra_capture_requests: description: Active extra-capture requests for this proposal. Populated only on the live proposal version row in the read-model endpoint so the FE can render assignment UI without a second round-trip; historic versions return an empty array. Other endpoints (e.g. admin snapshot views) may omit it entirely, in which case it is `undefined`. The standalone list endpoint stays the source of truth for paginated/admin views. type: array items: type: object properties: id: type: string format: uuid description: Extra-capture-request id proposal_id: type: string format: uuid description: The transformation proposal this request belongs to step_id: type: string description: Step id within the proposal's BPMN graph capture_id: nullable: true description: Capture that fulfilled this request, once one is created type: string format: uuid requested_user_id: nullable: true description: Assigned team member, if any type: string format: uuid status: type: string enum: - requested - captured - resolved description: Lifecycle status of the request gap: type: string description: Plain-language gap blocking automation suggested_prompt: nullable: true description: LLM-produced suggested capture prompt type: string priority: type: string enum: - low - medium - high description: Priority of fulfilling this request created_at: type: string description: ISO 8601 creation timestamp updated_at: type: string description: ISO 8601 last-update timestamp required: - id - proposal_id - step_id - capture_id - requested_user_id - status - gap - suggested_prompt - priority - created_at - updated_at additionalProperties: false required: - id - process_id - clarity_current_process_id - parent_transformation_proposal_id - created_at - status - creator_type - user_id - sandbox_id - last_session_id additionalProperties: false description: All non-deleted transformation-proposal snapshots, newest first. Lightweight rows (no `data`) for the version-picker UI. captures: type: array items: type: object properties: id: type: string format: uuid processId: type: string format: uuid userId: type: string format: uuid userName: type: string type: type: string x-extensible-enum: - video - interview - document - screenshare - meeting videoUrl: nullable: true type: string videoTranscript: nullable: true type: string documentFileName: nullable: true type: string documentTextMetadata: nullable: true type: object properties: pages: type: array items: type: object properties: pageNumber: type: integer exclusiveMinimum: true maximum: 9007199254740991 startOffset: type: integer minimum: 0 maximum: 9007199254740991 endOffset: type: integer minimum: 0 maximum: 9007199254740991 lines: type: array items: type: object properties: pageNumber: type: integer exclusiveMinimum: true maximum: 9007199254740991 lineNumber: type: integer exclusiveMinimum: true maximum: 9007199254740991 startOffset: type: integer minimum: 0 maximum: 9007199254740991 endOffset: type: integer minimum: 0 maximum: 9007199254740991 required: - pageNumber - lineNumber - startOffset - endOffset additionalProperties: false required: - pageNumber - startOffset - endOffset - lines additionalProperties: false required: - pages additionalProperties: false transcript: nullable: true type: array items: type: object properties: source: type: string enum: - ai - user - interviewer speakerName: type: string message: type: string minLength: 1 timestamp: type: number required: - source - message additionalProperties: false hasTranscript: type: boolean hasVideoTranscript: type: boolean transcriptQuestionCount: type: integer minimum: 0 maximum: 9007199254740991 status: type: string enum: - pending - recording - processing - complete - failed createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - processId - userId - type - videoUrl - videoTranscript - transcript - status - createdAt - updatedAt additionalProperties: false description: All captures (videos, interviews, documents) attached to this process. Field names follow the legacy v1 capture wire format (camelCase) so existing capture consumers keep working unchanged. required: - process - current_process_versions - transformation_proposal_versions - captures additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: Get Clarity Process /v2/clarity-v2/processes/{process_id}/postprocess: post: operationId: postprocessClaritySnapshot tags: - ClarityV2 description: Re-run postprocessing agents on an existing v2 clarity snapshot. Targets either the current-process snapshot or the transformation-proposal snapshot, identified by id in the body. Flips the process status to `generating` and returns 202 immediately; agents run asynchronously and flip the status back to `review` once they settle. requestBody: required: true content: application/json: schema: oneOf: - type: object properties: type: type: string enum: - current_process current_process_id: type: string format: uuid description: ID of the `clarity_current_process` snapshot to re-postprocess. required: - type - current_process_id - type: object properties: type: type: string enum: - transformation_proposal transformation_proposal_id: type: string format: uuid description: ID of the `clarity_transformation_proposal` snapshot to re-postprocess. required: - type - transformation_proposal_id parameters: - schema: type: string format: uuid in: path name: process_id required: true description: The clarity process id security: - bearerAuth: [] responses: '202': description: Default Response content: application/json: schema: type: object properties: success: type: boolean required: - success additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: Postprocess Clarity Snapshot /v2/clarity-v2/processes/{process_id}/automation: post: operationId: buildClarityAutomation tags: - ClarityV2 description: Hand the latest transformation proposal for a v2 clarity process off to the workflow-builder pipeline. Returns 202 with the new run id; the LLM run completes asynchronously. parameters: - schema: type: string format: uuid in: path name: process_id required: true description: The clarity process id security: - bearerAuth: [] responses: '202': description: Default Response content: application/json: schema: type: object properties: automation_run: type: object properties: id: type: string format: uuid description: Workflow-builder run id status: type: string enum: - generating description: Always `generating` immediately after kickoff required: - id - status additionalProperties: false required: - automation_run additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: Build Clarity Automation /v2/clarity-v2/processes/{process_id}/transformation-proposals/{transformation_proposal_id}/extra-capture-requests: get: operationId: listClarityExtraCaptureRequests tags: - ClarityV2 description: List active extra-capture requests for a given transformation proposal of a Clarity v2 process. The caller is expected to know the proposal id from the V2 read model and skip the call when no proposal exists yet. parameters: - schema: default: 20 type: integer minimum: 1 maximum: 100 in: query name: limit required: false description: Number of results per page (1-100, default 20) - schema: type: integer minimum: 0 maximum: 9007199254740991 in: query name: offset required: false description: Number of results to skip (default 0) - schema: type: string format: uuid in: path name: process_id required: true description: The clarity process id - schema: type: string format: uuid in: path name: transformation_proposal_id required: true description: The transformation proposal id security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: requests: type: array items: type: object properties: id: type: string format: uuid description: Extra-capture-request id proposal_id: type: string format: uuid description: The transformation proposal this request belongs to step_id: type: string description: Step id within the proposal's BPMN graph capture_id: nullable: true description: Capture that fulfilled this request, once one is created type: string format: uuid requested_user_id: nullable: true description: Assigned team member, if any type: string format: uuid status: type: string enum: - requested - captured - resolved description: Lifecycle status of the request gap: type: string description: Plain-language gap blocking automation suggested_prompt: nullable: true description: LLM-produced suggested capture prompt type: string priority: type: string enum: - low - medium - high description: Priority of fulfilling this request created_at: type: string description: ISO 8601 creation timestamp updated_at: type: string description: ISO 8601 last-update timestamp required: - id - proposal_id - step_id - capture_id - requested_user_id - status - gap - suggested_prompt - priority - created_at - updated_at additionalProperties: false total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Total matching rows across all pages limit: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Page size that was applied offset: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Offset that was applied required: - requests - total - limit - offset additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: List Clarity Extra Capture Requests ? /v2/clarity-v2/processes/{process_id}/transformation-proposals/{transformation_proposal_id}/extra-capture-requests/{request_id}/assign : patch: operationId: assignClarityExtraCaptureRequest tags: - ClarityV2 description: 'Assign (or unassign, with `user_id: null`) a team member to fulfil an extra-capture request. Restricted to admins and managers.' requestBody: required: true content: application/json: schema: type: object properties: user_id: nullable: true description: Team member to assign, or null to unassign type: string format: uuid required: - user_id parameters: - schema: type: string format: uuid in: path name: process_id required: true description: The clarity process id - schema: type: string format: uuid in: path name: transformation_proposal_id required: true description: The transformation proposal id - schema: type: string format: uuid in: path name: request_id required: true description: The extra-capture-request id security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: request: type: object properties: id: type: string format: uuid description: Extra-capture-request id proposal_id: type: string format: uuid description: The transformation proposal this request belongs to step_id: type: string description: Step id within the proposal's BPMN graph capture_id: nullable: true description: Capture that fulfilled this request, once one is created type: string format: uuid requested_user_id: nullable: true description: Assigned team member, if any type: string format: uuid status: type: string enum: - requested - captured - resolved description: Lifecycle status of the request gap: type: string description: Plain-language gap blocking automation suggested_prompt: nullable: true description: LLM-produced suggested capture prompt type: string priority: type: string enum: - low - medium - high description: Priority of fulfilling this request created_at: type: string description: ISO 8601 creation timestamp updated_at: type: string description: ISO 8601 last-update timestamp required: - id - proposal_id - step_id - capture_id - requested_user_id - status - gap - suggested_prompt - priority - created_at - updated_at additionalProperties: false description: The updated extra-capture request, including the new assignee required: - request additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: Assign Clarity Extra Capture Request /v2/clarity-v2/processes/{process_id}/invite-link: post: operationId: createClarityInviteLink tags: - ClarityV2 description: Create or regenerate a process-scoped Clarity interview invite link. Only the process creator or team managers can create invite links; creating a new link invalidates any prior active link for the process. parameters: - schema: type: string format: uuid in: path name: process_id required: true description: The clarity process id security: - bearerAuth: [] responses: '201': description: Default Response content: application/json: schema: type: object properties: invite_link: type: object properties: id: type: string format: uuid description: Invite-link id url: type: string format: uri description: Process-scoped invite URL created_at: type: string format: date-time description: ISO 8601 creation timestamp created_by: type: object properties: id: type: string format: uuid description: User id that created the invite link email: nullable: true description: Creator email, when available type: string format: email required: - id - email additionalProperties: false required: - id - url - created_at - created_by additionalProperties: false required: - invite_link additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: Create Clarity Invite Link /v2/clarity-v2/processes/{process_id}/artifact-imports/create-upload-url: post: operationId: createClarityArtifactImportUploadUrl tags: - ClarityV2 description: Create a signed upload URL for importing a Miro export into a Clarity v2 process. Supports SVG, XML, PNG, and JPEG exports. The caller must upload the file to the returned URL, then complete the import. requestBody: required: true content: application/json: schema: type: object properties: file_name: type: string minLength: 1 pattern: ^.*\.(?:[sS][vV][gG]|[xX][mM][lL]|[pP][nN][gG]|[jJ][pP][eE]?[gG])$ description: 'Name of the Miro export file. Supported extensions: .svg, .xml, .png, .jpg, .jpeg' content_type: type: string enum: - image/svg+xml - application/xml - text/xml - image/png - image/jpeg description: MIME type of the Miro export file extra_capture_request_id: description: Optional extra-capture-request id to bind this import to type: string format: uuid required: - file_name - content_type parameters: - schema: type: string format: uuid in: path name: process_id required: true description: The clarity process id security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: signed_url: type: string format: uri description: Signed URL for uploading the artifact capture_id: type: string format: uuid description: Pending capture id to pass to completion expires_at: type: string format: date-time description: ISO 8601 upload URL expiration timestamp required: - signed_url - capture_id - expires_at additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: Create Clarity Artifact Import Upload URL /v2/clarity-v2/processes/{process_id}/artifact-imports/{capture_id}/complete: post: operationId: completeClarityArtifactImport tags: - ClarityV2 description: Complete a Miro artifact import after uploading to the signed URL. The uploaded bytes are validated before the import becomes a usable Clarity capture. requestBody: required: true content: application/json: schema: type: object properties: file_name: type: string minLength: 1 pattern: ^.*\.(?:[sS][vV][gG]|[xX][mM][lL]|[pP][nN][gG]|[jJ][pP][eE]?[gG])$ description: 'Name of the Miro export file. Supported extensions: .svg, .xml, .png, .jpg, .jpeg' content_type: type: string enum: - image/svg+xml - application/xml - text/xml - image/png - image/jpeg description: MIME type of the uploaded Miro export file required: - file_name - content_type parameters: - schema: type: string format: uuid in: path name: process_id required: true description: The clarity process id - schema: type: string format: uuid in: path name: capture_id required: true description: The pending capture id returned by the upload-url endpoint security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: capture: type: object properties: id: type: string format: uuid processId: type: string format: uuid userId: type: string format: uuid userName: type: string type: type: string x-extensible-enum: - video - interview - document - screenshare - meeting videoUrl: nullable: true type: string videoTranscript: nullable: true type: string documentFileName: nullable: true type: string documentTextMetadata: nullable: true type: object properties: pages: type: array items: type: object properties: pageNumber: type: integer exclusiveMinimum: true maximum: 9007199254740991 startOffset: type: integer minimum: 0 maximum: 9007199254740991 endOffset: type: integer minimum: 0 maximum: 9007199254740991 lines: type: array items: type: object properties: pageNumber: type: integer exclusiveMinimum: true maximum: 9007199254740991 lineNumber: type: integer exclusiveMinimum: true maximum: 9007199254740991 startOffset: type: integer minimum: 0 maximum: 9007199254740991 endOffset: type: integer minimum: 0 maximum: 9007199254740991 required: - pageNumber - lineNumber - startOffset - endOffset additionalProperties: false required: - pageNumber - startOffset - endOffset - lines additionalProperties: false required: - pages additionalProperties: false transcript: nullable: true type: array items: type: object properties: source: type: string enum: - ai - user - interviewer speakerName: type: string message: type: string minLength: 1 timestamp: type: number required: - source - message additionalProperties: false hasTranscript: type: boolean hasVideoTranscript: type: boolean transcriptQuestionCount: type: integer minimum: 0 maximum: 9007199254740991 status: type: string enum: - pending - recording - processing - complete - failed createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - processId - userId - type - videoUrl - videoTranscript - transcript - status - createdAt - updatedAt additionalProperties: false required: - capture additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '413': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: Complete Clarity Artifact Import /v2/clarity-v2/processes/{process_id}/artifact-chat/conversations: get: operationId: listClarityArtifactChatConversations tags: - ClarityV2 description: List the current user's recent non-deleted artifact-chat conversations for a Clarity v2 process and snapshot kind. parameters: - schema: type: string enum: - current_process - transformation_proposal in: query name: snapshot_kind required: true description: Artifact kind to list conversations for - schema: type: string format: uuid in: path name: process_id required: true description: The Clarity process id security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: conversations: type: array items: type: object properties: id: type: string format: uuid user_id: type: string format: uuid process_id: type: string format: uuid snapshot_kind: type: string enum: - current_process - transformation_proposal title: nullable: true type: string sandbox_id: nullable: true type: string session_id: nullable: true type: string status: type: string enum: - open - running - waiting_for_patch - waiting_for_hitl created_at: type: string updated_at: type: string deleted_at: nullable: true type: string required: - id - user_id - process_id - snapshot_kind - title - sandbox_id - session_id - status - created_at - updated_at - deleted_at additionalProperties: false required: - conversations additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: List Clarity Artifact Chat Conversations /v2/clarity-v2/processes/{process_id}/artifact-chat/conversations/{conversation_id}/messages: get: operationId: getClarityArtifactChatMessages tags: - ClarityV2 description: Load the latest artifact-chat messages for one active conversation, returned oldest-first. parameters: - schema: type: string format: uuid in: path name: process_id required: true description: The Clarity process id - schema: type: string format: uuid in: path name: conversation_id required: true description: The artifact-chat conversation id security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: conversation: type: object properties: id: type: string format: uuid user_id: type: string format: uuid process_id: type: string format: uuid snapshot_kind: type: string enum: - current_process - transformation_proposal title: nullable: true type: string sandbox_id: nullable: true type: string session_id: nullable: true type: string status: type: string enum: - open - running - waiting_for_patch - waiting_for_hitl created_at: type: string updated_at: type: string deleted_at: nullable: true type: string required: - id - user_id - process_id - snapshot_kind - title - sandbox_id - session_id - status - created_at - updated_at - deleted_at additionalProperties: false messages: type: array items: type: object properties: id: type: string format: uuid conversation_id: type: string format: uuid role: type: string enum: - user - assistant - system kind: type: string enum: - text - patch - hitl_question - hitl_answer - error - info body: oneOf: - type: object properties: kind: type: string enum: - text text: type: string required: - kind - text additionalProperties: false - type: object properties: kind: type: string enum: - patch status: type: string enum: - pending - accepted - declined - failed summary: type: string patch: readOnly: true type: array items: anyOf: - type: object properties: op: type: string enum: - add - replace - test path: type: string value: $ref: '#/components/schemas/ArtifactChatJsonValue' required: - op - path - value additionalProperties: false - type: object properties: op: type: string enum: - remove path: type: string required: - op - path additionalProperties: false - type: object properties: op: type: string enum: - move - copy from: type: string path: type: string required: - op - from - path additionalProperties: false draft_snapshot_id: nullable: true type: string format: uuid snapshot_id: nullable: true type: string format: uuid required: - kind - status - summary - patch - snapshot_id additionalProperties: false - type: object properties: kind: type: string enum: - hitl_question questions: readOnly: true minItems: 1 type: array items: type: object properties: question: type: string header: default: '' type: string options: default: [] type: array items: type: object properties: label: type: string description: default: '' type: string required: - label - description additionalProperties: false multiSelect: default: false type: boolean required: - question - header - options - multiSelect additionalProperties: false required: - kind - questions additionalProperties: false - type: object properties: kind: type: string enum: - hitl_answer answers: readOnly: true type: object additionalProperties: type: string required: - kind - answers additionalProperties: false - type: object properties: kind: type: string enum: - error text: type: string required: - kind - text additionalProperties: false - type: object properties: kind: type: string enum: - info text: type: string required: - kind - text additionalProperties: false baseline_snapshot_id: type: string format: uuid created_at: type: string updated_at: type: string required: - id - conversation_id - role - kind - body - baseline_snapshot_id - created_at - updated_at additionalProperties: false required: - conversation - messages additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: Get Clarity Artifact Chat Messages /v2/clarity-v2/processes/{process_id}/artifact-chat/messages: post: tags: - ClarityV2 description: Submit a persisted artifact-chat user message and start a text turn. requestBody: required: true content: application/json: schema: type: object properties: conversation_id: nullable: true type: string format: uuid snapshot_kind: type: string enum: - current_process - transformation_proposal baseline_snapshot_id: type: string format: uuid content: type: string answers: type: object additionalProperties: type: string required: - conversation_id - snapshot_kind - baseline_snapshot_id parameters: - schema: type: string format: uuid in: path name: process_id required: true responses: '200': description: Default Response content: application/json: schema: type: object properties: conversation: type: object properties: id: type: string format: uuid user_id: type: string format: uuid process_id: type: string format: uuid snapshot_kind: type: string enum: - current_process - transformation_proposal title: nullable: true type: string sandbox_id: nullable: true type: string session_id: nullable: true type: string status: type: string enum: - open - running - waiting_for_patch - waiting_for_hitl created_at: type: string updated_at: type: string deleted_at: nullable: true type: string required: - id - user_id - process_id - snapshot_kind - title - sandbox_id - session_id - status - created_at - updated_at - deleted_at additionalProperties: false message: type: object properties: id: type: string format: uuid conversation_id: type: string format: uuid role: type: string enum: - user - assistant - system kind: type: string enum: - text - patch - hitl_question - hitl_answer - error - info body: oneOf: - type: object properties: kind: type: string enum: - text text: type: string required: - kind - text additionalProperties: false - type: object properties: kind: type: string enum: - patch status: type: string enum: - pending - accepted - declined - failed summary: type: string patch: readOnly: true type: array items: anyOf: - type: object properties: op: type: string enum: - add - replace - test path: type: string value: $ref: '#/components/schemas/ArtifactChatJsonValue' required: - op - path - value additionalProperties: false - type: object properties: op: type: string enum: - remove path: type: string required: - op - path additionalProperties: false - type: object properties: op: type: string enum: - move - copy from: type: string path: type: string required: - op - from - path additionalProperties: false draft_snapshot_id: nullable: true type: string format: uuid snapshot_id: nullable: true type: string format: uuid required: - kind - status - summary - patch - snapshot_id additionalProperties: false - type: object properties: kind: type: string enum: - hitl_question questions: readOnly: true minItems: 1 type: array items: type: object properties: question: type: string header: default: '' type: string options: default: [] type: array items: type: object properties: label: type: string description: default: '' type: string required: - label - description additionalProperties: false multiSelect: default: false type: boolean required: - question - header - options - multiSelect additionalProperties: false required: - kind - questions additionalProperties: false - type: object properties: kind: type: string enum: - hitl_answer answers: readOnly: true type: object additionalProperties: type: string required: - kind - answers additionalProperties: false - type: object properties: kind: type: string enum: - error text: type: string required: - kind - text additionalProperties: false - type: object properties: kind: type: string enum: - info text: type: string required: - kind - text additionalProperties: false baseline_snapshot_id: type: string format: uuid created_at: type: string updated_at: type: string required: - id - conversation_id - role - kind - body - baseline_snapshot_id - created_at - updated_at additionalProperties: false required: - conversation - message additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '409': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false /v2/clarity-v2/processes/{process_id}/artifact-chat/messages/{message_id}: put: tags: - ClarityV2 description: Accept or decline a persisted artifact-chat patch proposal. requestBody: required: true content: application/json: schema: type: object properties: decision: type: string enum: - accept - decline required: - decision parameters: - schema: type: string format: uuid in: path name: process_id required: true - schema: type: string format: uuid in: path name: message_id required: true responses: '200': description: Default Response content: application/json: schema: type: object properties: conversation: type: object properties: id: type: string format: uuid user_id: type: string format: uuid process_id: type: string format: uuid snapshot_kind: type: string enum: - current_process - transformation_proposal title: nullable: true type: string sandbox_id: nullable: true type: string session_id: nullable: true type: string status: type: string enum: - open - running - waiting_for_patch - waiting_for_hitl created_at: type: string updated_at: type: string deleted_at: nullable: true type: string required: - id - user_id - process_id - snapshot_kind - title - sandbox_id - session_id - status - created_at - updated_at - deleted_at additionalProperties: false message: type: object properties: id: type: string format: uuid conversation_id: type: string format: uuid role: type: string enum: - user - assistant - system kind: type: string enum: - text - patch - hitl_question - hitl_answer - error - info body: oneOf: - type: object properties: kind: type: string enum: - text text: type: string required: - kind - text additionalProperties: false - type: object properties: kind: type: string enum: - patch status: type: string enum: - pending - accepted - declined - failed summary: type: string patch: readOnly: true type: array items: anyOf: - type: object properties: op: type: string enum: - add - replace - test path: type: string value: $ref: '#/components/schemas/ArtifactChatJsonValue' required: - op - path - value additionalProperties: false - type: object properties: op: type: string enum: - remove path: type: string required: - op - path additionalProperties: false - type: object properties: op: type: string enum: - move - copy from: type: string path: type: string required: - op - from - path additionalProperties: false draft_snapshot_id: nullable: true type: string format: uuid snapshot_id: nullable: true type: string format: uuid required: - kind - status - summary - patch - snapshot_id additionalProperties: false - type: object properties: kind: type: string enum: - hitl_question questions: readOnly: true minItems: 1 type: array items: type: object properties: question: type: string header: default: '' type: string options: default: [] type: array items: type: object properties: label: type: string description: default: '' type: string required: - label - description additionalProperties: false multiSelect: default: false type: boolean required: - question - header - options - multiSelect additionalProperties: false required: - kind - questions additionalProperties: false - type: object properties: kind: type: string enum: - hitl_answer answers: readOnly: true type: object additionalProperties: type: string required: - kind - answers additionalProperties: false - type: object properties: kind: type: string enum: - error text: type: string required: - kind - text additionalProperties: false - type: object properties: kind: type: string enum: - info text: type: string required: - kind - text additionalProperties: false baseline_snapshot_id: type: string format: uuid created_at: type: string updated_at: type: string required: - id - conversation_id - role - kind - body - baseline_snapshot_id - created_at - updated_at additionalProperties: false required: - conversation - message additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '409': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false /v2/clarity-v2/processes/{process_id}/snapshots/{kind}: get: operationId: listClarityProcessSnapshots tags: - ClarityV2 description: List lightweight Clarity v2 process snapshots for one kind. parameters: - schema: default: 50 type: integer minimum: 1 maximum: 100 in: query name: limit required: false - schema: default: 0 type: integer minimum: 0 maximum: 9007199254740991 in: query name: offset required: false - schema: type: string format: uuid in: path name: process_id required: true description: The clarity process id - schema: type: string enum: - current_process - transformation_proposal in: path name: kind required: true description: Snapshot kind to list security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: snapshots: type: array items: oneOf: - type: object properties: id: type: string format: uuid description: Snapshot id process_id: type: string format: uuid description: Parent clarity_process id source_snapshot_id: type: string nullable: true enum: - null parent_id: nullable: true description: Parent snapshot this row forked from, if any type: string format: uuid created_at: type: string description: ISO 8601 creation timestamp status: type: string enum: - live - historic - draft - generating description: Versioning state. Only one 'live' row per process at a time; drafts may be edited or generating before promotion. creator_type: type: string enum: - human - ai description: Whether this row was created by a user edit ('human') or an AI pipeline run ('ai'). user_id: nullable: true description: Creator user id (the human who edited or triggered the run). type: string format: uuid sandbox_id: nullable: true description: E2B sandbox id that produced AI rows; null for user edits. type: string last_session_id: nullable: true description: Claude SDK session id for artifact-chat follow-up reuse. type: string kind: type: string enum: - current_process required: - id - process_id - source_snapshot_id - parent_id - created_at - status - creator_type - user_id - sandbox_id - last_session_id - kind additionalProperties: false - type: object properties: id: type: string format: uuid description: Snapshot id process_id: type: string format: uuid description: Parent clarity_process id source_snapshot_id: type: string format: uuid parent_id: nullable: true description: Parent snapshot this row forked from, if any type: string format: uuid created_at: type: string description: ISO 8601 creation timestamp status: type: string enum: - live - historic - draft - generating description: Versioning state. Only one 'live' row per process at a time; drafts may be edited or generating before promotion. creator_type: type: string enum: - human - ai description: Whether this row was created by a user edit ('human') or an AI pipeline run ('ai'). user_id: nullable: true description: Creator user id (the human who edited or triggered the run). type: string format: uuid sandbox_id: nullable: true description: E2B sandbox id that produced AI rows; null for user edits. type: string last_session_id: nullable: true description: Claude SDK session id for artifact-chat follow-up reuse. type: string kind: type: string enum: - transformation_proposal required: - id - process_id - source_snapshot_id - parent_id - created_at - status - creator_type - user_id - sandbox_id - last_session_id - kind additionalProperties: false total: type: integer minimum: 0 maximum: 9007199254740991 description: Total number of snapshots of this kind for the process required: - snapshots - total additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: List Clarity Process Snapshots /v2/clarity-v2/processes/{process_id}/snapshots/{kind}/{snapshot_id}: get: operationId: getClarityProcessSnapshot tags: - ClarityV2 description: Fetch the full payload for a Clarity v2 process snapshot of either kind. parameters: - schema: type: string format: uuid in: path name: process_id required: true description: The clarity process id - schema: type: string enum: - current_process - transformation_proposal in: path name: kind required: true description: Snapshot kind to list - schema: type: string format: uuid in: path name: snapshot_id required: true description: Snapshot id security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: snapshot: oneOf: - type: object properties: id: type: string format: uuid description: Snapshot id process_id: type: string format: uuid description: Parent clarity_process id source_snapshot_id: type: string nullable: true enum: - null parent_id: nullable: true description: Parent snapshot this row forked from, if any type: string format: uuid created_at: type: string description: ISO 8601 creation timestamp updated_at: type: string description: ISO 8601 last-update timestamp status: type: string enum: - live - historic - draft - generating description: Versioning state. Only one 'live' row per process at a time; drafts may be edited or generating before promotion. creator_type: type: string enum: - human - ai description: Whether this row was created by a user edit ('human') or an AI pipeline run ('ai'). user_id: nullable: true description: Creator user id (the human who edited or triggered the run). type: string format: uuid sandbox_id: nullable: true description: E2B sandbox id that produced AI rows; null for user edits. type: string last_session_id: nullable: true description: Claude SDK session id for artifact-chat follow-up reuse. type: string kind: type: string enum: - current_process data: type: object properties: version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Schema version for the current process data payload. Increment on breaking changes to the data shape so consumers can branch on the version field. steps: type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - event nodeSubtype: type: string enum: - start - end - timer - message - escalation description: BPMN event subtype. "start" (entry trigger), "end" (terminal state), "timer" (time-based wait), "message" (external communication), "escalation" (route to higher authority). description: nullable: true description: Optional prose describing what happens at this event. May be null for structural markers. type: string minLength: 1 rationale: nullable: true description: Optional reason for the event's existence. May be null for structural markers. type: string minLength: 1 sources: type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting this event. Empty array allowed (structural markers carry no evidence); non-empty values must follow the source schema. condition: nullable: true description: Always null on events; included for shape compatibility across variants. type: string extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - task nodeSubtype: type: string enum: - user - service - send - receive - manual - businessRule - script description: BPMN task subtype. "user" (human work), "service" (automated/API call), "send"/"receive" (messaging), "manual" (offline physical work), "businessRule" (rule engine), "script" (code execution). description: type: string minLength: 1 description: 'Full prose paragraph describing what happens in this step in natural language. Used for documentation reconstruction. Example: "Finance reviews the invoice in NetSuite, checking line item accuracy and matching against the purchase order before flagging for approval."' rationale: type: string minLength: 1 description: 'Why this step exists in the process — its purpose or business reason. Used by downstream agents to assess whether the step is essential or removable. Example: "Catches mispriced line items before they reach the customer and prevents downstream credit notes."' sources: minItems: 1 type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting this step's existence and details. At least one source is required — every step must trace back to something in the captures. condition: nullable: true description: 'Optional precondition that gates this task. Null when the task is unconditional. Example: "Only when invoice total exceeds $10,000"' type: string extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - gateway nodeSubtype: type: string enum: - exclusive - parallel - inclusive description: BPMN gateway subtype. "exclusive" (XOR — exactly one branch taken), "parallel" (AND — all branches taken), "inclusive" (OR — one or more branches taken). description: type: string minLength: 1 description: Full prose describing the decision logic at this gateway. rationale: type: string minLength: 1 description: Why this branching decision exists in the process. sources: minItems: 1 type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting the decision criteria. condition: description: Decision criteria evaluated at this gateway. BPMN requires this on every branching gateway. Existing rows persisted with null/empty values parse as "unknown" via a read-side preprocess; producers should write a real condition string going forward. type: string minLength: 1 extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false description: Ordered steps describing how the process works today, extracted from captures. Array position is the canonical order; BPMN topology is encoded by each step's targetSteps[] edges. swot: description: SWOT analysis produced by the swot-analysis postprocessing agent. `undefined` = agent has not yet run; `null` = agent ran and produced no analysis. nullable: true type: object properties: strengths: type: array items: type: string minLength: 1 description: 'Internal advantages of the current process — capabilities, resources, or design choices that work in its favour today. Phrase each as a short, evidence-backed statement. Example: "Bartenders know regulars by name, which keeps service personal during peak hours."' weaknesses: type: array items: type: string minLength: 1 description: 'Internal limitations of the current process — gaps, inefficiencies, or fragile assumptions visible in how it runs today. Phrase each as a short, evidence-backed statement. Example: "Manual pour times balloon during rushes because there is only one tap."' opportunities: type: array items: type: string minLength: 1 description: 'External openings the current process could exploit — adjacent automations, scale effects, or unmet needs surfaced by the captures. Example: "POS data could feed dynamic pricing for slow hours."' threats: type: array items: type: string minLength: 1 description: 'External risks that could degrade the current process — regulatory, operational, technological, or human factors visible in the captures. Example: "New ID-check legislation will require staff to interrupt every order."' required: - strengths - weaknesses - opportunities - threats additionalProperties: false summary: description: 'One short paragraph (3-5 sentences) describing the captured process at a glance. Surfaced at the top of the current-process tab so reviewers can orient themselves before scanning the steps. Example: "Customers order beer at the bar; the bartender greets them, picks an option matching their preference, pours and garnishes the glass, then rings the order through the POS before serving."' nullable: true type: string minLength: 1 required: - version - steps additionalProperties: false description: Opaque BPMN payload describing the captured current process. required: - id - process_id - source_snapshot_id - parent_id - created_at - updated_at - status - creator_type - user_id - sandbox_id - last_session_id - kind - data additionalProperties: false - type: object properties: id: type: string format: uuid description: Snapshot id process_id: type: string format: uuid description: Parent clarity_process id source_snapshot_id: type: string format: uuid parent_id: nullable: true description: Parent snapshot this row forked from, if any type: string format: uuid created_at: type: string description: ISO 8601 creation timestamp updated_at: type: string description: ISO 8601 last-update timestamp status: type: string enum: - live - historic - draft - generating description: Versioning state. Only one 'live' row per process at a time; drafts may be edited or generating before promotion. creator_type: type: string enum: - human - ai description: Whether this row was created by a user edit ('human') or an AI pipeline run ('ai'). user_id: nullable: true description: Creator user id (the human who edited or triggered the run). type: string format: uuid sandbox_id: nullable: true description: E2B sandbox id that produced AI rows; null for user edits. type: string last_session_id: nullable: true description: Claude SDK session id for artifact-chat follow-up reuse. type: string kind: type: string enum: - transformation_proposal data: type: object properties: version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Schema version for the transformation proposal data payload. Increment on breaking changes to the data shape so consumers can branch on the version field. steps: type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - event nodeSubtype: type: string enum: - start - end - timer - message - escalation description: BPMN event subtype. "start" (entry trigger), "end" (terminal state), "timer" (time-based wait), "message" (external communication), "escalation" (route to higher authority). description: nullable: true description: Optional prose describing what happens at this event. May be null for structural markers. type: string minLength: 1 rationale: nullable: true description: Optional reason for the event's existence. May be null for structural markers. type: string minLength: 1 sources: type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting this event. Empty array allowed (structural markers carry no evidence); non-empty values must follow the source schema. condition: nullable: true description: Always null on events; included for shape compatibility across variants. type: string extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - task nodeSubtype: type: string enum: - user - service - send - receive - manual - businessRule - script description: BPMN task subtype. "user" (human work), "service" (automated/API call), "send"/"receive" (messaging), "manual" (offline physical work), "businessRule" (rule engine), "script" (code execution). description: type: string minLength: 1 description: 'Full prose paragraph describing what happens in this step in natural language. Used for documentation reconstruction. Example: "Finance reviews the invoice in NetSuite, checking line item accuracy and matching against the purchase order before flagging for approval."' rationale: type: string minLength: 1 description: 'Why this step exists in the process — its purpose or business reason. Used by downstream agents to assess whether the step is essential or removable. Example: "Catches mispriced line items before they reach the customer and prevents downstream credit notes."' sources: minItems: 1 type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting this step's existence and details. At least one source is required — every step must trace back to something in the captures. condition: nullable: true description: 'Optional precondition that gates this task. Null when the task is unconditional. Example: "Only when invoice total exceeds $10,000"' type: string extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - gateway nodeSubtype: type: string enum: - exclusive - parallel - inclusive description: BPMN gateway subtype. "exclusive" (XOR — exactly one branch taken), "parallel" (AND — all branches taken), "inclusive" (OR — one or more branches taken). description: type: string minLength: 1 description: Full prose describing the decision logic at this gateway. rationale: type: string minLength: 1 description: Why this branching decision exists in the process. sources: minItems: 1 type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting the decision criteria. condition: description: Decision criteria evaluated at this gateway. BPMN requires this on every branching gateway. Existing rows persisted with null/empty values parse as "unknown" via a read-side preprocess; producers should write a real condition string going forward. type: string minLength: 1 extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false description: Ordered steps describing the proposed redesigned process. Same shape as the current process steps; BPMN topology is encoded by each step's targetSteps[] edges. summary: description: 'One short paragraph (3-5 sentences) describing the proposed transformed process at a glance. Surfaced at the top of the transformation-proposal tab so reviewers can orient themselves before scanning the steps. Example: "Customers self-order on a tablet at the bar; a smart tap auto-pours the chosen beer into a labelled glass, which the customer collects from the pickup counter once payment clears."' nullable: true type: string minLength: 1 projectedImpact: description: Answer-first, MECE-structured business case. 4-8 sentences of prose + one markdown assumptions table. Null when team context is insufficient to produce any quantitative or qualitative assessment. nullable: true type: string minLength: 1 required: - version - steps additionalProperties: false description: Opaque BPMN payload for the proposed transformed process. required: - id - process_id - source_snapshot_id - parent_id - created_at - updated_at - status - creator_type - user_id - sandbox_id - last_session_id - kind - data additionalProperties: false required: - snapshot additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: Get Clarity Process Snapshot delete: operationId: revertClarityProcessSnapshot tags: - ClarityV2 description: Archive a Clarity v2 snapshot of either kind. If the live row is archived, the repository auto-promotes the latest historic row of the same kind. parameters: - schema: type: string format: uuid in: path name: process_id required: true description: The clarity process id - schema: type: string enum: - current_process - transformation_proposal in: path name: kind required: true description: Snapshot kind to list - schema: type: string format: uuid in: path name: snapshot_id required: true description: Snapshot id security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: success: type: boolean required: - success additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '409': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: Revert Clarity Process Snapshot /v2/clarity-v2/processes/{process_id}/snapshots/{kind}/save: post: operationId: saveClarityProcessSnapshot tags: - ClarityV2 description: Save user edits as the live Clarity v2 snapshot for the selected kind. requestBody: required: true content: application/json: schema: type: object properties: steps: minItems: 1 type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - event nodeSubtype: type: string enum: - start - end - timer - message - escalation description: BPMN event subtype. "start" (entry trigger), "end" (terminal state), "timer" (time-based wait), "message" (external communication), "escalation" (route to higher authority). description: nullable: true description: Optional prose describing what happens at this event. May be null for structural markers. type: string minLength: 1 rationale: nullable: true description: Optional reason for the event's existence. May be null for structural markers. type: string minLength: 1 sources: type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs - type: object properties: type: type: string enum: - manual required: - type - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt description: Evidence supporting this event. Empty array allowed (structural markers carry no evidence); non-empty values must follow the source schema. condition: nullable: true description: Always null on events; included for shape compatibility across variants. type: string extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - task nodeSubtype: type: string enum: - user - service - send - receive - manual - businessRule - script description: BPMN task subtype. "user" (human work), "service" (automated/API call), "send"/"receive" (messaging), "manual" (offline physical work), "businessRule" (rule engine), "script" (code execution). description: type: string minLength: 1 description: 'Full prose paragraph describing what happens in this step in natural language. Used for documentation reconstruction. Example: "Finance reviews the invoice in NetSuite, checking line item accuracy and matching against the purchase order before flagging for approval."' rationale: type: string minLength: 1 description: 'Why this step exists in the process — its purpose or business reason. Used by downstream agents to assess whether the step is essential or removable. Example: "Catches mispriced line items before they reach the customer and prevents downstream credit notes."' sources: minItems: 1 type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs - type: object properties: type: type: string enum: - manual required: - type - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt description: Evidence supporting this step's existence and details. At least one source is required — every step must trace back to something in the captures. condition: nullable: true description: 'Optional precondition that gates this task. Null when the task is unconditional. Example: "Only when invoice total exceeds $10,000"' type: string extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - gateway nodeSubtype: type: string enum: - exclusive - parallel - inclusive description: BPMN gateway subtype. "exclusive" (XOR — exactly one branch taken), "parallel" (AND — all branches taken), "inclusive" (OR — one or more branches taken). description: type: string minLength: 1 description: Full prose describing the decision logic at this gateway. rationale: type: string minLength: 1 description: Why this branching decision exists in the process. sources: minItems: 1 type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs - type: object properties: type: type: string enum: - manual required: - type - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt description: Evidence supporting the decision criteria. condition: description: Decision criteria evaluated at this gateway. BPMN requires this on every branching gateway. Existing rows persisted with null/empty values parse as "unknown" via a read-side preprocess; producers should write a real condition string going forward. type: string minLength: 1 extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition baselineSnapshotId: type: string format: uuid clarityCurrentProcessId: type: string format: uuid swot: description: SWOT analysis produced by the swot-analysis postprocessing agent. `undefined` = agent has not yet run; `null` = agent ran and produced no analysis. nullable: true type: object properties: strengths: type: array items: type: string minLength: 1 description: 'Internal advantages of the current process — capabilities, resources, or design choices that work in its favour today. Phrase each as a short, evidence-backed statement. Example: "Bartenders know regulars by name, which keeps service personal during peak hours."' weaknesses: type: array items: type: string minLength: 1 description: 'Internal limitations of the current process — gaps, inefficiencies, or fragile assumptions visible in how it runs today. Phrase each as a short, evidence-backed statement. Example: "Manual pour times balloon during rushes because there is only one tap."' opportunities: type: array items: type: string minLength: 1 description: 'External openings the current process could exploit — adjacent automations, scale effects, or unmet needs surfaced by the captures. Example: "POS data could feed dynamic pricing for slow hours."' threats: type: array items: type: string minLength: 1 description: 'External risks that could degrade the current process — regulatory, operational, technological, or human factors visible in the captures. Example: "New ID-check legislation will require staff to interrupt every order."' required: - strengths - weaknesses - opportunities - threats summary: description: 'One short paragraph (3-5 sentences) describing the captured process at a glance. Surfaced at the top of the current-process tab so reviewers can orient themselves before scanning the steps. Example: "Customers order beer at the bar; the bartender greets them, picks an option matching their preference, pours and garnishes the glass, then rings the order through the POS before serving."' nullable: true type: string minLength: 1 projectedImpact: description: Answer-first, MECE-structured business case. 4-8 sentences of prose + one markdown assumptions table. Null when team context is insufficient to produce any quantitative or qualitative assessment. nullable: true type: string minLength: 1 required: - steps - baselineSnapshotId parameters: - schema: type: string format: uuid in: path name: process_id required: true description: The clarity process id - schema: type: string enum: - current_process - transformation_proposal in: path name: kind required: true description: Snapshot kind to list security: - bearerAuth: [] responses: '201': description: Default Response content: application/json: schema: type: object properties: snapshot: oneOf: - type: object properties: id: type: string format: uuid description: Snapshot id process_id: type: string format: uuid description: Parent clarity_process id source_snapshot_id: type: string nullable: true enum: - null parent_id: nullable: true description: Parent snapshot this row forked from, if any type: string format: uuid created_at: type: string description: ISO 8601 creation timestamp updated_at: type: string description: ISO 8601 last-update timestamp status: type: string enum: - live - historic - draft - generating description: Versioning state. Only one 'live' row per process at a time; drafts may be edited or generating before promotion. creator_type: type: string enum: - human - ai description: Whether this row was created by a user edit ('human') or an AI pipeline run ('ai'). user_id: nullable: true description: Creator user id (the human who edited or triggered the run). type: string format: uuid sandbox_id: nullable: true description: E2B sandbox id that produced AI rows; null for user edits. type: string last_session_id: nullable: true description: Claude SDK session id for artifact-chat follow-up reuse. type: string kind: type: string enum: - current_process data: type: object properties: version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Schema version for the current process data payload. Increment on breaking changes to the data shape so consumers can branch on the version field. steps: type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - event nodeSubtype: type: string enum: - start - end - timer - message - escalation description: BPMN event subtype. "start" (entry trigger), "end" (terminal state), "timer" (time-based wait), "message" (external communication), "escalation" (route to higher authority). description: nullable: true description: Optional prose describing what happens at this event. May be null for structural markers. type: string minLength: 1 rationale: nullable: true description: Optional reason for the event's existence. May be null for structural markers. type: string minLength: 1 sources: type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting this event. Empty array allowed (structural markers carry no evidence); non-empty values must follow the source schema. condition: nullable: true description: Always null on events; included for shape compatibility across variants. type: string extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - task nodeSubtype: type: string enum: - user - service - send - receive - manual - businessRule - script description: BPMN task subtype. "user" (human work), "service" (automated/API call), "send"/"receive" (messaging), "manual" (offline physical work), "businessRule" (rule engine), "script" (code execution). description: type: string minLength: 1 description: 'Full prose paragraph describing what happens in this step in natural language. Used for documentation reconstruction. Example: "Finance reviews the invoice in NetSuite, checking line item accuracy and matching against the purchase order before flagging for approval."' rationale: type: string minLength: 1 description: 'Why this step exists in the process — its purpose or business reason. Used by downstream agents to assess whether the step is essential or removable. Example: "Catches mispriced line items before they reach the customer and prevents downstream credit notes."' sources: minItems: 1 type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting this step's existence and details. At least one source is required — every step must trace back to something in the captures. condition: nullable: true description: 'Optional precondition that gates this task. Null when the task is unconditional. Example: "Only when invoice total exceeds $10,000"' type: string extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - gateway nodeSubtype: type: string enum: - exclusive - parallel - inclusive description: BPMN gateway subtype. "exclusive" (XOR — exactly one branch taken), "parallel" (AND — all branches taken), "inclusive" (OR — one or more branches taken). description: type: string minLength: 1 description: Full prose describing the decision logic at this gateway. rationale: type: string minLength: 1 description: Why this branching decision exists in the process. sources: minItems: 1 type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting the decision criteria. condition: description: Decision criteria evaluated at this gateway. BPMN requires this on every branching gateway. Existing rows persisted with null/empty values parse as "unknown" via a read-side preprocess; producers should write a real condition string going forward. type: string minLength: 1 extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false description: Ordered steps describing how the process works today, extracted from captures. Array position is the canonical order; BPMN topology is encoded by each step's targetSteps[] edges. swot: description: SWOT analysis produced by the swot-analysis postprocessing agent. `undefined` = agent has not yet run; `null` = agent ran and produced no analysis. nullable: true type: object properties: strengths: type: array items: type: string minLength: 1 description: 'Internal advantages of the current process — capabilities, resources, or design choices that work in its favour today. Phrase each as a short, evidence-backed statement. Example: "Bartenders know regulars by name, which keeps service personal during peak hours."' weaknesses: type: array items: type: string minLength: 1 description: 'Internal limitations of the current process — gaps, inefficiencies, or fragile assumptions visible in how it runs today. Phrase each as a short, evidence-backed statement. Example: "Manual pour times balloon during rushes because there is only one tap."' opportunities: type: array items: type: string minLength: 1 description: 'External openings the current process could exploit — adjacent automations, scale effects, or unmet needs surfaced by the captures. Example: "POS data could feed dynamic pricing for slow hours."' threats: type: array items: type: string minLength: 1 description: 'External risks that could degrade the current process — regulatory, operational, technological, or human factors visible in the captures. Example: "New ID-check legislation will require staff to interrupt every order."' required: - strengths - weaknesses - opportunities - threats additionalProperties: false summary: description: 'One short paragraph (3-5 sentences) describing the captured process at a glance. Surfaced at the top of the current-process tab so reviewers can orient themselves before scanning the steps. Example: "Customers order beer at the bar; the bartender greets them, picks an option matching their preference, pours and garnishes the glass, then rings the order through the POS before serving."' nullable: true type: string minLength: 1 required: - version - steps additionalProperties: false description: Opaque BPMN payload describing the captured current process. required: - id - process_id - source_snapshot_id - parent_id - created_at - updated_at - status - creator_type - user_id - sandbox_id - last_session_id - kind - data additionalProperties: false - type: object properties: id: type: string format: uuid description: Snapshot id process_id: type: string format: uuid description: Parent clarity_process id source_snapshot_id: type: string format: uuid parent_id: nullable: true description: Parent snapshot this row forked from, if any type: string format: uuid created_at: type: string description: ISO 8601 creation timestamp updated_at: type: string description: ISO 8601 last-update timestamp status: type: string enum: - live - historic - draft - generating description: Versioning state. Only one 'live' row per process at a time; drafts may be edited or generating before promotion. creator_type: type: string enum: - human - ai description: Whether this row was created by a user edit ('human') or an AI pipeline run ('ai'). user_id: nullable: true description: Creator user id (the human who edited or triggered the run). type: string format: uuid sandbox_id: nullable: true description: E2B sandbox id that produced AI rows; null for user edits. type: string last_session_id: nullable: true description: Claude SDK session id for artifact-chat follow-up reuse. type: string kind: type: string enum: - transformation_proposal data: type: object properties: version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Schema version for the transformation proposal data payload. Increment on breaking changes to the data shape so consumers can branch on the version field. steps: type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - event nodeSubtype: type: string enum: - start - end - timer - message - escalation description: BPMN event subtype. "start" (entry trigger), "end" (terminal state), "timer" (time-based wait), "message" (external communication), "escalation" (route to higher authority). description: nullable: true description: Optional prose describing what happens at this event. May be null for structural markers. type: string minLength: 1 rationale: nullable: true description: Optional reason for the event's existence. May be null for structural markers. type: string minLength: 1 sources: type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting this event. Empty array allowed (structural markers carry no evidence); non-empty values must follow the source schema. condition: nullable: true description: Always null on events; included for shape compatibility across variants. type: string extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - task nodeSubtype: type: string enum: - user - service - send - receive - manual - businessRule - script description: BPMN task subtype. "user" (human work), "service" (automated/API call), "send"/"receive" (messaging), "manual" (offline physical work), "businessRule" (rule engine), "script" (code execution). description: type: string minLength: 1 description: 'Full prose paragraph describing what happens in this step in natural language. Used for documentation reconstruction. Example: "Finance reviews the invoice in NetSuite, checking line item accuracy and matching against the purchase order before flagging for approval."' rationale: type: string minLength: 1 description: 'Why this step exists in the process — its purpose or business reason. Used by downstream agents to assess whether the step is essential or removable. Example: "Catches mispriced line items before they reach the customer and prevents downstream credit notes."' sources: minItems: 1 type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting this step's existence and details. At least one source is required — every step must trace back to something in the captures. condition: nullable: true description: 'Optional precondition that gates this task. Null when the task is unconditional. Example: "Only when invoice total exceeds $10,000"' type: string extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - gateway nodeSubtype: type: string enum: - exclusive - parallel - inclusive description: BPMN gateway subtype. "exclusive" (XOR — exactly one branch taken), "parallel" (AND — all branches taken), "inclusive" (OR — one or more branches taken). description: type: string minLength: 1 description: Full prose describing the decision logic at this gateway. rationale: type: string minLength: 1 description: Why this branching decision exists in the process. sources: minItems: 1 type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting the decision criteria. condition: description: Decision criteria evaluated at this gateway. BPMN requires this on every branching gateway. Existing rows persisted with null/empty values parse as "unknown" via a read-side preprocess; producers should write a real condition string going forward. type: string minLength: 1 extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false description: Ordered steps describing the proposed redesigned process. Same shape as the current process steps; BPMN topology is encoded by each step's targetSteps[] edges. summary: description: 'One short paragraph (3-5 sentences) describing the proposed transformed process at a glance. Surfaced at the top of the transformation-proposal tab so reviewers can orient themselves before scanning the steps. Example: "Customers self-order on a tablet at the bar; a smart tap auto-pours the chosen beer into a labelled glass, which the customer collects from the pickup counter once payment clears."' nullable: true type: string minLength: 1 projectedImpact: description: Answer-first, MECE-structured business case. 4-8 sentences of prose + one markdown assumptions table. Null when team context is insufficient to produce any quantitative or qualitative assessment. nullable: true type: string minLength: 1 required: - version - steps additionalProperties: false description: Opaque BPMN payload for the proposed transformed process. required: - id - process_id - source_snapshot_id - parent_id - created_at - updated_at - status - creator_type - user_id - sandbox_id - last_session_id - kind - data additionalProperties: false required: - snapshot additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '409': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: Save Clarity Process Snapshot /v2/clarity-v2/processes/{process_id}/snapshots/{kind}/{snapshot_id}/promote: post: operationId: promoteClarityProcessSnapshot tags: - ClarityV2 description: Promote a draft or historic Clarity v2 snapshot to live for its kind. parameters: - schema: type: string format: uuid in: path name: process_id required: true description: The clarity process id - schema: type: string enum: - current_process - transformation_proposal in: path name: kind required: true description: Snapshot kind to list - schema: type: string format: uuid in: path name: snapshot_id required: true description: Snapshot id security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: snapshot: oneOf: - type: object properties: id: type: string format: uuid description: Snapshot id process_id: type: string format: uuid description: Parent clarity_process id source_snapshot_id: type: string nullable: true enum: - null parent_id: nullable: true description: Parent snapshot this row forked from, if any type: string format: uuid created_at: type: string description: ISO 8601 creation timestamp updated_at: type: string description: ISO 8601 last-update timestamp status: type: string enum: - live - historic - draft - generating description: Versioning state. Only one 'live' row per process at a time; drafts may be edited or generating before promotion. creator_type: type: string enum: - human - ai description: Whether this row was created by a user edit ('human') or an AI pipeline run ('ai'). user_id: nullable: true description: Creator user id (the human who edited or triggered the run). type: string format: uuid sandbox_id: nullable: true description: E2B sandbox id that produced AI rows; null for user edits. type: string last_session_id: nullable: true description: Claude SDK session id for artifact-chat follow-up reuse. type: string kind: type: string enum: - current_process data: type: object properties: version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Schema version for the current process data payload. Increment on breaking changes to the data shape so consumers can branch on the version field. steps: type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - event nodeSubtype: type: string enum: - start - end - timer - message - escalation description: BPMN event subtype. "start" (entry trigger), "end" (terminal state), "timer" (time-based wait), "message" (external communication), "escalation" (route to higher authority). description: nullable: true description: Optional prose describing what happens at this event. May be null for structural markers. type: string minLength: 1 rationale: nullable: true description: Optional reason for the event's existence. May be null for structural markers. type: string minLength: 1 sources: type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting this event. Empty array allowed (structural markers carry no evidence); non-empty values must follow the source schema. condition: nullable: true description: Always null on events; included for shape compatibility across variants. type: string extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - task nodeSubtype: type: string enum: - user - service - send - receive - manual - businessRule - script description: BPMN task subtype. "user" (human work), "service" (automated/API call), "send"/"receive" (messaging), "manual" (offline physical work), "businessRule" (rule engine), "script" (code execution). description: type: string minLength: 1 description: 'Full prose paragraph describing what happens in this step in natural language. Used for documentation reconstruction. Example: "Finance reviews the invoice in NetSuite, checking line item accuracy and matching against the purchase order before flagging for approval."' rationale: type: string minLength: 1 description: 'Why this step exists in the process — its purpose or business reason. Used by downstream agents to assess whether the step is essential or removable. Example: "Catches mispriced line items before they reach the customer and prevents downstream credit notes."' sources: minItems: 1 type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting this step's existence and details. At least one source is required — every step must trace back to something in the captures. condition: nullable: true description: 'Optional precondition that gates this task. Null when the task is unconditional. Example: "Only when invoice total exceeds $10,000"' type: string extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - gateway nodeSubtype: type: string enum: - exclusive - parallel - inclusive description: BPMN gateway subtype. "exclusive" (XOR — exactly one branch taken), "parallel" (AND — all branches taken), "inclusive" (OR — one or more branches taken). description: type: string minLength: 1 description: Full prose describing the decision logic at this gateway. rationale: type: string minLength: 1 description: Why this branching decision exists in the process. sources: minItems: 1 type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting the decision criteria. condition: description: Decision criteria evaluated at this gateway. BPMN requires this on every branching gateway. Existing rows persisted with null/empty values parse as "unknown" via a read-side preprocess; producers should write a real condition string going forward. type: string minLength: 1 extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false description: Ordered steps describing how the process works today, extracted from captures. Array position is the canonical order; BPMN topology is encoded by each step's targetSteps[] edges. swot: description: SWOT analysis produced by the swot-analysis postprocessing agent. `undefined` = agent has not yet run; `null` = agent ran and produced no analysis. nullable: true type: object properties: strengths: type: array items: type: string minLength: 1 description: 'Internal advantages of the current process — capabilities, resources, or design choices that work in its favour today. Phrase each as a short, evidence-backed statement. Example: "Bartenders know regulars by name, which keeps service personal during peak hours."' weaknesses: type: array items: type: string minLength: 1 description: 'Internal limitations of the current process — gaps, inefficiencies, or fragile assumptions visible in how it runs today. Phrase each as a short, evidence-backed statement. Example: "Manual pour times balloon during rushes because there is only one tap."' opportunities: type: array items: type: string minLength: 1 description: 'External openings the current process could exploit — adjacent automations, scale effects, or unmet needs surfaced by the captures. Example: "POS data could feed dynamic pricing for slow hours."' threats: type: array items: type: string minLength: 1 description: 'External risks that could degrade the current process — regulatory, operational, technological, or human factors visible in the captures. Example: "New ID-check legislation will require staff to interrupt every order."' required: - strengths - weaknesses - opportunities - threats additionalProperties: false summary: description: 'One short paragraph (3-5 sentences) describing the captured process at a glance. Surfaced at the top of the current-process tab so reviewers can orient themselves before scanning the steps. Example: "Customers order beer at the bar; the bartender greets them, picks an option matching their preference, pours and garnishes the glass, then rings the order through the POS before serving."' nullable: true type: string minLength: 1 required: - version - steps additionalProperties: false description: Opaque BPMN payload describing the captured current process. required: - id - process_id - source_snapshot_id - parent_id - created_at - updated_at - status - creator_type - user_id - sandbox_id - last_session_id - kind - data additionalProperties: false - type: object properties: id: type: string format: uuid description: Snapshot id process_id: type: string format: uuid description: Parent clarity_process id source_snapshot_id: type: string format: uuid parent_id: nullable: true description: Parent snapshot this row forked from, if any type: string format: uuid created_at: type: string description: ISO 8601 creation timestamp updated_at: type: string description: ISO 8601 last-update timestamp status: type: string enum: - live - historic - draft - generating description: Versioning state. Only one 'live' row per process at a time; drafts may be edited or generating before promotion. creator_type: type: string enum: - human - ai description: Whether this row was created by a user edit ('human') or an AI pipeline run ('ai'). user_id: nullable: true description: Creator user id (the human who edited or triggered the run). type: string format: uuid sandbox_id: nullable: true description: E2B sandbox id that produced AI rows; null for user edits. type: string last_session_id: nullable: true description: Claude SDK session id for artifact-chat follow-up reuse. type: string kind: type: string enum: - transformation_proposal data: type: object properties: version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Schema version for the transformation proposal data payload. Increment on breaking changes to the data shape so consumers can branch on the version field. steps: type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - event nodeSubtype: type: string enum: - start - end - timer - message - escalation description: BPMN event subtype. "start" (entry trigger), "end" (terminal state), "timer" (time-based wait), "message" (external communication), "escalation" (route to higher authority). description: nullable: true description: Optional prose describing what happens at this event. May be null for structural markers. type: string minLength: 1 rationale: nullable: true description: Optional reason for the event's existence. May be null for structural markers. type: string minLength: 1 sources: type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting this event. Empty array allowed (structural markers carry no evidence); non-empty values must follow the source schema. condition: nullable: true description: Always null on events; included for shape compatibility across variants. type: string extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - task nodeSubtype: type: string enum: - user - service - send - receive - manual - businessRule - script description: BPMN task subtype. "user" (human work), "service" (automated/API call), "send"/"receive" (messaging), "manual" (offline physical work), "businessRule" (rule engine), "script" (code execution). description: type: string minLength: 1 description: 'Full prose paragraph describing what happens in this step in natural language. Used for documentation reconstruction. Example: "Finance reviews the invoice in NetSuite, checking line item accuracy and matching against the purchase order before flagging for approval."' rationale: type: string minLength: 1 description: 'Why this step exists in the process — its purpose or business reason. Used by downstream agents to assess whether the step is essential or removable. Example: "Catches mispriced line items before they reach the customer and prevents downstream credit notes."' sources: minItems: 1 type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting this step's existence and details. At least one source is required — every step must trace back to something in the captures. condition: nullable: true description: 'Optional precondition that gates this task. Null when the task is unconditional. Example: "Only when invoice total exceeds $10,000"' type: string extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false - type: object properties: id: type: string minLength: 1 description: 'Stable identifier for the step. Referenced by targetSteps[].stepId and by postprocessing agents annotating specific steps. Example: "step-review-invoice"' targetSteps: type: array items: type: object properties: stepId: type: string minLength: 1 description: 'Id of the step this edge points to. Must match an existing step.id in the same steps array. Example: "step-review-invoice"' label: nullable: true description: 'Human-readable label shown on the BPMN edge. For gateways, the outcome answer; for default flows, "Otherwise". Examples: "Approved", "> $5k", "Otherwise"' type: string isDefault: type: boolean description: True on exactly one outgoing edge of an exclusive or inclusive gateway, marking the fallback taken when no other condition matches. False on all other edges. required: - stepId - label - isDefault additionalProperties: false description: 'Outgoing BPMN edges from this step. Empty array only on end events. Exclusive and inclusive gateways must have ≥2 entries with exactly one isDefault: true.' title: type: string minLength: 1 description: Required node label used in lists and BPMN node labels. Structural markers use defaults such as "Start" and "End". action: nullable: true description: 'Verb-led one-liner summarizing the concrete action performed. Example: "Reviews invoice line items in NetSuite against the purchase order."' type: string minLength: 1 role: nullable: true description: 'Performer of this step — the specific job title, team, or system. Use "Duvo" for automated actions and "System" for system-triggered steps. Examples: "Finance Analyst", "Sales Operations", "Duvo", "System"' type: string minLength: 1 system: nullable: true description: 'System, tool, or application used to perform this step. Null when the step is purely manual or is a decision/event with no associated tool. Examples: "NetSuite", "Gmail", "Excel", null' type: string input: nullable: true description: 'Information or artifacts required to start this step. Null on start events or steps with no preconditions. Example: "Invoice PDF and matching purchase order number"' type: string output: nullable: true description: 'What this step produces or updates. Null on pure waits or events that emit nothing. Example: "Approved invoice record in NetSuite with reviewer signature"' type: string exception: nullable: true description: 'Known exceptions, errors, or failure modes observed in the captures for this step. Null when none were mentioned. Example: "Customer disputes line items or PO number does not match"' type: string handling: nullable: true description: 'How exceptions or escalations are handled — escalation path, fallback action, or retry strategy. Null when no exception or no handling described. Example: "Escalate to AP manager via email and pause processing until resolved"' type: string assumptions: nullable: true description: 'Assumptions the LLM made when extracting this step that were not directly stated in captures. Null if none. Used by verification agents to flag risky inferences. Example: ["Invoices are reviewed within 24 hours of receipt"]' type: array items: type: string openQuestions: nullable: true description: 'Specific gaps in understanding that a follow-up capture should address. Null if none. Drives the next interview or document request. Example: ["Is there a backup approver when the AP manager is out of office?"]' type: array items: type: string confidence: type: string enum: - low - medium - high description: Confidence in the accuracy of this step given evidence quality and completeness. "high" = directly stated by multiple sources, "medium" = stated by one source or inferred from strong signals, "low" = inferred with significant assumptions. nodeType: type: string enum: - gateway nodeSubtype: type: string enum: - exclusive - parallel - inclusive description: BPMN gateway subtype. "exclusive" (XOR — exactly one branch taken), "parallel" (AND — all branches taken), "inclusive" (OR — one or more branches taken). description: type: string minLength: 1 description: Full prose describing the decision logic at this gateway. rationale: type: string minLength: 1 description: Why this branching decision exists in the process. sources: minItems: 1 type: array items: type: object properties: attribution: type: string minLength: 1 description: 'Human-readable source label identifying who or what the evidence comes from. Examples: "Anna (sales interview)", "Onboarding SOP §3.2", "Slack #ops 2024-06-12"' excerpt: type: string minLength: 1 description: 'Verbatim supporting text quoted from the capture, document, or transcript. Example: "We always wait for finance to sign off before sending the invoice."' captureId: description: Durable clarity_capture id for this source. Use app-owned ids from the evidence index, never sandbox file paths. type: string minLength: 1 evidenceId: description: Stable id of the evidence unit from /workspace/captures/evidence-index.json when generation used that index. type: string minLength: 1 locator: description: Durable in-capture location for the excerpt. Missing means legacy free-text source; unresolved means a structured citation was attempted but could not be resolved. oneOf: - type: object properties: type: type: string enum: - transcript_message messageIndex: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based index into the capture transcript message array. This is the durable key; timestampMs is only supplemental. timestampMs: description: Optional epoch-millisecond timestamp for the transcript message when the capture supplied one. type: integer minimum: 0 maximum: 9007199254740991 required: - type - messageIndex additionalProperties: false - type: object properties: type: type: string enum: - document_text_range startOffset: type: integer minimum: 0 maximum: 9007199254740991 description: Zero-based character offset into the stored capture text. endOffset: type: integer exclusiveMinimum: true maximum: 9007199254740991 description: Exclusive character offset into the stored capture text. Must be greater than startOffset. pageNumber: description: Optional one-based PDF page number when the stored capture has page metadata. type: integer exclusiveMinimum: true maximum: 9007199254740991 startLine: description: Optional one-based line number where the cited text starts on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 endLine: description: Optional one-based line number where the cited text ends on pageNumber. type: integer exclusiveMinimum: true maximum: 9007199254740991 required: - type - startOffset - endOffset additionalProperties: false - type: object properties: type: type: string enum: - bpmn_element elementId: type: string minLength: 1 description: BPMN XML element id within an uploaded .bpmn document. elementType: description: Optional BPMN element type as parsed from the XML, for example "bpmn:UserTask" or "bpmn:ExclusiveGateway". type: string minLength: 1 name: description: Optional BPMN element name as parsed from the XML. The element id is the durable key. type: string minLength: 1 required: - type - elementId additionalProperties: false - type: object properties: type: type: string enum: - screenshare_frame timestampMs: type: integer minimum: 0 maximum: 9007199254740991 description: Epoch-millisecond frame timestamp matching a screenshare frame filename. required: - type - timestampMs additionalProperties: false - type: object properties: type: type: string enum: - manual required: - type additionalProperties: false - type: object properties: type: type: string enum: - unresolved reason: type: string minLength: 1 required: - type additionalProperties: false sourceConfidence: description: Confidence in this individual source citation. "high" = direct quote at the locator, "medium" = strong nearby evidence, "low" = weak or inferred support. type: string enum: - low - medium - high resolutionStatus: description: Resolution status for the structured source link. Legacy sources may omit this field. type: string enum: - resolved - unresolved - legacy - manual required: - attribution - excerpt additionalProperties: false description: Evidence supporting the decision criteria. condition: description: Decision criteria evaluated at this gateway. BPMN requires this on every branching gateway. Existing rows persisted with null/empty values parse as "unknown" via a read-side preprocess; producers should write a real condition string going forward. type: string minLength: 1 extraCaptureNeeded: nullable: true type: object properties: id: type: string format: uuid description: Id of the `clarity_proposal_extra_capture_request` row this slot points at. Created server-side by the agent after the LLM call; the LLM never produces this value. gap: type: string minLength: 1 description: 'Plain-language description of what about this step is unknown or under-specified, blocking automation. One short sentence. Example: "We don''t know which fields the AP analyst copies from the invoice into NetSuite."' proposal: description: 'What the new capture should include in order to resolve the gap — concrete actions, screens, or decisions the user should walk through. Optional: omit when no specific proposal can be inferred. Example: "Walk through reviewing one invoice in NetSuite end-to-end while narrating each field you check."' nullable: true type: string minLength: 1 required: - id - gap additionalProperties: false readiness: description: Automation-readiness rating for this step. "high" = fully automatable today, "medium" = partially automatable or needs minor changes, "low" = blocked by manual review, judgement, or missing data. nullable: true type: string enum: - low - medium - high readinessRationale: description: 'One-sentence justification for the readiness rating, citing the specific signals that drove the choice. Example: "Requires human judgement on edge cases that are not documented in the captures."' nullable: true type: string required: - id - targetSteps - title - action - role - system - input - output - exception - handling - assumptions - openQuestions - confidence - nodeType - nodeSubtype - description - rationale - sources - condition additionalProperties: false description: Ordered steps describing the proposed redesigned process. Same shape as the current process steps; BPMN topology is encoded by each step's targetSteps[] edges. summary: description: 'One short paragraph (3-5 sentences) describing the proposed transformed process at a glance. Surfaced at the top of the transformation-proposal tab so reviewers can orient themselves before scanning the steps. Example: "Customers self-order on a tablet at the bar; a smart tap auto-pours the chosen beer into a labelled glass, which the customer collects from the pickup counter once payment clears."' nullable: true type: string minLength: 1 projectedImpact: description: Answer-first, MECE-structured business case. 4-8 sentences of prose + one markdown assumptions table. Null when team context is insufficient to produce any quantitative or qualitative assessment. nullable: true type: string minLength: 1 required: - version - steps additionalProperties: false description: Opaque BPMN payload for the proposed transformed process. required: - id - process_id - source_snapshot_id - parent_id - created_at - updated_at - status - creator_type - user_id - sandbox_id - last_session_id - kind - data additionalProperties: false required: - snapshot additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '409': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: Promote Clarity Process Snapshot /v2/clarity-v2/processes/{process_id}/snapshots/{kind}/generate: post: operationId: generateClarityProcessSnapshot tags: - ClarityV2 description: Trigger a snapshot generation pipeline for a v2 clarity process, selected by kind. `current_process` runs the generateCurrentProcess pipeline (body fields are proposal-only and rejected); `transformation_proposal` runs the generate or regenerate proposal pipeline. Returns 202 immediately and finalises asynchronously via the cc-server webhook stream. requestBody: required: true content: application/json: schema: default: transformation_aggressiveness: aggressive type: object properties: source_snapshot_id: description: 'Transformation proposals only: id of the current-process snapshot to anchor the new proposal to. Defaults to the latest snapshot for the process.' type: string format: uuid regenerate_from: description: 'Transformation proposals only: id of a prior proposal snapshot to refine. When supplied, runs the regenerate pipeline using that proposal''s current-process snapshot as the anchor and the extra captures collected since.' type: string format: uuid custom_guidance: description: 'Transformation proposals only: optional freeform guidance for this generation. Used as high-priority design guidance, not source-of-truth evidence.' type: string maxLength: 2000 transformation_aggressiveness: default: aggressive description: 'Transformation proposals only: controls how much the generated proposal should change the current process structure.' type: string enum: - none - conservative - aggressive additionalProperties: false parameters: - schema: type: string format: uuid in: path name: process_id required: true description: The clarity process id - schema: type: string enum: - current_process - transformation_proposal in: path name: kind required: true description: Snapshot kind to list security: - bearerAuth: [] responses: '202': description: Default Response content: application/json: schema: type: object properties: success: type: boolean enum: - true description: Generation kickoff was accepted required: - success additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '409': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: Generate Clarity Process Snapshot /v2/clarity-v2/processes/{process_id}/snapshots/{kind}/stop: post: operationId: stopClarityProcessSnapshot tags: - ClarityV2 description: Stop an in-flight snapshot generation for the selected kind. Reads the sandbox id from the process row, kills the sandbox, flips the process back to `review`, and clears the sandbox marker so any late webhook from the killed run is dropped as stale. parameters: - schema: type: string format: uuid in: path name: process_id required: true description: The clarity process id - schema: type: string enum: - current_process - transformation_proposal in: path name: kind required: true description: Snapshot kind to list security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: success: type: boolean required: - success additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '409': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: Stop Clarity Process Snapshot /v2/teams/{teamId}/clarity-v2/processes: get: operationId: listClarityProcesses tags: - ClarityV2 description: List Clarity processes for the current team, most recently updated first. Returns lightweight metadata (capture counts, contributors, status) suitable for building a picker; the per-process read model is available via `GET /v2/teams/:team_id/clarity-v2/processes/:process_id` for v2 rows and `GET /v2/teams/:team_id/clarity/processes/:id` for legacy v1 rows. Both v1 (legacy) and v2 processes are returned by default; use `search`, `status`, and `version` to narrow discovery. Capped at 100 per page. parameters: - schema: default: 50 type: integer minimum: 1 maximum: 100 in: query name: limit required: false description: Number of processes per page (1-100, default 50) - schema: type: integer minimum: 0 maximum: 9007199254740991 in: query name: offset required: false description: Number of processes to skip (default 0) - schema: type: string minLength: 1 maxLength: 200 in: query name: search required: false description: Case-insensitive search across process names - schema: type: string enum: - draft - collecting - generating - generating-current-process - generating-transformation-proposal - review - complete - generation_failed in: query name: status required: false description: Filter by process lifecycle status - schema: type: integer minimum: -9007199254740991 maximum: 9007199254740991 in: query name: version required: false description: 'Filter by Clarity process schema version: 1 legacy, 2 v2' - schema: type: string in: path name: teamId required: true security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: processes: type: array items: type: object properties: id: type: string format: uuid name: type: string status: type: string enum: - draft - collecting - generating - generating-current-process - generating-transformation-proposal - review - complete - generation_failed visibility: type: string enum: - team - restricted version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: 1 = legacy clarity, 2 = clarity v2 capture_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 capture_counts: type: object properties: video: type: integer minimum: -9007199254740991 maximum: 9007199254740991 interview: type: integer minimum: -9007199254740991 maximum: 9007199254740991 document: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - video - interview - document additionalProperties: false pending_invitation_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 contributors: type: array items: type: object properties: user_id: type: string user_name: type: string required: - user_id - user_name additionalProperties: false created_at: type: string updated_at: type: string created_by_name: nullable: true type: string required: - id - name - status - visibility - version - capture_count - pending_invitation_count - contributors - created_at - updated_at - created_by_name additionalProperties: false total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 limit: type: integer minimum: -9007199254740991 maximum: 9007199254740991 offset: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - processes - total - limit - offset additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: List Clarity Processes /v2/teams/{teamId}/clarity-v2/processes/summaries: get: operationId: listClarityProcessSummaries tags: - ClarityV2 description: 'Cross-process portfolio digest for every completed Clarity process on the team: per-process summary, SWOT, projected impact, and a step skeleton (role, system, and flow edges) — without step prose or source excerpts. Paginated (default 5, max 10). Use this to answer portfolio-wide questions in one pass; fetch a single process''s full detail via getClarityProcessSnapshot only for the few that matter.' parameters: - schema: default: 5 type: integer minimum: 1 maximum: 10 in: query name: limit required: false description: Processes per page (1-10, default 5). Keeps the response under the MCP output cap. - schema: type: integer minimum: 0 maximum: 9007199254740991 in: query name: offset required: false description: Processes to skip (default 0). - schema: default: skeleton type: string enum: - skeleton - summary in: query name: detail required: false description: skeleton = + per-step role/system/flow edges (default); summary = summary+SWOT+impact only (cheaper, for pure ranking). - schema: default: 'false' type: string enum: - 'true' - 'false' in: query name: include_current_steps required: false description: Include the as-is (current) step skeleton too. Default false = proposed (to-be) steps only. Pass the literal string 'true' or 'false' (z.coerce.boolean treats any non-empty value, including 'false', as true). - schema: type: string in: path name: teamId required: true security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: processes: type: array items: type: object properties: id: type: string format: uuid name: type: string status: type: string enum: - draft - collecting - generating - generating-current-process - generating-transformation-proposal - review - complete - generation_failed created_at: type: string updated_at: type: string current: type: object properties: summary: nullable: true type: string swot: nullable: true type: object properties: strengths: type: array items: type: string minLength: 1 description: 'Internal advantages of the current process — capabilities, resources, or design choices that work in its favour today. Phrase each as a short, evidence-backed statement. Example: "Bartenders know regulars by name, which keeps service personal during peak hours."' weaknesses: type: array items: type: string minLength: 1 description: 'Internal limitations of the current process — gaps, inefficiencies, or fragile assumptions visible in how it runs today. Phrase each as a short, evidence-backed statement. Example: "Manual pour times balloon during rushes because there is only one tap."' opportunities: type: array items: type: string minLength: 1 description: 'External openings the current process could exploit — adjacent automations, scale effects, or unmet needs surfaced by the captures. Example: "POS data could feed dynamic pricing for slow hours."' threats: type: array items: type: string minLength: 1 description: 'External risks that could degrade the current process — regulatory, operational, technological, or human factors visible in the captures. Example: "New ID-check legislation will require staff to interrupt every order."' required: - strengths - weaknesses - opportunities - threats additionalProperties: false required: - summary - swot additionalProperties: false proposal: nullable: true type: object properties: summary: nullable: true type: string projectedImpact: nullable: true type: string steps: type: array items: type: object properties: id: type: string title: type: string role: nullable: true type: string system: nullable: true type: string nodeType: nullable: true type: string nodeSubtype: nullable: true type: string condition: nullable: true type: string readiness: nullable: true type: string targetSteps: type: array items: type: object properties: stepId: type: string label: nullable: true type: string isDefault: type: boolean required: - stepId - label - isDefault additionalProperties: false required: - id - title - role - system - nodeType - nodeSubtype - condition - readiness - targetSteps additionalProperties: false required: - summary - projectedImpact - steps additionalProperties: false roles: type: array items: type: string systems: type: array items: type: string required: - id - name - status - created_at - updated_at - current - proposal - roles - systems additionalProperties: false total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 limit: type: integer minimum: -9007199254740991 maximum: 9007199254740991 offset: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - processes - total - limit - offset additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string required: - error additionalProperties: false summary: List Clarity Process Summaries components: schemas: ArtifactChatJsonValue: anyOf: - anyOf: - type: boolean - type: number - type: string - type: 'null' - readOnly: true type: array items: $ref: '#/components/schemas/ArtifactChatJsonValue' - type: object additionalProperties: $ref: '#/components/schemas/ArtifactChatJsonValue' securitySchemes: bearerAuth: type: http scheme: bearer description: API key authentication. Get your API key from the Duvo dashboard.