API Evangelist enhancements for the Cobot API

# authorship: generated by API Evangelist tooling. Stamped 2026-08-18
# on the file's own generator header (roadmap#64). An unmarked file is
# NOT assumed to be ours -- absence of evidence was never stamped.
x-method: generated
overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Cobot API
  version: 1.0.0
extends: ../openapi/cobot-api2-openapi.yml
x-generated: '2026-08-09'
x-method: generated
x-source: >-
  Generated by the API Evangelist enrichment pipeline from openapi/cobot-api2-openapi.yml plus the
  probed surfaces in well-known/, mcp/, conventions/, errors/ and lifecycle/. It never mutates the
  original spec — apply it to get the annotated view.
actions:
# ---------------------------------------------------------------------------
# 1. Point the document at every companion artifact we hold.
# ---------------------------------------------------------------------------
- target: $.info
  update:
    x-apis-io:
      provider: cobot
      profile: https://raw.githubusercontent.com/api-evangelist/cobot/refs/heads/main/apis.yml
      artifacts:
        conventions: conventions/cobot-conventions.yml
        errors: errors/cobot-problem-types.yml
        scopes: scopes/cobot-scopes.yml
        authentication: authentication/cobot-authentication.yml
        data_model: data-model/cobot-data-model.yml
        lifecycle: lifecycle/cobot-lifecycle.yml
        changelog: changelog/cobot-changelog.yml
        webhooks: asyncapi/cobot-webhooks.yml
        mcp: mcp/cobot-mcp.yml
        well_known: well-known/cobot-well-known.yml
    x-discovery:
      api_catalog: https://www.cobot.me/.well-known/api-catalog
      service_desc: https://dev.cobot.me/openapi
      service_doc: https://dev.cobot.me/api2
      protected_resource_metadata: https://api.cobot.me/.well-known/oauth-protected-resource
      openid_configuration: https://www.cobot.me/.well-known/openid-configuration
      llms_txt: https://www.cobot.me/llms.txt
      status: https://api.cobot.me/health

# ---------------------------------------------------------------------------
# 2. Record the cross-cutting runtime semantics the spec documents in prose only.
# ---------------------------------------------------------------------------
- target: $.info
  update:
    x-conventions:
      standard: 'JSON:API 1.0'
      accept: 'application/vnd.api+json'
      content_type: 'application/vnd.api+json'
      pagination:
        style: page-number
        params: ['page[number]', 'page[size]']
        default_page_size: 72
        max_page_size: 200
        response_fields: [meta.totalPages, meta.currentPage, links.self, links.first, links.prev, links.next, links.last]
      sparse_fieldsets:
        supported: true
        param: 'fields[<type>]'
      array_query_params: comma-separated string
      datetimes: 'ISO 8601, always returned in UTC, milliseconds truncated'
      cors: enabled on all endpoints
      idempotency:
        supported: false
        note: No Idempotency-Key header or equivalent appears anywhere in the contract or the docs.
    x-rate-limit:
      default: 60 requests per minute per user
      exceeded_status: 429
      retry_header: Retry-After
      units: seconds
      declared_per_operation: false

# ---------------------------------------------------------------------------
# 3. Add the servers entry a client actually needs (subdomain-scoped v1 surface
#    is separate; API 2 is single-host) and name the auth server explicitly.
# ---------------------------------------------------------------------------
- target: $.servers[0]
  update:
    description: >-
      Production API 2 host. Unlike the legacy v1 API, API 2 is NOT scoped to a
      <subdomain>.cobot.me host — the space is addressed by id in the path.

- target: $.components.securitySchemes.OAuth2
  update:
    x-authorization-server: https://www.cobot.me
    x-metadata: https://www.cobot.me/.well-known/oauth-authorization-server
    x-pkce: S256
    x-dynamic-client-registration: https://www.cobot.me/oauth/register
    x-token-endpoint-auth-methods: [none]
    x-scope-count: 58
    x-client-registration-ui: https://dev.cobot.me/oauth2_clients

# ---------------------------------------------------------------------------
# 4. Flag the contract gaps we found, so a generated client knows what the spec
#    does NOT tell it. These are observations about the document, not new API behavior.
# ---------------------------------------------------------------------------
- target: $.info
  update:
    x-contract-gaps:
      undeclared_401: >-
        Every one of the 134 operations requires an OAuth 2.0 scope, yet no operation declares a
        401 or 403 response. Generated clients get no typed handling for token expiry or
        insufficient scope.
      undeclared_429: >-
        A 60 req/min limit with a Retry-After header is documented in info.description but declared
        on no operation.
      undeclared_5xx: No 5xx response is declared anywhere in the document.
      no_webhooks_in_v2: >-
        The webhook subscription API and its ~50 event types exist only on the legacy v1 API
        (https://dev.cobot.me/api-docs/webhooks-api). API 2 declares no `webhooks` block, so the
        event surface is invisible to anything reading this spec alone.

# ---------------------------------------------------------------------------
# 5. Mark the operations an agent can reach through Cobot's own MCP server.
# ---------------------------------------------------------------------------
- target: $.paths[*][*]
  update:
    x-agent-surface:
      mcp_server: https://api.cobot.me/mcp
      mcp_scopes: mcp/cobot-tool-crosswalk.yml
      note: >-
        The MCP server advertises 14 of the API's 58 scopes; 45 of 134 operations fall inside that
        scope set. See mcp/cobot-tool-crosswalk.yml for the per-scope binding.