mcp: 1.0.0
info:
  name: allsign-mcp
  version: 0.1.0
  title: AllSign MCP Server
  summary: Canonical bearer-token MCP server for AI-agent integrations.
  instructions: >
    Use resources to read canonical agreement data and the current signing
    protocol. Follow the protocol resource for the next valid signing action
    and call the tool whose name matches that action.
server:
  transport: streamable-http
  url: /mcp
security:
  - bearerAuth: []
tags:
  - name: Actors
  - name: Agreements
  - name: Comments
  - name: Contacts
  - name: Participants
  - name: Signing
  - name: Templates
resources:
  actor-self:
    uri: mcp://allsign/actors/self
    title: Actor Self
    description: Authenticated actor resource.
    mimeType: application/json
    tags:
      - Actors
    content:
      schema:
        type: object
        required:
          - actor
        properties:
          actor:
            $ref: "#/components/schemas/Actor"
  agreement:
    uri: "mcp://allsign/agreements/{agreement_ref}"
    title: Agreement
    description: Canonical agreement resource.
    mimeType: application/json
    tags:
      - Agreements
    variables:
      agreement_ref:
        description: Agreement reference.
        schema:
          $ref: "#/components/schemas/Ref"
    content:
      schema:
        type: object
        required:
          - agreement
          - readiness
        properties:
          agreement:
            $ref: "#/components/schemas/Agreement"
          readiness:
            $ref: "#/components/schemas/AgreementReadiness"
    examples:
      example:
        summary: Executed agreement
        value:
          agreement:
            ref: "a1b2c3d4-0001-4000-8000-000000000001"
            name: "PRD: Enterprise Data Export v1"
            description: null
            intent: binding
            priority: high
            status: executed
            executed_at: "2026-06-27T15:30:00Z"
            rejected_at: null
            rejected_reason: null
            requires_2fa: false
            requires_rcp: false
            sections:
              - ref: "a1b2c3d4-0011-4000-8000-000000000001"
                name: Problem Statement
                description: null
                position: 1
                terms: []
              - ref: "a1b2c3d4-0013-4000-8000-000000000001"
                name: v1 Scope
                description: null
                position: 3
                terms:
                  - ref: "a1b2c3d4-0031-4000-8000-000000000001"
                    name: "Export Formats"
                    description: "Export formats at launch: CSV and JSON. PDF export deferred to v2."
                    negotiable: true
                    locked: true
                    pending_counter_proposal: false
                    has_review_history: true
                    priority: medium
                    position: 1
            terms:
              - ref: "a1b2c3d4-0031-4000-8000-000000000001"
                name: "Export Formats"
                description: "Export formats at launch: CSV and JSON. PDF export deferred to v2."
                negotiable: true
                locked: true
                pending_counter_proposal: false
                has_review_history: true
                priority: medium
                position: 1
              - ref: "a1b2c3d4-0034-4000-8000-000000000001"
                name: "Link Validity"
                description: "Download links valid for 14 days from generation."
                negotiable: true
                locked: true
                pending_counter_proposal: false
                has_review_history: true
                priority: medium
                position: 2
              - ref: "a1b2c3d4-0063-4000-8000-000000000001"
                name: "Completion Notification"
                description: "In-app notification only for v1; email after notification redesign ships."
                negotiable: true
                locked: true
                pending_counter_proposal: false
                has_review_history: true
                priority: medium
                position: 3
          readiness:
            can_invite_signers_or_editors: true
            empty_section_count: 0
            participant_constraints:
              signer_or_editor: null
            section_count: 7
            term_count: 3
  agreement-protocol:
    uri: "mcp://allsign/agreements/{agreement_ref}/protocol"
    title: Agreement Protocol
    description: Current signing protocol resource for an agreement.
    mimeType: application/json
    tags:
      - Agreements
      - Signing
    variables:
      agreement_ref:
        description: Agreement reference.
        schema:
          $ref: "#/components/schemas/Ref"
    content:
      schema:
        type: object
        required:
          - protocol
          - readiness
        properties:
          protocol:
            $ref: "#/components/schemas/Protocol"
          readiness:
            $ref: "#/components/schemas/AgreementReadiness"
    examples:
      example:
        summary: Protocol in idle state
        value:
          protocol:
            state: idle
            action: null
          readiness:
            can_invite_signers_or_editors: true
            empty_section_count: 0
            participant_constraints:
              signer_or_editor: null
            section_count: 7
            term_count: 3
  agreement-participants:
    uri: "mcp://allsign/agreements/{agreement_ref}/participants"
    title: Agreement Participants
    description: Agreement participants collection resource.
    mimeType: application/json
    tags:
      - Agreements
      - Participants
    variables:
      agreement_ref:
        description: Agreement reference.
        schema:
          $ref: "#/components/schemas/Ref"
    content:
      schema:
        allOf:
          - $ref: "#/components/schemas/Pagination"
          - type: object
            required:
              - participants
            properties:
              participants:
                type: array
                items:
                  $ref: "#/components/schemas/Participant"
  agreement-comments:
    uri: "mcp://allsign/agreements/{agreement_ref}/comments"
    title: Agreement Comments
    description: Agreement comments collection resource.
    mimeType: application/json
    tags:
      - Agreements
      - Comments
    variables:
      agreement_ref:
        description: Agreement reference.
        schema:
          $ref: "#/components/schemas/Ref"
    content:
      schema:
        allOf:
          - $ref: "#/components/schemas/Pagination"
          - type: object
            required:
              - comments
            properties:
              comments:
                type: array
                items:
                  $ref: "#/components/schemas/Comment"
  section-comments:
    uri: "mcp://allsign/sections/{section_ref}/comments"
    title: Section Comments
    description: Section comments collection resource.
    mimeType: application/json
    tags:
      - Agreements
      - Comments
    variables:
      section_ref:
        description: Section reference.
        schema:
          $ref: "#/components/schemas/Ref"
    content:
      schema:
        allOf:
          - $ref: "#/components/schemas/Pagination"
          - type: object
            required:
              - comments
            properties:
              comments:
                type: array
                items:
                  $ref: "#/components/schemas/Comment"
  term-comments:
    uri: "mcp://allsign/terms/{term_ref}/comments"
    title: Term Comments
    description: Term comments collection resource.
    mimeType: application/json
    tags:
      - Agreements
      - Comments
    variables:
      term_ref:
        description: Term reference.
        schema:
          $ref: "#/components/schemas/Ref"
    content:
      schema:
        allOf:
          - $ref: "#/components/schemas/Pagination"
          - type: object
            required:
              - comments
            properties:
              comments:
                type: array
                items:
                  $ref: "#/components/schemas/Comment"
  term-decisions:
    uri: "mcp://allsign/terms/{term_ref}/decisions"
    title: Term Decisions
    description: Term decisions collection resource.
    mimeType: application/json
    tags:
      - Agreements
    variables:
      term_ref:
        description: Term reference.
        schema:
          $ref: "#/components/schemas/Ref"
    content:
      schema:
        allOf:
          - $ref: "#/components/schemas/Pagination"
          - type: object
            required:
              - decisions
            properties:
              decisions:
                type: array
                items:
                  $ref: "#/components/schemas/Decision"
  term-revisions:
    uri: "mcp://allsign/terms/{term_ref}/revisions"
    title: Term Revisions
    description: Term revisions collection resource.
    mimeType: application/json
    tags:
      - Agreements
    variables:
      term_ref:
        description: Term reference.
        schema:
          $ref: "#/components/schemas/Ref"
    content:
      schema:
        allOf:
          - $ref: "#/components/schemas/Pagination"
          - type: object
            required:
              - revisions
            properties:
              revisions:
                type: array
                items:
                  $ref: "#/components/schemas/Revision"
  contact:
    uri: "mcp://allsign/contacts/{contact_ref}"
    title: Contact
    description: Canonical contact resource.
    mimeType: application/json
    tags:
      - Contacts
    variables:
      contact_ref:
        description: Contact reference.
        schema:
          $ref: "#/components/schemas/Ref"
    content:
      schema:
        type: object
        required:
          - contact
        properties:
          contact:
            $ref: "#/components/schemas/Contact"
  template:
    uri: "mcp://allsign/templates/{template_ref}"
    title: Template
    description: Canonical template resource.
    mimeType: application/json
    tags:
      - Templates
    variables:
      template_ref:
        description: Template reference.
        schema:
          $ref: "#/components/schemas/Ref"
    content:
      schema:
        type: object
        required:
          - template
        properties:
          template:
            $ref: "#/components/schemas/Template"
  template-content:
    uri: "mcp://allsign/templates/{template_ref}/content"
    title: Template Content
    description: Canonical template agreement content.
    mimeType: application/json
    tags:
      - Templates
    variables:
      template_ref:
        description: Template reference.
        schema:
          $ref: "#/components/schemas/Ref"
    content:
      schema:
        type: object
        required:
          - content
        properties:
          content:
            $ref: "#/components/schemas/CanonicalDocument"
tools:
  list_agreements:
    description: Lists accessible agreements with optional search and pagination.
    tags:
      - Agreements
    inputSchema:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
          description: Result page number.
        page_size:
          type: integer
          minimum: 1
          maximum: 100
          description: Result page size.
        search:
          type: string
          description: Optional agreement search string.
    outputSchema:
      type: object
      required:
        - agreements
        - page
        - page_size
        - total_pages
        - total_records
      properties:
        agreements:
          type: array
          items:
            $ref: "#/components/schemas/AgreementPartial"
        page:
          type: integer
        page_size:
          type: integer
        total_pages:
          type: integer
        total_records:
          type: integer
    examples:
      example:
        summary: Paginated list of agreements
        input:
          page: 1
          page_size: 20
        output:
          agreements:
            - ref: "a1b2c3d4-0001-4000-8000-000000000001"
              name: "PRD: Enterprise Data Export v1"
              description: null
              intent: binding
              status: executed
          page: 1
          page_size: 20
          total_pages: 1
          total_records: 1
  create_agreement:
    description: Creates an agreement owned by the authenticated actor.
    tags:
      - Agreements
    inputSchema:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Agreement name.
        description:
          type:
            - string
            - "null"
          description: Optional agreement description.
        intent:
          type: string
          enum: [binding, nonbinding]
          description: Agreement intent.
        priority:
          type: string
          enum: [low, medium, high, urgent]
          description: Agreement priority.
        requires_2fa:
          type: integer
          enum: [0, 1]
          description: Whether signing requires verification.
        requires_rcp:
          type: integer
          enum: [0, 1]
          description: Whether signing requires reciprocal confirmation.
    outputSchema:
      type: object
      required:
        - agreement
      properties:
        agreement:
          $ref: "#/components/schemas/Agreement"
    examples:
      example:
        summary: Create a binding agreement
        input:
          name: "PRD: Enterprise Data Export v1"
          intent: binding
          priority: high
        output:
          agreement:
            ref: "a1b2c3d4-0001-4000-8000-000000000001"
            name: "PRD: Enterprise Data Export v1"
            description: null
            intent: binding
            priority: high
            status: draft
            executed_at: null
            rejected_at: null
            rejected_reason: null
            requires_2fa: false
            requires_rcp: false
            sections: []
            terms: []
  update_agreement:
    description: Updates an accessible agreement.
    tags:
      - Agreements
    inputSchema:
      type: object
      required:
        - agreement_ref
      properties:
        agreement_ref:
          $ref: "#/components/schemas/Ref"
          description: Agreement reference.
        name:
          type: string
          description: Agreement name.
        description:
          type:
            - string
            - "null"
          description: Optional agreement description.
        intent:
          type: string
          enum: [binding, nonbinding]
          description: Agreement intent.
        priority:
          type: string
          enum: [low, medium, high, urgent]
          description: Agreement priority.
        requires_2fa:
          type: integer
          enum: [0, 1]
          description: Whether signing requires verification.
        requires_rcp:
          type: integer
          enum: [0, 1]
          description: Whether signing requires reciprocal confirmation.
    outputSchema:
      type: object
      required:
        - agreement
      properties:
        agreement:
          $ref: "#/components/schemas/Agreement"
  delete_agreement:
    description: Deletes an agreement owned by the authenticated actor.
    tags:
      - Agreements
    inputSchema:
      type: object
      required:
        - agreement_ref
      properties:
        agreement_ref:
          $ref: "#/components/schemas/Ref"
          description: Agreement reference.
    outputSchema:
      type: object
      required:
        - agreement
      properties:
        agreement:
          $ref: "#/components/schemas/Agreement"
  create_section:
    description: Creates a section within an owned agreement.
    tags:
      - Agreements
    inputSchema:
      type: object
      required:
        - agreement_ref
        - name
      properties:
        agreement_ref:
          $ref: "#/components/schemas/Ref"
          description: Agreement reference.
        name:
          type: string
          description: Section name.
        description:
          type:
            - string
            - "null"
          description: Optional section description.
        position:
          type: integer
          minimum: 0
          description: Optional section position.
    outputSchema:
      type: object
      required:
        - section
      properties:
        section:
          $ref: "#/components/schemas/Section"
    examples:
      example:
        summary: Create a section
        input:
          agreement_ref: "a1b2c3d4-0001-4000-8000-000000000001"
          name: v1 Scope
          position: 3
        output:
          section:
            ref: "a1b2c3d4-0013-4000-8000-000000000001"
            name: v1 Scope
            description: null
            position: 3
            terms: []
  update_section:
    description: Updates a section within an owned agreement.
    tags:
      - Agreements
    inputSchema:
      type: object
      required:
        - section_ref
        - name
      properties:
        section_ref:
          $ref: "#/components/schemas/Ref"
          description: Section reference.
        name:
          type: string
          description: Section name.
        description:
          type:
            - string
            - "null"
          description: Optional section description.
        position:
          type: integer
          minimum: 0
          description: Optional section position.
    outputSchema:
      type: object
      required:
        - section
      properties:
        section:
          $ref: "#/components/schemas/Section"
  delete_section:
    description: Deletes a section from an owned agreement.
    tags:
      - Agreements
    inputSchema:
      type: object
      required:
        - section_ref
      properties:
        section_ref:
          $ref: "#/components/schemas/Ref"
          description: Section reference.
    outputSchema:
      type: object
      required:
        - section
      properties:
        section:
          $ref: "#/components/schemas/Section"
  create_term:
    description: Creates a term within an owned agreement.
    tags:
      - Agreements
    inputSchema:
      type: object
      required:
        - agreement_ref
        - name
      properties:
        agreement_ref:
          $ref: "#/components/schemas/Ref"
          description: Agreement reference.
        name:
          type: string
          description: Term name.
        description:
          type:
            - string
            - "null"
          description: Optional term description.
        negotiable:
          type: boolean
          description: Whether the term is negotiable.
        position:
          type: integer
          minimum: 0
          description: Optional term position.
        priority:
          type: string
          enum: [low, medium, high, urgent]
          description: Term priority.
        section_ref:
          $ref: "#/components/schemas/Ref"
          description: Optional section reference.
    outputSchema:
      type: object
      required:
        - term
      properties:
        term:
          $ref: "#/components/schemas/Term"
    examples:
      example:
        summary: Create a term within a section
        input:
          agreement_ref: "a1b2c3d4-0001-4000-8000-000000000001"
          name: "Export Formats"
          description: "Export formats supported at launch: CSV, JSON, and PDF."
          negotiable: true
          section_ref: "a1b2c3d4-0013-4000-8000-000000000001"
          priority: medium
          position: 1
        output:
          term:
            ref: "a1b2c3d4-0031-4000-8000-000000000001"
            name: "Export Formats"
            description: "Export formats supported at launch: CSV, JSON, and PDF."
            negotiable: true
            locked: false
            pending_counter_proposal: false
            has_review_history: false
            priority: medium
            position: 1
  update_term:
    description: Updates a term within an owned agreement.
    tags:
      - Agreements
    inputSchema:
      type: object
      required:
        - term_ref
        - name
      properties:
        term_ref:
          $ref: "#/components/schemas/Ref"
          description: Term reference.
        name:
          type: string
          description: Term name.
        description:
          type:
            - string
            - "null"
          description: Optional term description.
        negotiable:
          type: boolean
          description: Whether the term is negotiable.
        position:
          type: integer
          minimum: 0
          description: Optional term position.
        priority:
          type: string
          enum: [low, medium, high, urgent]
          description: Term priority.
    outputSchema:
      type: object
      required:
        - term
      properties:
        term:
          $ref: "#/components/schemas/Term"
  delete_term:
    description: Deletes a term from an owned agreement.
    tags:
      - Agreements
    inputSchema:
      type: object
      required:
        - term_ref
      properties:
        term_ref:
          $ref: "#/components/schemas/Ref"
          description: Term reference.
    outputSchema:
      type: object
      required:
        - term
      properties:
        term:
          $ref: "#/components/schemas/Term"
  list_templates:
    description: Lists owned templates with optional search and pagination.
    tags:
      - Templates
    inputSchema:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
          description: Result page number.
        page_size:
          type: integer
          minimum: 1
          maximum: 100
          description: Result page size.
        search:
          type: string
          description: Optional template search string.
    outputSchema:
      type: object
      required:
        - templates
        - page
        - page_size
        - total_pages
        - total_records
      properties:
        templates:
          type: array
          items:
            $ref: "#/components/schemas/TemplatePartial"
        page:
          type: integer
        page_size:
          type: integer
        total_pages:
          type: integer
        total_records:
          type: integer
  create_template:
    description: Creates a template owned by the authenticated actor.
    tags:
      - Templates
    inputSchema:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Template name.
        description:
          type:
            - string
            - "null"
          description: Optional template description.
        intent:
          type: string
          enum: [binding, nonbinding]
          description: Template intent.
        priority:
          type: string
          enum: [low, medium, high, urgent]
          description: Template priority.
        requires_2fa:
          type: integer
          enum: [0, 1]
          description: Whether signing requires verification.
        requires_rcp:
          type: integer
          enum: [0, 1]
          description: Whether signing requires reciprocal confirmation.
    outputSchema:
      type: object
      required:
        - template
      properties:
        template:
          $ref: "#/components/schemas/Template"
  update_template:
    description: Updates a template owned by the authenticated actor.
    tags:
      - Templates
    inputSchema:
      type: object
      required:
        - template_ref
      properties:
        template_ref:
          $ref: "#/components/schemas/Ref"
          description: Template reference.
        name:
          type: string
          description: Template name.
        description:
          type:
            - string
            - "null"
          description: Optional template description.
        intent:
          type: string
          enum: [binding, nonbinding]
          description: Template intent.
        priority:
          type: string
          enum: [low, medium, high, urgent]
          description: Template priority.
        requires_2fa:
          type: integer
          enum: [0, 1]
          description: Whether signing requires verification.
        requires_rcp:
          type: integer
          enum: [0, 1]
          description: Whether signing requires reciprocal confirmation.
    outputSchema:
      type: object
      required:
        - template
      properties:
        template:
          $ref: "#/components/schemas/Template"
  delete_template:
    description: Deletes a template owned by the authenticated actor.
    tags:
      - Templates
    inputSchema:
      type: object
      required:
        - template_ref
      properties:
        template_ref:
          $ref: "#/components/schemas/Ref"
          description: Template reference.
    outputSchema:
      type: object
      required:
        - template
      properties:
        template:
          $ref: "#/components/schemas/Template"
  list_contacts:
    description: Lists owned contacts with optional search and pagination.
    tags:
      - Contacts
    inputSchema:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
          description: Result page number.
        page_size:
          type: integer
          minimum: 1
          maximum: 100
          description: Result page size.
        search:
          type: string
          description: Optional contact search string.
    outputSchema:
      type: object
      required:
        - contacts
        - page
        - page_size
        - total_pages
        - total_records
      properties:
        contacts:
          type: array
          items:
            $ref: "#/components/schemas/Contact"
        page:
          type: integer
        page_size:
          type: integer
        total_pages:
          type: integer
        total_records:
          type: integer
  create_contact:
    description: Creates a contact owned by the authenticated actor.
    tags:
      - Contacts
    inputSchema:
      type: object
      required:
        - email
        - name
      properties:
        email:
          type: string
          format: email
          description: Contact email address.
        name:
          type: string
          description: Contact display name.
        notes:
          type:
            - string
            - "null"
          description: Optional notes.
        organization:
          type:
            - string
            - "null"
          description: Optional organization.
        phone:
          type:
            - string
            - "null"
          description: Optional phone number.
    outputSchema:
      type: object
      required:
        - contact
      properties:
        contact:
          $ref: "#/components/schemas/Contact"
  update_contact:
    description: Updates a contact owned by the authenticated actor.
    tags:
      - Contacts
    inputSchema:
      type: object
      required:
        - contact_ref
      properties:
        contact_ref:
          $ref: "#/components/schemas/Ref"
          description: Contact reference.
        email:
          type: string
          format: email
          description: Contact email address.
        name:
          type: string
          description: Contact display name.
        notes:
          type:
            - string
            - "null"
          description: Optional notes.
        organization:
          type:
            - string
            - "null"
          description: Optional organization.
        phone:
          type:
            - string
            - "null"
          description: Optional phone number.
    outputSchema:
      type: object
      required:
        - contact
      properties:
        contact:
          $ref: "#/components/schemas/Contact"
  delete_contact:
    description: Deletes a contact owned by the authenticated actor.
    tags:
      - Contacts
    inputSchema:
      type: object
      required:
        - contact_ref
      properties:
        contact_ref:
          $ref: "#/components/schemas/Ref"
          description: Contact reference.
    outputSchema:
      type: object
      required:
        - contact
      properties:
        contact:
          $ref: "#/components/schemas/Contact"
  list_participants:
    description: Lists agreement participants with pagination.
    tags:
      - Participants
    inputSchema:
      type: object
      required:
        - agreement_ref
      properties:
        agreement_ref:
          $ref: "#/components/schemas/Ref"
          description: Agreement reference.
        page:
          type: integer
          minimum: 1
          description: Result page number.
        page_size:
          type: integer
          minimum: 1
          maximum: 100
          description: Result page size.
    outputSchema:
      type: object
      required:
        - participants
        - page
        - page_size
        - total_pages
        - total_records
      properties:
        participants:
          type: array
          items:
            $ref: "#/components/schemas/Participant"
        page:
          type: integer
        page_size:
          type: integer
        total_pages:
          type: integer
        total_records:
          type: integer
  invite_participant:
    description: Invites a participant to an agreement.
    tags:
      - Participants
    inputSchema:
      type: object
      required:
        - agreement_ref
        - type
      properties:
        agreement_ref:
          $ref: "#/components/schemas/Ref"
          description: Agreement reference.
        type:
          type: string
          enum: [commentor, editor, signer, viewer]
          description: Participant role.
        agent_ref:
          type:
            - string
            - "null"
          format: uuid
          description: Optional agent actor reference.
        email:
          type:
            - string
            - "null"
          format: email
          description: Invitee email address.
        name:
          type:
            - string
            - "null"
          description: Invitee display name.
    outputSchema:
      type: object
      required:
        - participant
      properties:
        invitation:
          anyOf:
            - $ref: "#/components/schemas/InvitationPartial"
            - type: "null"
        participant:
          $ref: "#/components/schemas/Participant"
    examples:
      example:
        summary: Invite a participant as signer
        input:
          agreement_ref: "a1b2c3d4-0001-4000-8000-000000000001"
          type: signer
          email: marcus.webb@lumen.app
          name: Marcus Webb
        output:
          participant:
            ref: "a1b2c3d4-0102-4000-8000-000000000001"
            name: Marcus Webb
            email: marcus.webb@lumen.app
            type: signer
            active: false
            avatar_url: null
            actor: null
          invitation:
            ref: "a1b2c3d4-0501-4000-8000-000000000001"
            email: marcus.webb@lumen.app
            type: signer
  update_participant:
    description: Updates a participant role.
    tags:
      - Participants
    inputSchema:
      type: object
      required:
        - participant_ref
        - type
      properties:
        participant_ref:
          $ref: "#/components/schemas/Ref"
          description: Participant reference.
        type:
          type: string
          enum: [commentor, editor, signer, viewer]
          description: Participant role.
    outputSchema:
      type: object
      required:
        - participant
      properties:
        participant:
          $ref: "#/components/schemas/Participant"
  delete_participant:
    description: Deletes a participant from an agreement.
    tags:
      - Participants
    inputSchema:
      type: object
      required:
        - participant_ref
      properties:
        participant_ref:
          $ref: "#/components/schemas/Ref"
          description: Participant reference.
    outputSchema:
      type: object
      required:
        - participant
      properties:
        participant:
          $ref: "#/components/schemas/Participant"
  self_join_agreement:
    description: Adds the authenticated actor to an agreement as an editor or signer.
    tags:
      - Participants
    inputSchema:
      type: object
      required:
        - agreement_ref
      properties:
        agreement_ref:
          $ref: "#/components/schemas/Ref"
          description: Agreement reference.
        type:
          type: string
          enum: [editor, signer]
          description: Self-join role.
    outputSchema:
      type: object
      required:
        - participant
      properties:
        participant:
          $ref: "#/components/schemas/Participant"
  accept_invitation:
    description: Accepts an invitation for the authenticated actor.
    tags:
      - Participants
    inputSchema:
      type: object
      required:
        - invitation_ref
      properties:
        invitation_ref:
          $ref: "#/components/schemas/Ref"
          description: Invitation reference.
    outputSchema:
      type: object
      required:
        - participant
      properties:
        participant:
          $ref: "#/components/schemas/Participant"
    examples:
      example:
        summary: Accepted participant invitation
        input:
          invitation_ref: "a1b2c3d4-0501-4000-8000-000000000001"
        output:
          participant:
            ref: "a1b2c3d4-0102-4000-8000-000000000001"
            name: Marcus Webb
            email: marcus.webb@lumen.app
            type: signer
            active: true
            avatar_url: null
            actor:
              ref: "a1b2c3d4-0602-4000-8000-000000000001"
              kind: user
  reject_invitation:
    description: Rejects an invitation for the authenticated actor.
    tags:
      - Participants
    inputSchema:
      type: object
      required:
        - invitation_ref
      properties:
        invitation_ref:
          $ref: "#/components/schemas/Ref"
          description: Invitation reference.
    outputSchema:
      type: object
      required:
        - invitation
      properties:
        invitation:
          $ref: "#/components/schemas/InvitationReference"
  create_agreement_comment:
    description: Creates a comment on an agreement.
    tags:
      - Comments
    inputSchema:
      type: object
      required:
        - agreement_ref
        - content
      properties:
        agreement_ref:
          $ref: "#/components/schemas/Ref"
          description: Agreement reference.
        content:
          type: string
          description: Comment content.
    outputSchema:
      type: object
      required:
        - comment
      properties:
        comment:
          $ref: "#/components/schemas/Comment"
  create_section_comment:
    description: Creates a comment on a section.
    tags:
      - Comments
    inputSchema:
      type: object
      required:
        - section_ref
        - content
      properties:
        section_ref:
          $ref: "#/components/schemas/Ref"
          description: Section reference.
        content:
          type: string
          description: Comment content.
    outputSchema:
      type: object
      required:
        - comment
      properties:
        comment:
          $ref: "#/components/schemas/Comment"
  create_term_comment:
    description: Creates a comment on a term.
    tags:
      - Comments
    inputSchema:
      type: object
      required:
        - term_ref
        - content
      properties:
        term_ref:
          $ref: "#/components/schemas/Ref"
          description: Term reference.
        content:
          type: string
          description: Comment content.
        on_revision:
          type: boolean
          description: Whether the comment applies to the current revision.
    outputSchema:
      type: object
      required:
        - comment
      properties:
        comment:
          $ref: "#/components/schemas/Comment"
  update_comment:
    description: Updates a comment.
    tags:
      - Comments
    inputSchema:
      type: object
      required:
        - comment_ref
        - content
      properties:
        comment_ref:
          $ref: "#/components/schemas/Ref"
          description: Comment reference.
        content:
          type: string
          description: Comment content.
        on_revision:
          type: boolean
          description: Whether the comment applies to the current revision.
    outputSchema:
      type: object
      required:
        - comment
      properties:
        comment:
          $ref: "#/components/schemas/Comment"
  delete_comment:
    description: Deletes a comment.
    tags:
      - Comments
    inputSchema:
      type: object
      required:
        - comment_ref
      properties:
        comment_ref:
          $ref: "#/components/schemas/Ref"
          description: Comment reference.
    outputSchema:
      type: object
      required:
        - comment
      properties:
        comment:
          $ref: "#/components/schemas/Comment"
  create_revision:
    description: Creates a revision proposal for a term.
    tags:
      - Agreements
    inputSchema:
      type: object
      required:
        - term_ref
        - description
      properties:
        term_ref:
          $ref: "#/components/schemas/Ref"
          description: Term reference.
        description:
          type: string
          description: Proposed term description.
        name:
          type:
            - string
            - "null"
          description: Optional proposed term name.
        remarks:
          type:
            - string
            - "null"
          description: Optional revision remarks.
    outputSchema:
      type: object
      required:
        - decision
        - revision
      properties:
        decision:
          $ref: "#/components/schemas/Decision"
        revision:
          $ref: "#/components/schemas/Revision"
    examples:
      example:
        summary: Propose a term revision
        input:
          term_ref: "a1b2c3d4-0031-4000-8000-000000000001"
          description: "Export formats at launch: CSV and JSON. PDF export deferred to v2."
          remarks: "PDF export is out of scope for v1; deferring to reduce launch risk."
        output:
          revision:
            ref: "a1b2c3d4-0301-4000-8000-000000000001"
            number: 1
            description: "Export formats at launch: CSV and JSON. PDF export deferred to v2."
            name: null
            latest: true
            created_at: "2026-06-27T10:30:00Z"
            actor:
              ref: "a1b2c3d4-0602-4000-8000-000000000001"
              name: Marcus Webb
            decisions: []
          decision:
            ref: "a1b2c3d4-0401-4000-8000-000000000001"
            status: accepted
            remarks: "PDF export is out of scope for v1; deferring to reduce launch risk."
            created_at: "2026-06-27T10:30:00Z"
            actor:
              ref: "a1b2c3d4-0602-4000-8000-000000000001"
              name: Marcus Webb
              avatar_url: null
            revision:
              ref: "a1b2c3d4-0301-4000-8000-000000000001"
  create_decision:
    description: Creates a decision for a term revision workflow.
    tags:
      - Agreements
    inputSchema:
      type: object
      required:
        - term_ref
        - status
      properties:
        term_ref:
          $ref: "#/components/schemas/Ref"
          description: Term reference.
        status:
          type: string
          enum: [accepted, rejected]
          description: Decision status.
        proposed_description:
          type:
            - string
            - "null"
          description: Optional proposed term description.
        proposed_name:
          type:
            - string
            - "null"
          description: Optional proposed term name.
        remarks:
          type:
            - string
            - "null"
          description: Optional decision remarks.
        supersedes_decision_ref:
          type:
            - string
            - "null"
          format: uuid
          description: Optional superseded decision reference.
    outputSchema:
      type: object
      required:
        - decision
      properties:
        decision:
          $ref: "#/components/schemas/Decision"
        proposal_decision:
          anyOf:
            - $ref: "#/components/schemas/Decision"
            - type: "null"
        revision:
          anyOf:
            - $ref: "#/components/schemas/Revision"
            - type: "null"
    examples:
      example:
        summary: Accept the current term revision
        input:
          term_ref: "a1b2c3d4-0031-4000-8000-000000000001"
          status: accepted
          remarks: "Agreed. Scoping to CSV and JSON aligns with v1 delivery timeline."
        output:
          decision:
            ref: "a1b2c3d4-0401-4000-8000-000000000001"
            status: accepted
            remarks: "Agreed. Scoping to CSV and JSON aligns with v1 delivery timeline."
            created_at: "2026-06-27T11:00:00Z"
            actor:
              ref: "a1b2c3d4-0601-4000-8000-000000000001"
              name: Priya Nair
              avatar_url: null
            revision:
              ref: "a1b2c3d4-0301-4000-8000-000000000001"
          proposal_decision: null
          revision: null
  create_authentication:
    description: Creates the current signing authentication transition for an agreement.
    tags:
      - Signing
    inputSchema:
      type: object
      required:
        - agreement_ref
      properties:
        agreement_ref:
          $ref: "#/components/schemas/Ref"
          description: Agreement reference.
        password:
          type: string
          description: Current account password when password-based reauthentication is required.
    outputSchema:
      type: object
      properties:
        session:
          $ref: "#/components/schemas/Session"
        verification:
          $ref: "#/components/schemas/SignatureVerification"
  create_rcp_assignment:
    description: Creates the reciprocal confirmation requirements for an agreement.
    tags:
      - Signing
    inputSchema:
      type: object
      required:
        - agreement_ref
      properties:
        agreement_ref:
          $ref: "#/components/schemas/Ref"
          description: Agreement reference.
    outputSchema:
      type: object
      required:
        - rcp
      properties:
        rcp:
          $ref: "#/components/schemas/RcpContext"
  create_rcp_confirmation:
    description: Confirms the actor's current reciprocal confirmation requirement.
    tags:
      - Signing
    inputSchema:
      type: object
      required:
        - agreement_ref
        - attested
        - code
        - token
      properties:
        agreement_ref:
          $ref: "#/components/schemas/Ref"
          description: Agreement reference.
        attested:
          type: boolean
          description: Whether the actor attests to the reciprocal confirmation.
        code:
          type: string
          description: Remote confirmation code.
        token:
          type: string
          description: Remote confirmation token.
    outputSchema:
      type: object
      required:
        - challenge
        - rcp
      properties:
        challenge:
          $ref: "#/components/schemas/RcpChallenge"
        rcp:
          $ref: "#/components/schemas/RcpContext"
  create_signature:
    description: Creates the actor's signature for an agreement.
    tags:
      - Signing
    inputSchema:
      type: object
      required:
        - agreement_ref
      properties:
        agreement_ref:
          $ref: "#/components/schemas/Ref"
          description: Agreement reference.
        legal_affirmed:
          type: boolean
          description: Whether the actor legally affirms the agreement before signing.
    outputSchema:
      type: object
      required:
        - agreement
      properties:
        agreement:
          $ref: "#/components/schemas/Agreement"
        signature:
          $ref: "#/components/schemas/Signature"
        verification:
          $ref: "#/components/schemas/SignatureVerification"
    examples:
      example:
        summary: Sign an agreement
        input:
          agreement_ref: "a1b2c3d4-0001-4000-8000-000000000001"
          legal_affirmed: true
        output:
          agreement:
            ref: "a1b2c3d4-0001-4000-8000-000000000001"
            name: "PRD: Enterprise Data Export v1"
            status: signing
            intent: binding
            priority: high
            executed_at: null
            rejected_at: null
            rejected_reason: null
            requires_2fa: false
            requires_rcp: false
            description: null
            sections: []
            terms: []
          signature:
            ref: "a1b2c3d4-0701-4000-8000-000000000001"
            created_at: "2026-06-27T14:00:00Z"
            requires_2fa: false
          verification: null
  create_verification_confirmation:
    description: Completes the current signing-related verification challenge.
    tags:
      - Signing
    inputSchema:
      type: object
      required:
        - verification_ref
        - code
      properties:
        verification_ref:
          $ref: "#/components/schemas/Ref"
          description: Verification reference.
        code:
          type: string
          description: Verification code.
    outputSchema:
      type: object
      properties:
        session:
          $ref: "#/components/schemas/Session"
        agreement:
          $ref: "#/components/schemas/Agreement"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Bearer
  schemas:
    Ref:
      type: string
      format: uuid
      description: Public stable resource reference.
    Actor:
      type: object
      description: Canonical actor identity summary for bearer authentication.
      required:
        - avatar_url
        - email
        - family_name
        - given_name
        - job_title
        - kind
        - name
        - organization
        - ref
      properties:
        avatar_url:
          type:
            - string
            - "null"
        email:
          type:
            - string
            - "null"
          format: email
        family_name:
          type:
            - string
            - "null"
        given_name:
          type:
            - string
            - "null"
        job_title:
          type:
            - string
            - "null"
        kind:
          type: string
        name:
          type: string
        organization:
          type:
            - string
            - "null"
        ref:
          $ref: "#/components/schemas/Ref"
    Contact:
      type: object
      description: Canonical contact resource.
      required:
        - avatar_url
        - email
        - family_name
        - given_name
        - name
        - notes
        - organization
        - phone
        - ref
      properties:
        avatar_url:
          type:
            - string
            - "null"
        email:
          type: string
          format: email
        family_name:
          type:
            - string
            - "null"
        given_name:
          type: string
        name:
          type: string
        notes:
          type:
            - string
            - "null"
        organization:
          type:
            - string
            - "null"
        phone:
          type:
            - string
            - "null"
        ref:
          $ref: "#/components/schemas/Ref"
    AgreementPartial:
      type: object
      description: Canonical agreement summary.
      required:
        - description
        - intent
        - name
        - ref
        - status
      properties:
        description:
          type:
            - string
            - "null"
        intent:
          type: string
        name:
          type: string
        ref:
          $ref: "#/components/schemas/Ref"
        status:
          type: string
    Agreement:
      type: object
      description: Canonical agreement resource.
      required:
        - description
        - executed_at
        - intent
        - name
        - priority
        - rejected_at
        - rejected_reason
        - ref
        - requires_2fa
        - requires_rcp
        - sections
        - status
        - terms
      properties:
        description:
          type:
            - string
            - "null"
        executed_at:
          type:
            - string
            - "null"
          format: date-time
        intent:
          type: string
        name:
          type: string
        priority:
          type: string
        rejected_at:
          type:
            - string
            - "null"
          format: date-time
        rejected_reason:
          type:
            - string
            - "null"
        ref:
          $ref: "#/components/schemas/Ref"
        requires_2fa:
          type: boolean
        requires_rcp:
          type: boolean
        sections:
          type: array
          items:
            $ref: "#/components/schemas/Section"
        status:
          type: string
        terms:
          type: array
          items:
            $ref: "#/components/schemas/Term"
    AgreementReadiness:
      type: object
      description: Structural readiness state of an agreement for participant invitation.
      required:
        - can_invite_signers_or_editors
        - empty_section_count
        - participant_constraints
        - section_count
        - term_count
      properties:
        can_invite_signers_or_editors:
          type: boolean
        empty_section_count:
          type: integer
        participant_constraints:
          type: object
          required:
            - signer_or_editor
          properties:
            signer_or_editor:
              type:
                - string
                - "null"
        section_count:
          type: integer
        term_count:
          type: integer
    Section:
      type: object
      description: Canonical section resource.
      required:
        - description
        - name
        - position
        - ref
        - terms
      properties:
        description:
          type:
            - string
            - "null"
        name:
          type: string
        position:
          type:
            - integer
            - "null"
        ref:
          $ref: "#/components/schemas/Ref"
        terms:
          type: array
          items:
            $ref: "#/components/schemas/Term"
    Term:
      type: object
      description: Canonical term resource.
      required:
        - description
        - has_review_history
        - locked
        - name
        - negotiable
        - pending_counter_proposal
        - position
        - priority
        - ref
      properties:
        description:
          type:
            - string
            - "null"
        has_review_history:
          type: boolean
        locked:
          type: boolean
        name:
          type: string
        negotiable:
          type: boolean
        pending_counter_proposal:
          type: boolean
        position:
          type:
            - integer
            - "null"
        priority:
          type: string
        ref:
          $ref: "#/components/schemas/Ref"
    CommentActor:
      type: object
      description: Actor identity attached to a comment.
      required:
        - avatar_url
        - name
        - ref
      properties:
        avatar_url:
          type:
            - string
            - "null"
        name:
          type: string
        ref:
          type:
            - string
            - "null"
          format: uuid
    CommentRevision:
      type: object
      description: Revision reference attached to a comment.
      required:
        - latest
        - ref
      properties:
        latest:
          type: boolean
        ref:
          type:
            - string
            - "null"
          format: uuid
    CommentResourceRef:
      type: object
      description: Nested resource reference attached to a comment.
      required:
        - ref
      properties:
        ref:
          type:
            - string
            - "null"
          format: uuid
    Comment:
      type: object
      description: Canonical comment resource.
      required:
        - actor
        - content
        - created_at
        - on_revision
        - ref
        - revision
        - section
        - term
      properties:
        actor:
          $ref: "#/components/schemas/CommentActor"
        content:
          type: string
        created_at:
          type: string
          format: date-time
        on_revision:
          type: boolean
        ref:
          $ref: "#/components/schemas/Ref"
        revision:
          anyOf:
            - $ref: "#/components/schemas/CommentRevision"
            - type: "null"
        section:
          anyOf:
            - $ref: "#/components/schemas/CommentResourceRef"
            - type: "null"
        term:
          anyOf:
            - $ref: "#/components/schemas/CommentResourceRef"
            - type: "null"
    DecisionActor:
      type: object
      description: Actor identity attached to a decision.
      required:
        - avatar_url
        - name
        - ref
      properties:
        avatar_url:
          type:
            - string
            - "null"
        name:
          type: string
        ref:
          type:
            - string
            - "null"
          format: uuid
    DecisionRevision:
      type: object
      description: Revision reference attached to a decision.
      required:
        - ref
      properties:
        ref:
          $ref: "#/components/schemas/Ref"
    Decision:
      type: object
      description: Canonical decision resource.
      required:
        - actor
        - created_at
        - ref
        - remarks
        - revision
        - status
      properties:
        actor:
          anyOf:
            - $ref: "#/components/schemas/DecisionActor"
            - type: "null"
        created_at:
          type: string
          format: date-time
        ref:
          $ref: "#/components/schemas/Ref"
        remarks:
          type:
            - string
            - "null"
        revision:
          anyOf:
            - $ref: "#/components/schemas/DecisionRevision"
            - type: "null"
        status:
          type: string
          enum: [accepted, rejected]
    RevisionActor:
      type: object
      description: Actor identity attached to a revision.
      required:
        - name
        - ref
      properties:
        name:
          type: string
        ref:
          type:
            - string
            - "null"
          format: uuid
    Revision:
      type: object
      description: Canonical revision resource.
      required:
        - actor
        - created_at
        - decisions
        - description
        - latest
        - name
        - number
        - ref
      properties:
        actor:
          anyOf:
            - $ref: "#/components/schemas/RevisionActor"
            - type: "null"
        created_at:
          type: string
          format: date-time
        decisions:
          type: array
          items:
            $ref: "#/components/schemas/Decision"
        description:
          type:
            - string
            - "null"
        latest:
          type: boolean
        name:
          type:
            - string
            - "null"
        number:
          type: integer
        ref:
          $ref: "#/components/schemas/Ref"
    TemplatePartial:
      type: object
      description: Canonical template summary.
      required:
        - description
        - intent
        - name
        - ref
        - status
      properties:
        description:
          type:
            - string
            - "null"
        intent:
          type: string
        name:
          type: string
        ref:
          $ref: "#/components/schemas/Ref"
        status:
          type: string
    Template:
      type: object
      description: Canonical template resource.
      required:
        - description
        - executed_at
        - intent
        - name
        - priority
        - rejected_at
        - rejected_reason
        - ref
        - requires_2fa
        - requires_rcp
        - sections
        - status
        - terms
      properties:
        description:
          type:
            - string
            - "null"
        executed_at:
          type:
            - string
            - "null"
          format: date-time
        intent:
          type: string
        name:
          type: string
        priority:
          type: string
        rejected_at:
          type:
            - string
            - "null"
          format: date-time
        rejected_reason:
          type:
            - string
            - "null"
        ref:
          $ref: "#/components/schemas/Ref"
        requires_2fa:
          type: boolean
        requires_rcp:
          type: boolean
        sections:
          type: array
          items:
            $ref: "#/components/schemas/Section"
        status:
          type: string
        terms:
          type: array
          items:
            $ref: "#/components/schemas/Term"
    CanonicalDocument:
      type: object
      description: Canonical agreement or template document payload.
      additionalProperties: true
    ParticipantActor:
      type: object
      description: Linked actor identity for an active participant.
      required:
        - ref
      properties:
        kind:
          type: string
        ref:
          $ref: "#/components/schemas/Ref"
    Participant:
      type: object
      description: Canonical agreement participant resource.
      required:
        - active
        - actor
        - avatar_url
        - email
        - name
        - ref
        - type
      properties:
        active:
          type: boolean
        actor:
          anyOf:
            - $ref: "#/components/schemas/ParticipantActor"
            - type: "null"
        avatar_url:
          type:
            - string
            - "null"
        email:
          type: string
          format: email
        name:
          type: string
        ref:
          $ref: "#/components/schemas/Ref"
        type:
          type: string
          enum: [commentor, editor, signer, viewer]
    InvitationPartial:
      type: object
      description: Partial invitation resource returned when participant creation requires recipient acceptance.
      required:
        - email
        - ref
        - type
      properties:
        email:
          type: string
          format: email
        ref:
          $ref: "#/components/schemas/Ref"
        type:
          type: string
          enum: [commentor, editor, signer, viewer]
    InvitationReference:
      type: object
      description: Invitation reference returned by invitation lifecycle events.
      required:
        - ref
      properties:
        ref:
          $ref: "#/components/schemas/Ref"
    Session:
      type: object
      description: Authenticated session continuation payload.
      additionalProperties: true
    ProtocolState:
      type: string
      description: Current server-driven signing protocol state for the authenticated actor.
      enum:
        - idle
        - authenticate
        - confirm_authentication
        - assign_rcp
        - confirm_rcp
        - verify_signature
        - sign
    JsonSchema:
      type: object
      description: Inline JSON Schema document that validates the next tool input.
      additionalProperties: true
    ProtocolAction:
      type: object
      description: Next tool call prescribed by the signing protocol.
      required:
        - description
        - name
        - schema
      properties:
        description:
          type: string
        name:
          type: string
          enum:
            - create_authentication
            - create_rcp_assignment
            - create_rcp_confirmation
            - create_signature
            - create_verification_confirmation
        schema:
          $ref: "#/components/schemas/JsonSchema"
    Protocol:
      type: object
      description: Current protocol state and next prescribed tool call for agreement signing.
      required:
        - action
        - state
      properties:
        state:
          $ref: "#/components/schemas/ProtocolState"
        action:
          anyOf:
            - $ref: "#/components/schemas/ProtocolAction"
            - type: "null"
    SignatureVerification:
      type: object
      description: Signature or signing authentication verification challenge.
      required:
        - channel
        - expires_at
        - ref
      properties:
        channel:
          type:
            - string
            - "null"
        expires_at:
          type:
            - string
            - "null"
          format: date-time
        ref:
          $ref: "#/components/schemas/Ref"
    Signature:
      type: object
      description: Canonical agreement signature record.
      required:
        - created_at
        - ref
        - requires_2fa
      properties:
        created_at:
          type: string
          format: date-time
        ref:
          $ref: "#/components/schemas/Ref"
        requires_2fa:
          type: boolean
    RcpExpectedActor:
      type: object
      description: Actor identity attached to a remote confirmation requirement.
      required:
        - name
        - ref
      properties:
        name:
          type: string
        ref:
          type:
            - string
            - "null"
          format: uuid
    RcpIncomingRequirement:
      type: object
      description: Incoming remote confirmation requirement for the authenticated actor.
      required:
        - confirmed_at
        - expected_from
        - token
      properties:
        confirmed_at:
          type:
            - string
            - "null"
          format: date-time
        expected_from:
          anyOf:
            - $ref: "#/components/schemas/RcpExpectedActor"
            - type: "null"
        token:
          type: string
    RcpOutgoingAssignment:
      type: object
      description: Outgoing remote confirmation assignment issued by the authenticated actor.
      required:
        - code
        - confirmed_at
        - recipient
        - token
      properties:
        code:
          type: string
        confirmed_at:
          type:
            - string
            - "null"
          format: date-time
        recipient:
          anyOf:
            - $ref: "#/components/schemas/RcpExpectedActor"
            - type: "null"
        token:
          type: string
    RcpContext:
      type: object
      description: Remote confirmation party context for an agreement.
      required:
        - completed_count
        - incoming_requirement
        - outgoing_assignment
        - ready
        - total_count
      properties:
        completed_count:
          type: integer
        incoming_requirement:
          anyOf:
            - $ref: "#/components/schemas/RcpIncomingRequirement"
            - type: "null"
        outgoing_assignment:
          anyOf:
            - $ref: "#/components/schemas/RcpOutgoingAssignment"
            - type: "null"
        ready:
          type: boolean
        total_count:
          type: integer
    RcpChallenge:
      type: object
      description: Remote confirmation challenge state.
      required:
        - code
        - confirmed_at
        - ref
      properties:
        code:
          type: string
        confirmed_at:
          type:
            - string
            - "null"
          format: date-time
        ref:
          $ref: "#/components/schemas/Ref"
    Pagination:
      type: object
      description: Standard paginated collection metadata.
      required:
        - page
        - page_size
        - total_pages
        - total_records
      properties:
        page:
          type: integer
        page_size:
          type: integer
        total_pages:
          type: integer
        total_records:
          type: integer
