fix(openapi): resolve lint errors and add lefthook pre-commit check

- Move ConfigBackupEnvelope from securitySchemes to its own schema file
- Fix adapter property nesting in ProviderConfig (was outside properties block)
- Fix  to use split-spec relative paths in backup/restore paths
- Remove invalid description sibling of  in restore path
- Add openapi-lint lefthook command for docs/openapi/ changes

Author: mcowger

docs/openapi/components/schemas/ConfigBackupEnvelope.yaml

@@ -0,0 +1,79 @@
+type: object
+required:
+  - plexus_backup
+  - version
+  - created_at
+  - data
+properties:
+  plexus_backup:
+    type: boolean
+    const: true
+  version:
+    type: integer
+    description: Schema version for forward-compatible migration.
+    const: 1
+  created_at:
+    type: string
+    format: date-time
+    description: ISO 8601 timestamp of when the backup was created.
+  dialect:
+    type: string
+    enum: [sqlite, postgres]
+    description: Source database dialect (informational; not used on import).
+  data:
+    type: object
+    description: All configuration tables.
+    required:
+      - providers
+      - models
+      - keys
+      - user_quotas
+      - mcp_servers
+      - settings
+      - oauth_credentials
+    properties:
+      providers:
+        type: object
+        additionalProperties: true
+        description: Map of provider slug to provider configuration.
+      models:
+        type: object
+        additionalProperties: true
+        description: Map of model alias slug to model configuration.
+      keys:
+        type: object
+        additionalProperties: true
+        description: Map of key name to API key configuration.
+      user_quotas:
+        type: object
+        additionalProperties: true
+        description: Map of quota name to quota definition.
+      mcp_servers:
+        type: object
+        additionalProperties: true
+        description: Map of MCP server name to server configuration.
+      settings:
+        type: object
+        additionalProperties: true
+        description: Map of setting key to value.
+      oauth_credentials:
+        type: array
+        items:
+          type: object
+          required:
+            - provider_type
+            - account_id
+            - access_token
+            - refresh_token
+            - expires_at
+          properties:
+            provider_type:
+              type: string
+            account_id:
+              type: string
+            access_token:
+              type: string
+            refresh_token:
+              type: string
+            expires_at:
+              type: number

docs/openapi/components/schemas/ProviderConfig.yaml

@@ -104,7 +104,7 @@ properties:
               type: object
               additionalProperties: true
               description: Extra fields merged into the request body for this model.
-          adapter:
+            adapter:
               oneOf:
                 - type: string
                 - type: array

docs/openapi/openapi.yaml

@@ -539,84 +539,3 @@ components:
       description: |
         Either the server's `ADMIN_KEY` (full admin access) or the plaintext
         secret of a configured API key (limited access, scoped to that key).
-    schemas:
-      ConfigBackupEnvelope:
-        type: object
-        required:
-          - plexus_backup
-          - version
-          - created_at
-          - data
-        properties:
-          plexus_backup:
-            type: boolean
-            const: true
-          version:
-            type: integer
-            description: Schema version for forward-compatible migration.
-            const: 1
-          created_at:
-            type: string
-            format: date-time
-            description: ISO 8601 timestamp of when the backup was created.
-          dialect:
-            type: string
-            enum: [sqlite, postgres]
-            description: Source database dialect (informational; not used on import).
-          data:
-            type: object
-            description: All configuration tables.
-            required:
-              - providers
-              - models
-              - keys
-              - user_quotas
-              - mcp_servers
-              - settings
-              - oauth_credentials
-            properties:
-              providers:
-                type: object
-                additionalProperties: true
-                description: Map of provider slug to provider configuration.
-              models:
-                type: object
-                additionalProperties: true
-                description: Map of model alias slug to model configuration.
-              keys:
-                type: object
-                additionalProperties: true
-                description: Map of key name to API key configuration.
-              user_quotas:
-                type: object
-                additionalProperties: true
-                description: Map of quota name to quota definition.
-              mcp_servers:
-                type: object
-                additionalProperties: true
-                description: Map of MCP server name to server configuration.
-              settings:
-                type: object
-                additionalProperties: true
-                description: Map of setting key to value.
-              oauth_credentials:
-                type: array
-                items:
-                  type: object
-                  required:
-                    - provider_type
-                    - account_id
-                    - access_token
-                    - refresh_token
-                    - expires_at
-                  properties:
-                    provider_type:
-                      type: string
-                    account_id:
-                      type: string
-                    access_token:
-                      type: string
-                    refresh_token:
-                      type: string
-                    expires_at:
-                      type: number

docs/openapi/paths/v0_management_backup.yaml

@@ -37,7 +37,7 @@ get:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/ConfigBackupEnvelope'
+            $ref: ../components/schemas/ConfigBackupEnvelope.yaml
         application/gzip:
           schema:
             type: string

docs/openapi/paths/v0_management_restore.yaml

@@ -31,8 +31,7 @@ post:
     content:
       application/json:
         schema:
-          $ref: '#/components/schemas/ConfigBackupEnvelope'
-        description: Config-only backup envelope.
+          $ref: ../components/schemas/ConfigBackupEnvelope.yaml
       application/octet-stream:
         schema:
           type: string

lefthook.yml

@@ -55,6 +55,11 @@ pre-commit:
       glob: "packages/frontend/src/**"
       run: bun run build:frontend
 
+    # --- OpenAPI spec lint (only when OpenAPI docs change) -----------------
+    openapi-lint:
+      glob: "docs/openapi/**"
+      run: bun run lint:openapi
+
     # --- Backend tests (only when backend source changes) --------------------
     backend-tests:
       glob: "packages/backend/src/**"