> ## Documentation Index > Fetch the complete documentation index at: https://docs.duvo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Promote Clarity Process Snapshot > Promote a draft or historic Clarity v2 snapshot to live for its kind. ## OpenAPI ````yaml /api-reference/openapi.json post /v2/clarity-v2/processes/{process_id}/snapshots/{kind}/{snapshot_id}/promote openapi: 3.0.3 info: title: Duvo Public 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 security: [] tags: - name: Runs description: Start, monitor, and manage agent runs (Runs in the Duvo UI) - name: Sandboxes description: Create sandboxes and upload files for agent runs - name: Queues description: Manage queues and their agent bindings - name: Cases description: Create, list, and manage cases and their labels within queues - name: Case Approvals description: Submit decisions on pending case approval requests issued by an agent run - name: Agents description: Create and manage agents for automation workloads - name: Revisions description: Create and manage agent revisions — the underlying Setup for an Agent - name: Agent Folders description: Organize agents into folders - name: Agent Memory description: Read an agent's memory files (the Memory feature in the Duvo UI) - name: Suggestions description: >- List, apply, and dismiss an Agent's improvement suggestions (the suggestions inbox in the Duvo UI) - name: Schedules description: List schedules configured for an agent - name: Duvo Pulse description: >- Create, list, iterate on, and delete Duvo Pulse dashboards — live, agent-generated visualizations of your Duvo data - name: Case Triggers description: >- Configure case triggers that automatically dispatch agent runs (Runs in the Duvo UI) for cases added to a queue - name: Triggers description: >- Configure event triggers that start a Run automatically when an external event fires (e.g. an email arrives, a Linear issue is created, or a file changes in Google Drive) - name: Skills description: Manage team and system skills (reusable knowledge packs). - name: Files description: Manage team files. - name: Plugins description: Discover plugins that can be referenced from a revision. - name: Organizations description: Inspect organizations you belong to and the teams within them - name: Team description: Inspect the team and members associated with the API key - name: Integrations description: Browse the team's catalog of available integration types - name: Connections description: Manage your connected integrations - name: Credentials description: >- Manage logins (domain + username + password + TOTP) used by agents to sign in to websites and desktop applications, and attach them to assignment revisions - name: Secrets description: >- Manage env-var secrets injected into runs, and attach them to assignment revisions. Only metadata is exposed; values are never returned - name: Revision Integrations description: >- Attach integrations to assignment revisions, pin specific connections, and link queues - 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}/snapshots/{kind}/{snapshot_id}/promote: post: tags: - ClarityV2 summary: Promote Clarity Process Snapshot description: Promote a draft or historic Clarity v2 snapshot to live for its kind. operationId: promoteClarityProcessSnapshot 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 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 security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: API key authentication. Get your API key from the Duvo dashboard. ````