thumbgate 1.27.17 → 1.27.18

package/adapters/chatgpt/openapi.yaml

@@ -0,0 +1,1695 @@
+openapi: 3.1.0
+info:
+  title: ThumbGate API
+  version: 1.2.0
+  description: |
+    Production API for feedback capture, schema-validated memory promotion,
+    prevention rule generation, and DPO export.
+    Bare up/down signals are logged immediately, but the API returns
+    clarification_required until one sentence explains what worked or failed.
+    When the explanation is specific enough, ThumbGate infers a domain tag if
+    the caller omitted manual tags so the feedback can still promote cleanly.
+servers:
+  - url: https://thumbgate-production.up.railway.app
+security:
+  - bearerAuth: []
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: API Key
+  schemas:
+    RubricScore:
+      type: object
+      required: [criterion, score]
+      properties:
+        criterion:
+          type: string
+        score:
+          type: number
+          minimum: 1
+          maximum: 5
+        evidence:
+          type: string
+        judge:
+          type: string
+    CaptureFeedbackRequest:
+      type: object
+      required: [signal]
+      properties:
+        signal:
+          type: string
+          enum: [up, down, positive, negative]
+        context:
+          type: string
+          description: One-sentence reason describing what worked or failed
+        whatWentWrong:
+          type: string
+        whatToChange:
+          type: string
+        whatWorked:
+          type: string
+        rubricScores:
+          type: array
+          items:
+            $ref: '#/components/schemas/RubricScore'
+        guardrails:
+          type: object
+          properties:
+            testsPassed:
+              type: boolean
+            pathSafety:
+              type: boolean
+            budgetCompliant:
+              type: boolean
+        tags:
+          oneOf:
+            - type: array
+              items:
+                type: string
+            - type: string
+          description: Optional domain tags. If omitted, ThumbGate infers one from the feedback text before promotion.
+        skill:
+          type: string
+    IntentPlanRequest:
+      type: object
+      required: [intentId]
+      properties:
+        intentId:
+          type: string
+        context:
+          type: string
+        mcpProfile:
+          type: string
+        bundleId:
+          type: string
+        partnerProfile:
+          type: string
+        delegationMode:
+          type: string
+          enum: [off, auto, sequential]
+        approved:
+          type: boolean
+        repoPath:
+          type: string
+    InternalAgentBootstrapRequest:
+      type: object
+      required: [source]
+      properties:
+        source:
+          type: string
+          enum: [github, slack, linear, api, cli]
+        repoPath:
+          type: string
+        prepareSandbox:
+          type: boolean
+        sandboxRoot:
+          type: string
+        intentId:
+          type: string
+        context:
+          type: string
+        mcpProfile:
+          type: string
+        partnerProfile:
+          type: string
+        delegationMode:
+          type: string
+          enum: [off, auto, sequential]
+        approved:
+          type: boolean
+        trigger:
+          type: object
+          properties:
+            type:
+              type: string
+            id:
+              type: string
+            url:
+              type: string
+            actor:
+              type: string
+        thread:
+          type: object
+          properties:
+            id:
+              type: string
+            title:
+              type: string
+            url:
+              type: string
+        task:
+          type: object
+          properties:
+            title:
+              type: string
+            body:
+              type: string
+            number:
+              type: string
+            branch:
+              type: string
+            labels:
+              type: array
+              items:
+                type: string
+        comments:
+          type: array
+          items:
+            type: object
+            properties:
+              author:
+                type: string
+              text:
+                type: string
+              timestamp:
+                type: string
+        messages:
+          type: array
+          items:
+            type: object
+            properties:
+              author:
+                type: string
+              text:
+                type: string
+              timestamp:
+                type: string
+    HandoffStartRequest:
+      type: object
+      required: [intentId]
+      properties:
+        intentId:
+          type: string
+        context:
+          type: string
+        mcpProfile:
+          type: string
+        bundleId:
+          type: string
+        partnerProfile:
+          type: string
+        approved:
+          type: boolean
+        repoPath:
+          type: string
+        delegateProfile:
+          type: string
+        plannedChecks:
+          type: array
+          items:
+            type: string
+    HandoffCompleteRequest:
+      type: object
+      required: [handoffId, outcome]
+      properties:
+        handoffId:
+          type: string
+        outcome:
+          type: string
+          enum: [accepted, rejected, aborted]
+        resultContext:
+          type: string
+        attempts:
+          type: number
+        violationCount:
+          type: number
+        tokenEstimate:
+          type: number
+        latencyMs:
+          type: number
+        summary:
+          type: string
+    BillingCheckoutRequest:
+      type: object
+      properties:
+        successUrl:
+          type: string
+          format: uri
+        cancelUrl:
+          type: string
+          format: uri
+        customerEmail:
+          type: string
+          format: email
+        installId:
+          type: string
+        metadata:
+          type: object
+          additionalProperties:
+            type: string
+    BillingProvisionRequest:
+      type: object
+      required: [customerId]
+      properties:
+        customerId:
+          type: string
+        installId:
+          type: string
+    WorkflowSprintIntakeRequest:
+      type: object
+      required: [email, workflow, owner, blocker, runtime]
+      properties:
+        email:
+          type: string
+          format: email
+        company:
+          type: string
+        workflow:
+          type: string
+        owner:
+          type: string
+        blocker:
+          type: string
+        runtime:
+          type: string
+        note:
+          type: string
+        acquisitionId:
+          type: string
+        visitorId:
+          type: string
+        sessionId:
+          type: string
+        traceId:
+          type: string
+        installId:
+          type: string
+        source:
+          type: string
+        utmSource:
+          type: string
+        utmMedium:
+          type: string
+        utmCampaign:
+          type: string
+        utmContent:
+          type: string
+        utmTerm:
+          type: string
+        community:
+          type: string
+        postId:
+          type: string
+        commentId:
+          type: string
+        campaignVariant:
+          type: string
+        offerCode:
+          type: string
+        ctaId:
+          type: string
+        ctaPlacement:
+          type: string
+        planId:
+          type: string
+        page:
+          type: string
+        landingPath:
+          type: string
+        referrerHost:
+          type: string
+        referrer:
+          type: string
+    WorkflowSprintIntakeResponse:
+      type: object
+      properties:
+        ok:
+          type: boolean
+        leadId:
+          type: string
+        status:
+          type: string
+        offer:
+          type: string
+        nextStep:
+          type: string
+        proofPackUrl:
+          type: string
+          format: uri
+        sprintBriefUrl:
+          type: string
+          format: uri
+    WorkflowSprintAdvanceRequest:
+      type: object
+      required: [leadId, status]
+      properties:
+        leadId:
+          type: string
+        status:
+          type: string
+          enum: [new, qualified, named_pilot, proof_backed_run, paid_team]
+        actor:
+          type: string
+        note:
+          type: string
+        reviewedBy:
+          type: string
+        workflowId:
+          type: string
+        teamId:
+          type: string
+        proofArtifacts:
+          type: array
+          items:
+            type: string
+    WorkflowSprintAdvanceResponse:
+      type: object
+      properties:
+        ok:
+          type: boolean
+        unchanged:
+          type: boolean
+        lead:
+          type: object
+          additionalProperties: true
+        workflowRun:
+          type: object
+          nullable: true
+          additionalProperties: true
+    FunnelAnalyticsResponse:
+      type: object
+      properties:
+        totalEvents:
+          type: integer
+        stageCounts:
+          type: object
+          properties:
+            acquisition:
+              type: integer
+            activation:
+              type: integer
+            paid:
+              type: integer
+        eventCounts:
+          type: object
+          additionalProperties:
+            type: integer
+        conversionRates:
+          type: object
+          properties:
+            acquisitionToActivation:
+              type: number
+            activationToPaid:
+              type: number
+            acquisitionToPaid:
+              type: number
+        paidProviderEvents:
+          type: integer
+    BillingSummaryResponse:
+      type: object
+      properties:
+        generatedAt:
+          type: string
+          format: date-time
+        coverage:
+          type: object
+          properties:
+            source:
+              type: string
+            tracksBookedRevenue:
+              type: boolean
+            tracksPaidOrders:
+              type: boolean
+            tracksInvoices:
+              type: boolean
+            tracksAttribution:
+              type: boolean
+            providerCoverage:
+              type: object
+              additionalProperties:
+                type: string
+        funnel:
+          allOf:
+            - $ref: '#/components/schemas/FunnelAnalyticsResponse'
+            - type: object
+              properties:
+                uniqueAcquisitionLeads:
+                  type: integer
+                uniquePaidCustomers:
+                  type: integer
+                firstPaidAt:
+                  type: string
+                  nullable: true
+                lastPaidAt:
+                  type: string
+                  nullable: true
+                lastPaidEvent:
+                  type: object
+                  nullable: true
+                  properties:
+                    timestamp:
+                      type: string
+                      nullable: true
+                    event:
+                      type: string
+                      nullable: true
+                    evidence:
+                      type: string
+                      nullable: true
+                    customerId:
+                      type: string
+                      nullable: true
+                    traceId:
+                      type: string
+                      nullable: true
+        signups:
+          type: object
+          properties:
+            total:
+              type: integer
+            uniqueLeads:
+              type: integer
+            bySource:
+              type: object
+              additionalProperties:
+                type: integer
+            byCampaign:
+              type: object
+              additionalProperties:
+                type: integer
+        pipeline:
+          type: object
+          properties:
+            workflowSprintLeads:
+              type: object
+              properties:
+                total:
+                  type: integer
+                bySource:
+                  type: object
+                  additionalProperties:
+                    type: integer
+            qualifiedWorkflowSprintLeads:
+              type: object
+              properties:
+                total:
+                  type: integer
+                bySource:
+                  type: object
+                  additionalProperties:
+                    type: integer
+        revenue:
+          type: object
+          properties:
+            paidProviderEvents:
+              type: integer
+            paidOrders:
+              type: integer
+            paidCustomers:
+              type: integer
+            bookedRevenueCents:
+              type: integer
+            bookedRevenueByCurrency:
+              type: object
+              additionalProperties:
+                type: integer
+            amountKnownOrders:
+              type: integer
+            amountUnknownOrders:
+              type: integer
+            amountKnownCoverageRate:
+              type: number
+            unreconciledPaidEvents:
+              type: integer
+            latestPaidAt:
+              type: string
+              nullable: true
+            latestPaidOrder:
+              type: object
+              nullable: true
+              properties:
+                timestamp:
+                  type: string
+                  nullable: true
+                provider:
+                  type: string
+                  nullable: true
+                event:
+                  type: string
+                  nullable: true
+                orderId:
+                  type: string
+                  nullable: true
+                customerId:
+                  type: string
+                  nullable: true
+                amountCents:
+                  type: integer
+                  nullable: true
+                currency:
+                  type: string
+                  nullable: true
+                amountKnown:
+                  type: boolean
+            byProvider:
+              type: object
+              additionalProperties:
+                type: object
+                properties:
+                  paidOrders:
+                    type: integer
+                  bookedRevenueCents:
+                    type: integer
+                  amountKnownOrders:
+                    type: integer
+                  amountUnknownOrders:
+                    type: integer
+                  bookedRevenueByCurrency:
+                    type: object
+                    additionalProperties:
+                      type: integer
+        attribution:
+          type: object
+          properties:
+            acquisitionBySource:
+              type: object
+              additionalProperties:
+                type: integer
+            acquisitionByCampaign:
+              type: object
+              additionalProperties:
+                type: integer
+            paidBySource:
+              type: object
+              additionalProperties:
+                type: integer
+            paidByCampaign:
+              type: object
+              additionalProperties:
+                type: integer
+            bookedRevenueBySourceCents:
+              type: object
+              additionalProperties:
+                type: integer
+            bookedRevenueByCampaignCents:
+              type: object
+              additionalProperties:
+                type: integer
+            conversionBySource:
+              type: object
+              additionalProperties:
+                type: number
+            conversionByCampaign:
+              type: object
+              additionalProperties:
+                type: number
+        keys:
+          type: object
+          properties:
+            total:
+              type: integer
+            active:
+              type: integer
+            disabled:
+              type: integer
+            activeCustomers:
+              type: integer
+            totalUsage:
+              type: integer
+            bySource:
+              type: object
+              additionalProperties:
+                type: integer
+            activeBySource:
+              type: object
+              additionalProperties:
+                type: integer
+        customers:
+          type: array
+          items:
+            type: object
+            properties:
+              customerId:
+                type: string
+              activeKeys:
+                type: integer
+              totalKeys:
+                type: integer
+              usageCount:
+                type: integer
+              source:
+                type: string
+              installId:
+                type: string
+                nullable: true
+              createdAt:
+                type: string
+                nullable: true
+              disabledAt:
+                type: string
+                nullable: true
+        trafficMetrics:
+          type: object
+          properties:
+            visitors:
+              type: integer
+            sessions:
+              type: integer
+            pageViews:
+              type: integer
+            ctaClicks:
+              type: integer
+            checkoutStarts:
+              type: integer
+            buyerLossFeedback:
+              type: integer
+            seoLandingViews:
+              type: integer
+        operatorGeneratedAcquisition:
+          type: object
+          properties:
+            totalEvents:
+              type: integer
+            uniqueLeads:
+              type: integer
+            bySource:
+              type: object
+              additionalProperties:
+                type: integer
+        dataQuality:
+          type: object
+          properties:
+            telemetryCoverage:
+              type: number
+            attributionCoverage:
+              type: number
+            amountKnownCoverage:
+              type: number
+            unreconciledPaidEvents:
+              type: integer
+paths:
+  /healthz:
+    get:
+      operationId: healthz
+      responses:
+        '200':
+          description: Service health
+        '401':
+          description: Unauthorized
+  /v1/feedback/capture:
+    post:
+      operationId: captureFeedback
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CaptureFeedbackRequest'
+      responses:
+        '200':
+          description: Feedback accepted and promoted to memory
+        '422':
+          description: Feedback logged only; clarification required or promotion rejected
+        '401':
+          description: Unauthorized
+  /v1/feedback/stats:
+    get:
+      operationId: getFeedbackStats
+      responses:
+        '200':
+          description: Aggregated feedback statistics
+        '401':
+          description: Unauthorized
+  /v1/feedback/infer:
+    post:
+      operationId: inferLessonFromHistory
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/InferLessonRequest'
+      responses:
+        '200':
+          description: Distilled lesson from chat history
+        '401':
+          description: Unauthorized
+  /v1/telemetry/ping:
+    post:
+      operationId: recordTelemetryPing
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
+      responses:
+        '204':
+          description: Telemetry accepted on a best-effort basis
+  /v1/analytics/funnel:
+    get:
+      operationId: getFunnelAnalytics
+      responses:
+        '200':
+          description: Acquisition/activation/paid funnel metrics from append-only ledger
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FunnelAnalyticsResponse'
+        '401':
+          description: Unauthorized
+  /v1/analytics/losses:
+    get:
+      operationId: getLossAnalytics
+      parameters:
+        - in: query
+          name: window
+          schema:
+            type: string
+            enum: [today, 7d, 30d, lifetime]
+        - in: query
+          name: timezone
+          schema:
+            type: string
+        - in: query
+          name: now
+          schema:
+            type: string
+            format: date-time
+      responses:
+        '200':
+          description: Ranked buyer-loss and revenue-opportunity analysis for the active analytics window
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        '401':
+          description: Unauthorized
+  /v1/dashboard:
+    get:
+      operationId: getDashboard
+      parameters:
+        - in: query
+          name: window
+          schema:
+            type: string
+            enum: [today, 7d, 30d, lifetime]
+        - in: query
+          name: timezone
+          schema:
+            type: string
+        - in: query
+          name: now
+          schema:
+            type: string
+            format: date-time
+      responses:
+        '200':
+          description: Full ThumbGate dashboard with feedback, telemetry, funnel, and observability analytics
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        '401':
+          description: Unauthorized
+  /v1/dashboard/review-state:
+    get:
+      operationId: getDashboardReviewState
+      responses:
+        '200':
+          description: Persisted dashboard review checkpoint and the current delta since that checkpoint
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        '401':
+          description: Unauthorized
+    post:
+      operationId: markDashboardReviewed
+      responses:
+        '200':
+          description: Persist and return the current dashboard review checkpoint
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        '401':
+          description: Unauthorized
+  /v1/dashboard/render-spec:
+    get:
+      operationId: getDashboardRenderSpec
+      parameters:
+        - in: query
+          name: view
+          schema:
+            type: string
+            enum: [team-review, incident-review, workflow-rollout]
+        - in: query
+          name: window
+          schema:
+            type: string
+            enum: [today, 7d, 30d, lifetime]
+        - in: query
+          name: timezone
+          schema:
+            type: string
+        - in: query
+          name: now
+          schema:
+            type: string
+            format: date-time
+      responses:
+        '200':
+          description: Constrained JSON render spec for hosted Team and operations dashboard views
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        '400':
+          description: Invalid dashboard render view or query
+        '401':
+          description: Unauthorized
+  /v1/decisions/evaluate:
+    post:
+      operationId: evaluateDecision
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                toolName:
+                  type: string
+                  description: Tool name is optional when provider-native tool call payload is supplied.
+                provider:
+                  type: string
+                model:
+                  type: string
+                providerToolCall:
+                  type: object
+                  additionalProperties: true
+                toolCall:
+                  type: object
+                  additionalProperties: true
+                toolUse:
+                  type: object
+                  additionalProperties: true
+                content:
+                  type: array
+                  items:
+                    type: object
+                    additionalProperties: true
+                input:
+                  type: object
+                  additionalProperties: true
+                arguments:
+                  type: object
+                  additionalProperties: true
+                method:
+                  type: string
+                params:
+                  type: object
+                  additionalProperties: true
+                mcp:
+                  type: object
+                  additionalProperties: true
+                mcpToolCall:
+                  type: object
+                  additionalProperties: true
+                usage:
+                  type: object
+                  additionalProperties: true
+                tokenEstimate:
+                  type: number
+                costUsd:
+                  type: number
+                budget:
+                  type: object
+                  additionalProperties: true
+                workflowPattern:
+                  type: string
+                  enum: [single_action, chaining, routing, parallelization, evaluator-optimizer, agent]
+                workflow:
+                  type: object
+                  additionalProperties: true
+                goal:
+                  type: string
+                tools:
+                  type: array
+                  items:
+                    type: string
+                branches:
+                  type: array
+                  items:
+                    type: string
+                steps:
+                  type: array
+                  items:
+                    type: string
+                routes:
+                  type: array
+                  items:
+                    type: string
+                command:
+                  type: string
+                filePath:
+                  type: string
+                changedFiles:
+                  type: array
+                  items:
+                    type: string
+                repoPath:
+                  type: string
+                baseBranch:
+                  type: string
+                requirePrForReleaseSensitive:
+                  type: boolean
+                requireVersionNotBehindBase:
+                  type: boolean
+                workflowDispatch:
+                  type: object
+                  description: Evidence required before running `gh workflow run` or another environment-specific workflow dispatch.
+                  properties:
+                    environment:
+                      type: string
+                      description: Requested environment such as dev, staging, beta, or release.
+                    workflow:
+                      type: string
+                      description: Expected workflow file or workflow name.
+                    ref:
+                      type: string
+                      description: Expected branch or ref passed to the workflow dispatch command.
+                    sha:
+                      type: string
+                      description: Expected HEAD SHA to verify before and after dispatch.
+                    job:
+                      type: string
+                      description: Expected job name to verify before reporting the workflow URL.
+      responses:
+        '200':
+          description: Persisted workflow-sentinel recommendation with decision-control metadata and actionId
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        '400':
+          description: Invalid decision evaluation request
+        '401':
+          description: Unauthorized
+  /v1/decisions/outcome:
+    post:
+      operationId: recordDecisionOutcome
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [actionId, outcome]
+              properties:
+                actionId:
+                  type: string
+                outcome:
+                  type: string
+                actualDecision:
+                  type: string
+                actor:
+                  type: string
+                notes:
+                  type: string
+                latencyMs:
+                  type: number
+                metadata:
+                  type: object
+                  additionalProperties: true
+      responses:
+        '200':
+          description: Recorded a decision override, rollback, completion, or block outcome
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        '400':
+          description: Invalid decision outcome request
+        '401':
+          description: Unauthorized
+  /v1/decisions/metrics:
+    get:
+      operationId: getDecisionMetrics
+      responses:
+        '200':
+          description: Decision-loop metrics derived from recorded evaluations and outcomes
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        '401':
+          description: Unauthorized
+  /v1/settings/status:
+    get:
+      operationId: getSettingsStatus
+      responses:
+        '200':
+          description: Resolved settings hierarchy with per-field origin metadata for managed, user, project, and local scopes
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        '401':
+          description: Unauthorized
+  /v1/billing/summary:
+    get:
+      operationId: getBillingSummary
+      responses:
+        '200':
+          description: Admin-only business summary from the funnel ledger, revenue ledger, and key store
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BillingSummaryResponse'
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden
+  /v1/intake/workflow-sprint:
+    post:
+      operationId: submitWorkflowSprintIntake
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WorkflowSprintIntakeRequest'
+      responses:
+        '201':
+          description: Workflow Hardening Sprint lead accepted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WorkflowSprintIntakeResponse'
+        '400':
+          description: Invalid sprint intake request
+  /v1/intake/workflow-sprint/advance:
+    post:
+      operationId: advanceWorkflowSprintLead
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WorkflowSprintAdvanceRequest'
+      responses:
+        '200':
+          description: Workflow Hardening Sprint lead advanced to the next state
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WorkflowSprintAdvanceResponse'
+        '400':
+          description: Invalid sprint advancement request
+        '403':
+          description: Forbidden
+  /v1/intents/catalog:
+    get:
+      operationId: listIntentCatalog
+      parameters:
+        - in: query
+          name: mcpProfile
+          schema:
+            type: string
+        - in: query
+          name: bundleId
+          schema:
+            type: string
+        - in: query
+          name: partnerProfile
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Intent catalog with risk and checkpoint metadata
+        '401':
+          description: Unauthorized
+  /v1/intents/plan:
+    post:
+      operationId: planIntent
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/IntentPlanRequest'
+      responses:
+        '200':
+          description: Policy-scoped intent execution plan
+        '400':
+          description: Invalid intent request
+        '401':
+          description: Unauthorized
+  /v1/handoffs/start:
+    post:
+      operationId: startHandoff
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/HandoffStartRequest'
+      responses:
+        '200':
+          description: Sequential handoff started
+        '400':
+          description: Invalid handoff request
+        '401':
+          description: Unauthorized
+  /v1/handoffs/complete:
+    post:
+      operationId: completeHandoff
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/HandoffCompleteRequest'
+      responses:
+        '200':
+          description: Sequential handoff completed
+        '400':
+          description: Invalid handoff completion request
+        '401':
+          description: Unauthorized
+  /v1/internal-agent/bootstrap:
+    post:
+      operationId: bootstrapInternalAgent
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/InternalAgentBootstrapRequest'
+      responses:
+        '200':
+          description: Normalized trigger context, recall pack, sandbox, and reviewer-ready execution plan
+        '400':
+          description: Invalid internal-agent bootstrap request
+        '401':
+          description: Unauthorized
+  /v1/feedback/summary:
+    get:
+      operationId: getFeedbackSummary
+      parameters:
+        - in: query
+          name: recent
+          schema:
+            type: integer
+            default: 20
+      responses:
+        '200':
+          description: Feedback summary text
+        '401':
+          description: Unauthorized
+  /v1/lessons/search:
+    get:
+      operationId: searchLessons
+      parameters:
+        - in: query
+          name: q
+          schema:
+            type: string
+          description: Search query. Leave empty to list recent lessons.
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            default: 10
+        - in: query
+          name: category
+          schema:
+            type: string
+            enum: [error, learning, preference]
+        - in: query
+          name: tags
+          schema:
+            type: string
+          description: Comma-separated tags that must all be present on a lesson.
+      responses:
+        '200':
+          description: Searchable promoted lessons with linked corrective actions, prevention rules, and auto-promoted checks
+        '401':
+          description: Unauthorized
+  /v1/search:
+    get:
+      operationId: searchThumbgate
+      parameters:
+        - in: query
+          name: q
+          schema:
+            type: string
+          description: Search query for raw ThumbGate state.
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            default: 10
+        - in: query
+          name: source
+          schema:
+            type: string
+            enum: [all, feedback, context, rules]
+            default: all
+        - in: query
+          name: signal
+          schema:
+            type: string
+            enum: [up, down, positive, negative]
+      responses:
+        '200':
+          description: Search results across feedback logs, ContextFS, and prevention rules
+        '401':
+          description: Unauthorized
+    post:
+      operationId: searchThumbgatePost
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                query:
+                  type: string
+                q:
+                  type: string
+                limit:
+                  type: integer
+                  default: 10
+                source:
+                  type: string
+                  enum: [all, feedback, context, rules]
+                  default: all
+                signal:
+                  type: string
+                  enum: [up, down, positive, negative]
+      responses:
+        '200':
+          description: Search results across feedback logs, ContextFS, and prevention rules
+        '401':
+          description: Unauthorized
+  /v1/feedback/rules:
+    post:
+      operationId: generatePreventionRules
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                minOccurrences:
+                  type: integer
+                  default: 2
+                outputPath:
+                  type: string
+      responses:
+        '200':
+          description: Prevention rules generated
+        '401':
+          description: Unauthorized
+  /v1/dpo/export:
+    post:
+      operationId: exportDpoPairs
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                inputPath:
+                  type: string
+                memoryLogPath:
+                  type: string
+                outputPath:
+                  type: string
+                async:
+                  type: boolean
+                mode:
+                  type: string
+                  enum: [sync, async]
+                jobId:
+                  type: string
+      responses:
+        '200':
+          description: DPO export completed
+        '202':
+          description: DPO export accepted as a hosted background job
+        '401':
+          description: Unauthorized
+  /v1/documents:
+    get:
+      operationId: listImportedDocuments
+      parameters:
+        - in: query
+          name: query
+          schema:
+            type: string
+        - in: query
+          name: q
+          schema:
+            type: string
+        - in: query
+          name: tag
+          schema:
+            type: string
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            default: 20
+      responses:
+        '200':
+          description: Imported policy and runbook documents
+        '401':
+          description: Unauthorized
+  /v1/documents/import:
+    post:
+      operationId: importDocument
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                filePath:
+                  type: string
+                content:
+                  type: string
+                title:
+                  type: string
+                sourceFormat:
+                  type: string
+                  enum: [markdown, text, yaml, json, html]
+                sourceUrl:
+                  type: string
+                tags:
+                  type: array
+                  items:
+                    type: string
+                proposeGates:
+                  type: boolean
+      responses:
+        '201':
+          description: Document imported
+        '400':
+          description: Invalid document import request
+        '401':
+          description: Unauthorized
+  /v1/documents/{documentId}:
+    get:
+      operationId: getImportedDocument
+      parameters:
+        - in: path
+          name: documentId
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Imported document with proposed gates
+        '401':
+          description: Unauthorized
+        '404':
+          description: Imported document not found
+  /v1/jobs:
+    get:
+      operationId: listHostedJobs
+      parameters:
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            default: 20
+        - in: query
+          name: status
+          schema:
+            type: string
+          description: Optional comma-separated list of job statuses to filter.
+      responses:
+        '200':
+          description: Hosted job states
+        '401':
+          description: Unauthorized
+  /v1/jobs/harness:
+    post:
+      operationId: launchHostedHarness
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [harness]
+              properties:
+                harness:
+                  type: string
+                harnessId:
+                  type: string
+                jobId:
+                  type: string
+                skill:
+                  type: string
+                partnerProfile:
+                  type: string
+                autoImprove:
+                  type: boolean
+                inputs:
+                  type: object
+      responses:
+        '202':
+          description: Hosted harness accepted
+        '401':
+          description: Unauthorized
+  /v1/jobs/{jobId}:
+    get:
+      operationId: getHostedJob
+      parameters:
+        - in: path
+          name: jobId
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Hosted job state
+        '401':
+          description: Unauthorized
+        '404':
+          description: Job not found
+  /v1/jobs/{jobId}/control:
+    post:
+      operationId: controlHostedJob
+      parameters:
+        - in: path
+          name: jobId
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [action]
+              properties:
+                action:
+                  type: string
+                  enum: [pause, cancel, resume]
+                metadata:
+                  type: object
+      responses:
+        '202':
+          description: Hosted job control accepted
+        '401':
+          description: Unauthorized
+        '404':
+          description: Job not found
+        '409':
+          description: Job cannot accept the requested control action
+  /v1/analytics/databricks/export:
+    post:
+      operationId: exportDatabricksBundle
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                outputPath:
+                  type: string
+      responses:
+        '200':
+          description: Databricks bundle exported
+        '401':
+          description: Unauthorized
+  /v1/context/construct:
+    post:
+      operationId: constructContextPack
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                query:
+                  type: string
+                maxItems:
+                  type: integer
+                  default: 8
+                maxChars:
+                  type: integer
+                  default: 6000
+                namespaces:
+                  type: array
+                  items:
+                    type: string
+                    enum:
+                      - raw_history
+                      - memory/error
+                      - memory/learning
+                      - rules
+                      - tools
+                      - provenance
+      responses:
+        '200':
+          description: Context pack created
+        '400':
+          description: Invalid namespace selection
+        '401':
+          description: Unauthorized
+  /v1/context/evaluate:
+    post:
+      operationId: evaluateContextPack
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [packId, outcome]
+              properties:
+                packId:
+                  type: string
+                outcome:
+                  type: string
+                signal:
+                  type: string
+                notes:
+                  type: string
+                rubricScores:
+                  type: array
+                  items:
+                    $ref: '#/components/schemas/RubricScore'
+                guardrails:
+                  type: object
+                  properties:
+                    testsPassed:
+                      type: boolean
+                    pathSafety:
+                      type: boolean
+                    budgetCompliant:
+                      type: boolean
+      responses:
+        '200':
+          description: Evaluation recorded
+        '400':
+          description: Invalid rubric payload
+        '401':
+          description: Unauthorized
+  /v1/context/provenance:
+    get:
+      operationId: getContextProvenance
+      parameters:
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            default: 50
+      responses:
+        '200':
+          description: Recent provenance events
+        '401':
+          description: Unauthorized
+  /v1/billing/checkout:
+    post:
+      operationId: createBillingCheckoutSession
+      security: []
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BillingCheckoutRequest'
+      responses:
+        '200':
+          description: Stripe checkout session created
+  /v1/billing/usage:
+    get:
+      operationId: getBillingUsage
+      responses:
+        '200':
+          description: Usage count for authenticated billing key
+        '401':
+          description: Unauthorized
+  /v1/billing/provision:
+    post:
+      operationId: provisionBillingKey
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BillingProvisionRequest'
+      responses:
+        '200':
+          description: API key provisioned
+        '400':
+          description: Missing required customerId
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden - requires static THUMBGATE_API_KEY admin token
+  /v1/billing/webhook:
+    post:
+      operationId: stripeBillingWebhook
+      security: []
+      responses:
+        '200':
+          description: Webhook accepted
+        '400':
+          description: Invalid webhook signature or payload
+  /v1/billing/github-webhook:
+    post:
+      operationId: githubMarketplaceWebhook
+      security: []
+      responses:
+        '200':
+          description: Webhook accepted
+        '400':
+          description: Invalid webhook signature or payload
+k signature or payload
+  /v1/billing/github-webhook:
+    post:
+      operationId: githubMarketplaceWebhook
+      security: []
+      responses:
+        '200':
+          description: Webhook accepted
+        '400':
+          description: Invalid webhook signature or payload