{
  "openapi": "3.1.0",
  "info": {
    "title": "AI LearnOS Public & Protocol API",
    "version": "0.1.0",
    "description": "Authoritative OpenAPI 3.1 contract for AI Capability OS (AI LearnOS). Covers Public Verification, Share Grants, Enterprise Verification Standard (EVS), Billing, Learning Runtime, Opportunity Matching, and Organization Cohorts."
  },
  "servers": [
    {
      "url": "http://localhost:3000",
      "description": "Local Development Server"
    }
  ],
  "paths": {
    "/api/verify/{id}": {
      "get": {
        "summary": "Resolve Public Verification ID",
        "description": "Public, unauthenticated resolution of an issued credential, passport claim, or proof-of-skill. Returns issuer metadata, revocation status, evidence summary, and protocol version.",
        "operationId": "resolveVerification",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The opaque public verification ID (e.g. pvi_...)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Verification details successfully resolved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationResolution"
                }
              }
            }
          },
          "400": {
            "description": "Missing verification ID parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Verification ID not found or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/share": {
      "get": {
        "summary": "Resolve Scoped Share Grant",
        "description": "Public resolution of a scoped learner passport share grant. Atomically increments view count and enforces time expiration and maximum view limits.",
        "operationId": "resolveShareGrant",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "The share grant ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Share grant successfully resolved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResolvedShareGrant"
                }
              }
            }
          },
          "400": {
            "description": "Missing share ID query parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Share grant expired, revoked, or max views exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create Scoped Share Grant",
        "description": "Authenticated learner generates a privacy-preserving, time-bounded or view-bounded share grant for their skill passport.",
        "operationId": "createShareGrant",
        "security": [{ "SessionAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateShareGrantRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Share grant created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateShareGrantResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/evs": {
      "post": {
        "summary": "Issue Enterprise Verification ID",
        "description": "Learner issues a fixed-scope Enterprise Verification Standard (EVS) ID for a specific enterprise organization.",
        "operationId": "issueEvs",
        "security": [{ "SessionAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IssueEvsRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "EVS ID successfully issued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IssueEvsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/evs/resolve": {
      "post": {
        "summary": "Resolve Enterprise Verification ID",
        "description": "Enterprise organization verifies an employee or candidate's EVS token. Unconditionally logs verification access.",
        "operationId": "resolveEvs",
        "security": [{ "SessionAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResolveEvsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "EVS verified and scoped skills returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResolveEvsResponse"
                }
              }
            }
          },
          "403": {
            "description": "Unauthorized organization or insufficient role.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "EVS ID not found or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/evs/revoke": {
      "post": {
        "summary": "Revoke Enterprise Verification ID",
        "description": "Learner immediately revokes an issued EVS token.",
        "operationId": "revokeEvs",
        "security": [{ "SessionAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["evsId"],
                "properties": {
                  "evsId": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "EVS successfully revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "evs": { "$ref": "#/components/schemas/EnterpriseVerificationRecord" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/billing/plans": {
      "get": {
        "summary": "List Active Billing Plans",
        "description": "Public catalog of subscription plans and one-time credit packs with pricing in integer minor units.",
        "operationId": "listBillingPlans",
        "responses": {
          "200": {
            "description": "List of active plans.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "plans": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PlanCatalogItem"
                      }
                    }
                  },
                  "required": ["plans"]
                }
              }
            }
          }
        }
      }
    },
    "/api/billing/checkout": {
      "post": {
        "summary": "Create Checkout Session",
        "description": "Initiates payment checkout for a subscription or credit pack. Routes currency automatically (TWD -> NewebPay, non-TWD -> PayPal).",
        "operationId": "createCheckout",
        "security": [{ "SessionAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckoutRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout session created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/network/leaderboard": {
      "get": {
        "summary": "Get Leaderboard Rankings",
        "description": "Public capability rankings across Free and Premium zones.",
        "operationId": "getLeaderboard",
        "parameters": [
          {
            "name": "zone",
            "in": "query",
            "required": false,
            "description": "Leaderboard zone (free | premium)",
            "schema": {
              "type": "string",
              "enum": ["free", "premium"],
              "default": "free"
            }
          },
          {
            "name": "skillNodeId",
            "in": "query",
            "required": false,
            "description": "Filter rankings by specific skill node ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of entries (1-100)",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Leaderboard entries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "entries": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/LeaderboardEntry"
                      }
                    }
                  },
                  "required": ["entries"]
                }
              }
            }
          }
        }
      }
    },
    "/api/network/teams": {
      "get": {
        "summary": "List Team Rankings",
        "description": "Lists collaborative team rankings within a leaderboard zone.",
        "operationId": "listTeams",
        "parameters": [
          {
            "name": "zone",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["free", "premium"], "default": "free" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 20 }
          }
        ],
        "responses": {
          "200": {
            "description": "Team rankings.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "teams": { "type": "array", "items": { "$ref": "#/components/schemas/TeamRankingEntry" } }
                  },
                  "required": ["teams"]
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Manage Team Membership",
        "description": "Create, join, or leave a collaborative team.",
        "operationId": "manageTeam",
        "security": [{ "SessionAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TeamActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Team operation successful.",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "team": { "type": "object" } } }
              }
            }
          }
        }
      }
    },
    "/api/network/matches": {
      "get": {
        "summary": "List Opportunity Matches",
        "description": "Recomputes and returns privacy-preserving matched opportunities for the learner.",
        "operationId": "listMatches",
        "security": [{ "SessionAuth": [] }],
        "responses": {
          "200": {
            "description": "List of opportunity matches.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "matches": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/OpportunityMatch" }
                    }
                  },
                  "required": ["matches"]
                }
              }
            }
          }
        }
      }
    },
    "/api/network/matches/{id}/release": {
      "post": {
        "summary": "Release Opportunity Match Profile",
        "description": "Learner explicitly consents to reveal their verified identity and passport to the matched opportunity company.",
        "operationId": "releaseMatch",
        "security": [{ "SessionAuth": [] }],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Match released.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "match": { "$ref": "#/components/schemas/OpportunityMatch" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/student-verification": {
      "post": {
        "summary": "Create Student Email Verification Session",
        "description": "Generates a cryptographic single-use verification token and pre-filled mailto: challenge link.",
        "operationId": "createStudentVerification",
        "security": [{ "SessionAuth": [] }],
        "responses": {
          "201": {
            "description": "Session created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StudentVerificationSessionResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (5 requests/hour or 10 requests/day).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/student-verification/{id}/status": {
      "get": {
        "summary": "Get Student Verification Status",
        "description": "Polls verification status for a student verification session owned by the authenticated learner.",
        "operationId": "getStudentVerificationStatus",
        "security": [{ "SessionAuth": [] }],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Session status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StudentVerificationStatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/student-verification/{id}/cancel": {
      "post": {
        "summary": "Cancel Student Verification Session",
        "description": "Explicitly cancels an active pending student verification session.",
        "operationId": "cancelStudentVerification",
        "security": [{ "SessionAuth": [] }],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Session cancelled.",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }
              }
            }
          }
        }
      }
    },
    "/api/student-verification/{id}/retry": {
      "post": {
        "summary": "Retry Student Verification Session",
        "description": "Cancels prior session and returns a fresh mailto: link.",
        "operationId": "retryStudentVerification",
        "security": [{ "SessionAuth": [] }],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "201": {
            "description": "Fresh session created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StudentVerificationSessionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/org/cohorts": {
      "get": {
        "summary": "List Organization Cohorts",
        "description": "Lists all cohorts in the organization.",
        "operationId": "listOrgCohorts",
        "security": [{ "SessionAuth": [] }],
        "parameters": [
          {
            "name": "orgId",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of cohorts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "cohorts": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/CohortRecord" }
                    }
                  },
                  "required": ["cohorts"]
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create Organization Cohort",
        "description": "Manager creates a learner cohort.",
        "operationId": "createOrgCohort",
        "security": [{ "SessionAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCohortRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Cohort created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "cohort": { "$ref": "#/components/schemas/CohortRecord" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/org/workforce-report": {
      "get": {
        "summary": "List Workforce Reports",
        "description": "Lists generated workforce reports for an organization.",
        "operationId": "listWorkforceReports",
        "security": [{ "SessionAuth": [] }],
        "parameters": [
          {
            "name": "orgId",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of reports.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reports": { "type": "array", "items": { "type": "object" } },
                    "enabled": { "type": "boolean" }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Generate Workforce Report",
        "description": "Triggers skill intelligence analysis for an organization.",
        "operationId": "generateWorkforceReport",
        "security": [{ "SessionAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["orgId"],
                "properties": { "orgId": { "type": "string" } }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Report generated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "report": { "type": "object" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/activities/{id}/assistance": {
      "post": {
        "summary": "Request Tutor Assistance",
        "description": "Requests scaffolding assistance during an activity with support-debt accounting.",
        "operationId": "requestAssistance",
        "security": [{ "SessionAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssistanceRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Assistance event.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "event": { "type": "object" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/activities/{id}/attempts": {
      "post": {
        "summary": "Record Activity Answer Attempt",
        "description": "Records answer attempt, evaluates mastery against student model, and performs diagnostic checks.",
        "operationId": "recordAttempt",
        "security": [{ "SessionAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecordAttemptRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Attempt recorded and evaluated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecordAttemptResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/sources": {
      "get": {
        "summary": "List Uploaded Sources",
        "description": "Lists source documents uploaded by the authenticated user.",
        "operationId": "listSources",
        "security": [{ "SessionAuth": [] }],
        "responses": {
          "200": {
            "description": "List of sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "documents": { "type": "array", "items": { "$ref": "#/components/schemas/SourceDocument" } }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Upload and Ingest Source Document",
        "description": "Uploads PDF/EPUB/DOCX/MD/URL file with provenance chunking.",
        "operationId": "uploadSource",
        "security": [{ "SessionAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file", "sourceType"],
                "properties": {
                  "file": { "type": "string", "format": "binary" },
                  "sourceType": {
                    "type": "string",
                    "enum": ["pdf", "epub", "docx", "md", "url", "audio_transcript"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Source ingested.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "document": { "$ref": "#/components/schemas/SourceDocument" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/compile": {
      "get": {
        "summary": "List Compilation Jobs",
        "description": "Lists compilation jobs for the authenticated creator.",
        "operationId": "listCompileJobs",
        "security": [{ "SessionAuth": [] }],
        "responses": {
          "200": {
            "description": "List of jobs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/CompileJob" } }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Dispatch Course Compilation",
        "description": "Dispatches compilation workflow for an ingested source document.",
        "operationId": "dispatchCompileJob",
        "security": [{ "SessionAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["documentId"],
                "properties": { "documentId": { "type": "string" } }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Compile job dispatched.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job": { "$ref": "#/components/schemas/CompileJob" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "SessionAuth": {
        "type": "apiKey",
        "in": "cookie",
        "name": "better-auth.session_token",
        "description": "Better-Auth HTTP-only session cookie."
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" },
          "status": { "type": "string" }
        }
      },
      "VerificationResolution": {
        "type": "object",
        "required": ["protocolVersion", "status", "verifiedAt"],
        "properties": {
          "protocolVersion": { "type": "string", "example": "0.1" },
          "status": {
            "type": "string",
            "enum": ["valid", "revoked", "expired", "not_found"]
          },
          "verificationId": { "type": "string" },
          "credentialId": { "type": "string" },
          "skillNodeId": { "type": "string" },
          "skillName": { "type": "string" },
          "levelClaimed": { "type": "string" },
          "kind": { "type": "string" },
          "issuedAt": { "type": "string", "format": "date-time" },
          "expiresAt": { "type": "string", "format": "date-time", "nullable": true },
          "revokedAt": { "type": "string", "format": "date-time", "nullable": true },
          "revokeReason": { "type": "string", "nullable": true },
          "issuer": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": { "type": "string" },
              "displayName": { "type": "string" },
              "authorityStatus": { "type": "string", "nullable": true }
            }
          },
          "evidenceSummary": {
            "type": "object",
            "properties": {
              "count": { "type": "integer" },
              "lastAt": { "type": "string", "format": "date-time" },
              "topSource": { "type": "string" }
            }
          },
          "verifiedAt": { "type": "string", "format": "date-time" }
        }
      },
      "CreateShareGrantRequest": {
        "type": "object",
        "required": ["expiresAt"],
        "properties": {
          "scope": {
            "type": "object",
            "properties": {
              "fullPassport": { "type": "boolean", "default": true },
              "skillNodeIds": { "type": "array", "items": { "type": "string" } }
            }
          },
          "expiresAt": { "type": "string", "format": "date-time" },
          "maxViews": { "type": "integer", "nullable": true, "minimum": 1 }
        }
      },
      "CreateShareGrantResponse": {
        "type": "object",
        "required": ["grant"],
        "properties": {
          "grant": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "userId": { "type": "string" },
              "scope": { "type": "object" },
              "expiresAt": { "type": "string", "format": "date-time" },
              "maxViews": { "type": "integer", "nullable": true },
              "viewCount": { "type": "integer" },
              "createdAt": { "type": "string", "format": "date-time" }
            }
          }
        }
      },
      "ResolvedShareGrant": {
        "type": "object",
        "required": ["grantId", "learner", "scope", "skills", "expiresAt", "viewsRemaining"],
        "properties": {
          "grantId": { "type": "string" },
          "learner": {
            "type": "object",
            "properties": {
              "displayName": { "type": "string" },
              "avatarUrl": { "type": "string", "nullable": true }
            }
          },
          "scope": { "type": "object" },
          "skills": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "skillNodeId": { "type": "string" },
                "name": { "type": "string" },
                "level": { "type": "string" },
                "evidenceCount": { "type": "integer" },
                "lastVerifiedAt": { "type": "string", "format": "date-time" }
              }
            }
          },
          "expiresAt": { "type": "string", "format": "date-time" },
          "viewsRemaining": { "type": "integer", "nullable": true }
        }
      },
      "IssueEvsRequest": {
        "type": "object",
        "required": ["orgId", "skillNodeIds"],
        "properties": {
          "orgId": { "type": "string" },
          "skillNodeIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 }
        }
      },
      "IssueEvsResponse": {
        "type": "object",
        "required": ["evs"],
        "properties": {
          "evs": {
            "$ref": "#/components/schemas/EnterpriseVerificationRecord"
          }
        }
      },
      "EnterpriseVerificationRecord": {
        "type": "object",
        "required": ["id", "userId", "organizationId", "scopedSkillNodeIds", "createdAt"],
        "properties": {
          "id": { "type": "string" },
          "userId": { "type": "string" },
          "organizationId": { "type": "string" },
          "scopedSkillNodeIds": { "type": "array", "items": { "type": "string" } },
          "revokedAt": { "type": "string", "format": "date-time", "nullable": true },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "ResolveEvsRequest": {
        "type": "object",
        "required": ["evsId", "orgId"],
        "properties": {
          "evsId": { "type": "string" },
          "orgId": { "type": "string" }
        }
      },
      "ResolveEvsResponse": {
        "type": "object",
        "required": ["valid", "evsId", "learnerId", "organizationId", "evsVersion", "issuer", "scopedSkills", "resolvedAt"],
        "properties": {
          "valid": { "type": "boolean" },
          "evsId": { "type": "string" },
          "learnerId": { "type": "string" },
          "organizationId": { "type": "string" },
          "evsVersion": {
            "type": "string",
            "description": "Protocol version of the resolution payload.",
            "enum": ["1.0"]
          },
          "issuer": {
            "type": "object",
            "nullable": true,
            "description": "Top-level credential issuer; null when the credential has no issuer.",
            "required": ["displayName", "tier"],
            "properties": {
              "displayName": { "type": "string" },
              "tier": { "type": "string", "enum": ["platform", "accredited", "community"] }
            }
          },
          "scopedSkills": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "skillNodeId",
                "skillName",
                "level",
                "historicalPeakLevel",
                "evidenceSummary",
                "confidenceBand",
                "lastVerifiedAt",
                "credentialValidity"
              ],
              "properties": {
                "skillNodeId": { "type": "string" },
                "skillName": { "type": "string" },
                "level": { "type": "string", "description": "Current SkillMasteryLevel." },
                "historicalPeakLevel": {
                  "type": "string",
                  "description": "Highest SkillMasteryLevel ever attained for this skill."
                },
                "evidenceSummary": {
                  "type": "object",
                  "properties": {
                    "count": { "type": "integer" },
                    "lastAt": { "type": "string", "format": "date-time" },
                    "topSource": { "type": "string" }
                  }
                },
                "confidenceBand": {
                  "type": "string",
                  "description": "Derived from evidence_confidence: < 0.4 = low, < 0.7 = medium, >= 0.7 = high.",
                  "enum": ["low", "medium", "high"]
                },
                "lastVerifiedAt": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true,
                  "description": "From learner_skill_state.last_verified_at; null when never verified."
                },
                "credentialValidity": {
                  "type": "boolean",
                  "description": "True iff an active non-revoked proof-of-skill credential exists for this skill."
                }
              }
            }
          },
          "resolvedAt": { "type": "string", "format": "date-time" }
        }
      },
      "PlanCatalogItem": {
        "type": "object",
        "required": ["key", "kind", "displayNameKey", "priceMinor", "currency", "isActive"],
        "properties": {
          "key": { "type": "string" },
          "kind": { "type": "string", "enum": ["subscription", "credit_pack"] },
          "displayNameKey": { "type": "string" },
          "priceMinor": { "type": "integer", "description": "Price in minor units (e.g. 33000 = 330.00 TWD)" },
          "currency": { "type": "string", "example": "TWD" },
          "monthlyPoints": { "type": "integer", "nullable": true },
          "pointsGrant": { "type": "integer", "nullable": true },
          "isActive": { "type": "boolean" }
        }
      },
      "CheckoutRequest": {
        "type": "object",
        "required": ["productKey"],
        "properties": {
          "productKey": { "type": "string" },
          "successUrl": { "type": "string", "format": "uri" },
          "cancelUrl": { "type": "string", "format": "uri" }
        }
      },
      "CheckoutResponse": {
        "type": "object",
        "properties": {
          "provider": { "type": "string", "enum": ["newebpay", "paypal"] },
          "actionUrl": { "type": "string" },
          "formParams": { "type": "object" },
          "checkoutUrl": { "type": "string" },
          "orderId": { "type": "string" }
        }
      },
      "LeaderboardEntry": {
        "type": "object",
        "required": ["rank", "userId", "displayName", "zone", "totalMasteryPoints", "skillsMastered"],
        "properties": {
          "rank": { "type": "integer" },
          "userId": { "type": "string" },
          "displayName": { "type": "string" },
          "zone": { "type": "string", "enum": ["free", "premium"] },
          "totalMasteryPoints": { "type": "integer" },
          "skillsMastered": { "type": "integer" },
          "topSkill": { "type": "string", "nullable": true }
        }
      },
      "TeamRankingEntry": {
        "type": "object",
        "required": ["rank", "teamId", "teamName", "memberCount", "totalPoints"],
        "properties": {
          "rank": { "type": "integer" },
          "teamId": { "type": "string" },
          "teamName": { "type": "string" },
          "memberCount": { "type": "integer" },
          "totalPoints": { "type": "integer" }
        }
      },
      "TeamActionRequest": {
        "type": "object",
        "required": ["action"],
        "properties": {
          "action": { "type": "string", "enum": ["create", "join", "leave"] },
          "name": { "type": "string" },
          "teamId": { "type": "string" }
        }
      },
      "OpportunityMatch": {
        "type": "object",
        "required": ["id", "companyName", "roleTitle", "matchScore", "matchedSkills", "status"],
        "properties": {
          "id": { "type": "string" },
          "companyName": { "type": "string" },
          "roleTitle": { "type": "string" },
          "matchScore": { "type": "number" },
          "matchedSkills": { "type": "array", "items": { "type": "string" } },
          "status": { "type": "string", "enum": ["pending_learner_release", "released"] },
          "releasedAt": { "type": "string", "format": "date-time", "nullable": true }
        }
      },
      "StudentVerificationSessionResponse": {
        "type": "object",
        "required": ["id", "mailtoUrl", "expiresAt"],
        "properties": {
          "id": { "type": "string" },
          "mailtoUrl": { "type": "string" },
          "expiresAt": { "type": "string", "format": "date-time" }
        }
      },
      "StudentVerificationStatusResponse": {
        "type": "object",
        "required": ["sessionId", "status", "expiresAt"],
        "properties": {
          "sessionId": { "type": "string" },
          "status": { "type": "string", "enum": ["pending", "verified", "failed", "cancelled", "expired"] },
          "expiresAt": { "type": "string", "format": "date-time" },
          "verification": {
            "type": "object",
            "nullable": true,
            "properties": {
              "level": { "type": "string" },
              "institutionName": { "type": "string", "nullable": true },
              "domain": { "type": "string" },
              "verifiedAt": { "type": "string", "format": "date-time" },
              "expiresAt": { "type": "string", "format": "date-time" }
            }
          }
        }
      },
      "CohortRecord": {
        "type": "object",
        "required": ["id", "organizationId", "courseId", "name", "createdAt"],
        "properties": {
          "id": { "type": "string" },
          "organizationId": { "type": "string" },
          "courseId": { "type": "string" },
          "name": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "CreateCohortRequest": {
        "type": "object",
        "required": ["orgId", "courseId", "name"],
        "properties": {
          "orgId": { "type": "string" },
          "courseId": { "type": "string" },
          "name": { "type": "string" }
        }
      },
      "AssistanceRequest": {
        "type": "object",
        "required": ["kind"],
        "properties": {
          "kind": { "type": "string", "enum": ["hint", "explanation", "remediation", "solution"] },
          "attemptId": { "type": "string" },
          "content": { "type": "string" }
        }
      },
      "RecordAttemptRequest": {
        "type": "object",
        "required": ["correct"],
        "properties": {
          "response": { "type": "object" },
          "correct": { "type": "boolean" },
          "score": { "type": "number" }
        }
      },
      "RecordAttemptResponse": {
        "type": "object",
        "required": ["attempt", "evidenceResult"],
        "properties": {
          "attempt": { "type": "object" },
          "evidenceResult": { "type": "object" },
          "diagnosis": { "type": "object", "nullable": true }
        }
      },
      "SourceDocument": {
        "type": "object",
        "required": ["id", "title", "sourceType", "status"],
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "sourceType": { "type": "string" },
          "status": { "type": "string" },
          "chunkCount": { "type": "integer" }
        }
      },
      "CompileJob": {
        "type": "object",
        "required": ["id", "status"],
        "properties": {
          "id": { "type": "string" },
          "status": { "type": "string" },
          "courseId": { "type": "string", "nullable": true }
        }
      }
    }
  }
}