API Evangelist enhancements for the Lang.ai 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 Lang.ai API
  version: 1.0.0
extends: openapi/langai-api-openapi.yml
x-generated: '2026-07-19'
x-method: generated
x-source: https://docs.lang.ai/
x-note: >-
  Lang.ai publishes no machine-readable specification, so openapi/langai-api-openapi.yml
  was itself generated from the published reference. This overlay carries the API
  Evangelist annotations layered on top of it — provenance, lifecycle posture, and the
  agent-facing execution semantics captured in conventions/ and errors/.
actions:
- target: $.info
  update:
    x-apievangelist-slug: langai
    x-apievangelist-artifacts:
      conventions: conventions/langai-conventions.yml
      errors: errors/langai-problem-types.yml
      authentication: authentication/langai-authentication.yml
      lifecycle: lifecycle/langai-lifecycle.yml
      data-model: data-model/langai-data-model.yml
      conformance: conformance/langai-conformance.yml
      skills: skills/_index.yml
      mcp: mcp/langai-mcp.yml
    x-apievangelist-lifecycle-status: acquired
    x-apievangelist-successor: https://capacity.com/
    x-apievangelist-spec-provenance: >-
      Generated by the API Evangelist enrichment pipeline from the human-readable
      reference at https://docs.lang.ai/. Not published by Lang.ai.
- target: $.info
  update:
    x-rate-limit:
      documented: true
      numeric_limits_published: false
      status_code: 429
      headers: none documented
      guidance: exponential backoff with jitter
- target: $.components.securitySchemes.bearerAuth
  update:
    x-token-rotation: >-
      Single active token per instance — generating a new token invalidates previously
      issued ones, so rotation is a hard cutover with no overlap window.
    x-token-source: Settings section of the Lang.ai instance
- target: $.paths./documents.post
  update:
    x-idempotency:
      supported: true
      mechanism: client-supplied-resource-id
      field: id
      semantics: >-
        Saving a document with an id that already exists overwrites it, so retries with a
        stable client-supplied id are safe and will not duplicate.
      header: null
- target: $.paths./project.post
  update:
    x-idempotency:
      supported: false
      warning: >-
        Project creation has no idempotency contract — a blind retry after a timeout may
        create a duplicate project. Reconcile with listProjects before retrying.
    x-long-running:
      note: >-
        Project creation is asynchronous. The response returns only the new project id;
        poll listProjects or getProjectTags until status transitions from Processing to
        Completed (or Errored) before classifying against it.
- target: $.paths./analyze.post
  update:
    x-side-effects: none
    x-note: >-
      analyzeDocument classifies without persisting. Use saveDocument when the document
      should land in the project's dashboard.
- target: $.tags
  update:
    x-apievangelist-note: >-
      Tags in the OpenAPI sense (Projects, Documents) are unrelated to Lang.ai "tags",
      which are the user-defined classifier groupings returned in responses.