> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bluee.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Save packages, per-harness overrides, and MCP servers as a new revision



## OpenAPI

````yaml /openapi/next.yaml put /admin/governance-extensions
openapi: 3.1.0
info:
  title: Blue — Service Contract
  version: 0.1.0
  description: >
    The client-side contract the `blue` CLI expects from the provisioned
    service. The reference `control-api` implements it; any BYO service that
    honors these shapes can be swapped in. Gateway-mode inference JWT issuance
    is OPTIONAL — governance-only deployments need only `GET
    /governance-config`. CLI callers use OAuth 2.0 access tokens issued through
    RFC 8628 device authorization; dashboard callers use an HTTP-only Better
    Auth session cookie.
servers:
  - url: https://harness.example.com
    description: Replace with the Control API URL for your deployment.
security:
  - oauthDevice: []
tags:
  - name: System
    description: Service health and authenticated identity.
  - name: Configuration
    description: Personalized governance policy and client reconciliation state.
  - name: Gateway
    description: Per-user managed inference-gateway credential lifecycle.
  - name: Sessions
    description: Raw-session upload, metadata, and download lifecycle.
  - name: Administration
    description: Organization-administrator policy and client operations.
  - name: User management
    description: >-
      Organization user lifecycle, session revocation, and invitation
      operations.
  - name: Identity provisioning
    description: SCIM 2.0 user and group provisioning for an external identity provider.
paths:
  /admin/governance-extensions:
    put:
      tags:
        - Administration
      summary: Save packages, per-harness overrides, and MCP servers as a new revision
      operationId: updateManagedExtensions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateManagedExtensions'
      responses:
        '200':
          description: Saved governance revision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminConfig'
        '409':
          description: Base revision is stale
components:
  schemas:
    UpdateManagedExtensions:
      type: object
      required:
        - base_revision
        - packages
      properties:
        base_revision:
          type: string
          format: uuid
        packages:
          type: array
          items:
            $ref: '#/components/schemas/ManagedPackage'
        package_audiences:
          type: object
          description: >-
            Optional package audiences keyed by selected package ID; omitted
            entries deploy organization-wide.
          additionalProperties:
            $ref: '#/components/schemas/PackageAudience'
        package_overrides:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/PackageOverride'
        mcp:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/McpServer'
    AdminConfig:
      type: object
      required:
        - revision
        - yaml
        - managed_yaml
        - document
        - package_audiences
        - created_at
      properties:
        revision:
          type: string
          format: uuid
          example: 251e6087-98cf-4861-9668-f09f537d5e4d
        yaml:
          type: string
          description: Validated organization policy template
        managed_yaml:
          type: string
          description: Editable policy projection with extension-owned fields omitted
        document:
          $ref: '#/components/schemas/GovernanceConfig'
        package_audiences:
          type: object
          description: >-
            Revision-scoped deployment audience keyed by package ID; absent
            historical records are returned as organization-wide.
          additionalProperties:
            $ref: '#/components/schemas/PackageAudience'
        created_at:
          type: string
          format: date-time
    ManagedPackage:
      type: object
      required:
        - id
        - version
        - source_ref
        - sha256
      properties:
        id:
          type: string
          pattern: ^[a-z0-9-]+$
        name:
          type: string
        version:
          type: string
        source_ref:
          type: string
          description: Immutable HTTPS or local .tar.gz archive
        artifact_id:
          type: string
          format: uuid
          description: Organization-scoped mirrored artifact
        sha256:
          type: string
          pattern: ^[A-Fa-f0-9]{64}$
        platform_sources:
          type: object
          description: >-
            Exact `<os>-<arch>` archive overrides; clients require a matching
            entry when this map is present.
          additionalProperties:
            $ref: '#/components/schemas/PackageSource'
        settings:
          type: object
          additionalProperties: true
        adapters:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PackageAdapter'
    PackageAudience:
      type: object
      required:
        - scope
        - user_ids
      properties:
        scope:
          type: string
          enum:
            - organization
            - users
        user_ids:
          type: array
          uniqueItems: true
          items:
            type: string
            format: uuid
    PackageOverride:
      type: object
      properties:
        enabled:
          type: boolean
        settings:
          type: object
          additionalProperties: true
    McpServer:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        command:
          type: string
        args:
          type: array
          items:
            type: string
        env:
          type: object
          additionalProperties:
            type: string
        url:
          type: string
        transport:
          type: string
        disabled:
          type: boolean
    GovernanceConfig:
      type: object
      required:
        - revision
        - allowed_harnesses
      properties:
        revision:
          type: string
          description: Reconcile key; daemon acts on change
          example: 251e6087-98cf-4861-9668-f09f537d5e4d
        contract_version:
          type: integer
          default: 1
          description: Governance wire contract version
        required_capabilities:
          type: array
          items:
            type: string
            enum:
              - adapter_intervals
              - compiled_harness_registry
              - transactional_reconcile
              - unverified_harness_versions
              - versioned_state
        minimum_client_version:
          type: string
          description: >-
            Operator-visible rollout floor; required capabilities enforce
            compatibility
        ttl_seconds:
          type: integer
          description: Client cache TTL (default 300)
          example: 300
        required:
          type: boolean
          description: If true, client fails closed without fresh config
        allowed_harnesses:
          type: array
          items:
            type: string
            description: Harness key from the compiled registry
        harnesses:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/HarnessPolicy'
        packages:
          type: array
          items:
            $ref: '#/components/schemas/ManagedPackage'
        gateway:
          $ref: '#/components/schemas/GatewayConfig'
        session_upload:
          $ref: '#/components/schemas/SessionUploadConfig'
        telemetry:
          type: object
          properties:
            sink_url:
              type: string
    PackageSource:
      type: object
      required:
        - source_ref
        - sha256
      properties:
        source_ref:
          type: string
          description: Immutable HTTPS or local .tar.gz archive
        artifact_id:
          type: string
          format: uuid
          description: Organization-scoped mirrored artifact
        sha256:
          type: string
          pattern: ^[A-Fa-f0-9]{64}$
    PackageAdapter:
      type: object
      description: >
        All paths are archive-root-relative. skills_dir may identify an exact
        skill folder or a collection of skill folders. Codex/Claude agents and
        hooks require plugin_dir; OpenCode hooks are declared as plugin modules.
      properties:
        introduced:
          type: string
          description: >-
            Inclusive harness-version lower bound for adapter availability;
            defaults to 0.0.0
        before:
          type: string
          description: Exclusive harness-version upper bound for adapter availability
        plugin_dir:
          type: string
        skills_dir:
          type: string
        agents_dir:
          type: string
        hooks_file:
          type: string
        plugins:
          type: array
          items:
            type: string
        helpers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PlatformAsset'
        variants:
          type: array
          description: >-
            Ordered half-open layouts selected within adapter availability;
            intervals must not overlap or leave gaps without a fallback.
          items:
            $ref: '#/components/schemas/PackageAdapterVariant'
    HarnessPolicy:
      type: object
      properties:
        version_requirement:
          type: string
          description: Semver range required for the locally installed harness
        allow_unverified_versions:
          type: boolean
          default: false
          description: >-
            Permit matching releases beyond Blue's certified ceiling; requires
            version_requirement
        managed_config:
          $ref: '#/components/schemas/ManagedConfig'
        mcp:
          type: array
          description: >
            Additive MCP suggestions. An enabled entry is installed only when
            the local harness has no MCP with the same name; existing local MCPs
            are never overwritten, disabled, or removed.
          items:
            $ref: '#/components/schemas/McpServer'
        package_overrides:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PackageOverride'
    GatewayConfig:
      type: object
      required:
        - type
      description: >
        Present ⇒ gateway mode for every allowed harness; omit ⇒
        governance-only. proxy_url and token are runtime fields injected by the
        control API when it delivers the policy to an authenticated client.
      properties:
        type:
          type: string
          description: Deployment-defined gateway adapter identifier.
        proxy_url:
          type: string
          description: Runtime inference proxy URL injected at delivery time
        token:
          type: string
          description: >
            Runtime-only, session-bound inference JWT. The inference proxy
            validates it and swaps it for an upstream gateway credential. The
            control API injects it into the authenticated client's config
            response and never persists it.
        auth_style:
          type: string
          enum:
            - bearer
          default: bearer
          description: >-
            Client-to-proxy authentication style; bearer is the only supported
            value.
    SessionUploadConfig:
      type: object
      required:
        - presign_url
      description: >
        Global opt-in portable-session capture. When present, every compatible
        supported harness registers its native hook. The authenticated endpoint
        returns a short-lived provider-specific blob upload request.
      properties:
        presign_url:
          type: string
          format: uri
    PlatformAsset:
      type: object
      properties:
        paths:
          type: object
          description: Archive paths keyed by os-architecture, with optional default.
          additionalProperties:
            type: string
    PackageAdapterVariant:
      type: object
      required:
        - introduced
      properties:
        introduced:
          type: string
          description: Inclusive semantic-version lower bound
        before:
          type: string
          description: Exclusive semantic-version upper bound; omit for open-ended
        plugin_dir:
          type: string
        skills_dir:
          type: string
        agents_dir:
          type: string
        hooks_file:
          type: string
        plugins:
          type: array
          items:
            type: string
        helpers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PlatformAsset'
    ManagedConfig:
      type: object
      description: Known keys are typed; unknown keys are preserved forward-compatibly.
      properties:
        model:
          type: string
        approval_policy:
          type: string
        sandbox_mode:
          type: string
        auto_approve:
          type: boolean
        reasoning_effort:
          type: string
          description: Harness model thinking/reasoning effort, such as medium.
        fast_mode:
          type: boolean
          description: >-
            Whether accelerated service-tier selection is available; Codex maps
            false to features.fast_mode=false and service_tier=default.
      additionalProperties: true
  securitySchemes:
    oauthDevice:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        OAuth 2.0 access token obtained through RFC 8628 at
        /api/auth/device/code and /api/auth/oauth2/token. The API enforces
        governance:read, session:write, and client-status:write as appropriate.

````