// Package apidocs Code generated by swaggo/swag. DO NOT EDIT
package apidocs

import "github.com/swaggo/swag"

const docTemplate = `{
    "schemes": {{ marshal .Schemes }},
    "swagger": "2.0",
    "info": {
        "description": "{{escape .Description}}",
        "title": "{{.Title}}",
        "contact": {},
        "version": "{{.Version}}"
    },
    "host": "{{.Host}}",
    "basePath": "{{.BasePath}}",
    "paths": {
        "/admin/api-gateway/connections/{name}/oauth-start": {
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Generates a PKCE verifier, derives the SHA256 challenge, registers a state token, and returns the authorization URL the operator should open in their browser. The upstream IdP redirects back to /api/v1/admin/api-gateway/oauth/callback after the user authenticates.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Begin OAuth authorization-code flow for an API gateway connection",
                "parameters": [
                    {
                        "type": "string",
                        "description": "API gateway connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Optional return URL",
                        "name": "body",
                        "in": "body",
                        "schema": {
                            "$ref": "#/definitions/admin.startGatewayOAuthRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.startGatewayOAuthResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/api-gateway/oauth/callback": {
            "get": {
                "description": "Public endpoint hit by the upstream IdP after the operator authenticates. Exchanges the code for tokens and persists them via the API gateway's TokenStore. Renders an HTML error page on failure so a stranded browser tab still gives a useful message.",
                "produces": [
                    "text/html"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "OAuth authorization-code callback for API gateway connections",
                "parameters": [
                    {
                        "type": "string",
                        "description": "OAuth authorization code",
                        "name": "code",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "PKCE state token from oauth-start",
                        "name": "state",
                        "in": "query",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "OAuth error code from upstream",
                        "name": "error",
                        "in": "query"
                    }
                ],
                "responses": {
                    "302": {
                        "description": "Found"
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/audit/events": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns paginated audit events with optional filtering.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Audit"
                ],
                "summary": "List audit events",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Filter by user ID",
                        "name": "user_id",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by tool name",
                        "name": "tool_name",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by toolkit kind (e.g. api, trino, datahub, s3, memory)",
                        "name": "toolkit_kind",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by event source (e.g. mcp)",
                        "name": "source",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by MCP session ID",
                        "name": "session_id",
                        "in": "query"
                    },
                    {
                        "type": "boolean",
                        "description": "Filter by success/failure",
                        "name": "success",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Events after this time (RFC 3339)",
                        "name": "start_time",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Events before this time (RFC 3339)",
                        "name": "end_time",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Sort column (default: timestamp)",
                        "name": "sort_by",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Sort direction: asc, desc (default: desc)",
                        "name": "sort_order",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Page number, 1-based (default: 1)",
                        "name": "page",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Results per page (default: 50)",
                        "name": "per_page",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.auditEventResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/audit/events/filters": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns unique user IDs and tool names seen in the audit log, sorted alphabetically.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Audit"
                ],
                "summary": "Get audit event filter values",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Events after this time (RFC 3339)",
                        "name": "start_time",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Events before this time (RFC 3339)",
                        "name": "end_time",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.auditFiltersResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/audit/events/{id}": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns a single audit event by ID.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Audit"
                ],
                "summary": "Get audit event",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Audit event ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/audit.Event"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/audit/metrics/breakdown": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns audit event counts grouped by a dimension.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Audit"
                ],
                "summary": "Get audit breakdown",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Dimension: tool_name, user_id, persona, toolkit_kind, connection",
                        "name": "group_by",
                        "in": "query",
                        "required": true
                    },
                    {
                        "type": "integer",
                        "description": "Max entries (default: 10, max: 100)",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Start time (RFC 3339)",
                        "name": "start_time",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "End time (RFC 3339)",
                        "name": "end_time",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/audit.BreakdownEntry"
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/audit/metrics/discovery": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns discovery-before-query session pattern statistics.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Audit"
                ],
                "summary": "Get discovery pattern metrics",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Start time (RFC 3339)",
                        "name": "start_time",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "End time (RFC 3339)",
                        "name": "end_time",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/audit.DiscoveryStats"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/audit/metrics/enrichment": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns aggregate enrichment statistics including mode breakdown and token savings.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Audit"
                ],
                "summary": "Get enrichment metrics",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Start time (RFC 3339)",
                        "name": "start_time",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "End time (RFC 3339)",
                        "name": "end_time",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/audit.EnrichmentStats"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/audit/metrics/overview": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns aggregate audit statistics for the given time range.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Audit"
                ],
                "summary": "Get audit overview",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Start time (RFC 3339)",
                        "name": "start_time",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "End time (RFC 3339)",
                        "name": "end_time",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/audit.Overview"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/audit/metrics/performance": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns latency percentile statistics for the given time range.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Audit"
                ],
                "summary": "Get audit performance",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Start time (RFC 3339)",
                        "name": "start_time",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "End time (RFC 3339)",
                        "name": "end_time",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/audit.PerformanceStats"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/audit/metrics/timeseries": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns audit event counts bucketed by time resolution.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Audit"
                ],
                "summary": "Get audit timeseries",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Time bucket resolution: minute, hour, day (default: hour)",
                        "name": "resolution",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Start time (RFC 3339)",
                        "name": "start_time",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "End time (RFC 3339)",
                        "name": "end_time",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/audit.TimeseriesBucket"
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/audit/stats": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns aggregate counts for total, successful, and failed events. Supports time and filter parameters.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Audit"
                ],
                "summary": "Get audit stats",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Filter by user ID",
                        "name": "user_id",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by tool name",
                        "name": "tool_name",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by toolkit kind",
                        "name": "toolkit_kind",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by event source",
                        "name": "source",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Events after this time (RFC 3339)",
                        "name": "start_time",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Events before this time (RFC 3339)",
                        "name": "end_time",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.auditStatsResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/auth/keys": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns all API keys (key values are never exposed, only names and roles).",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Auth Keys"
                ],
                "summary": "List auth keys",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.authKeyListResponse"
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Generates a new API key. The key value is returned only once.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Auth Keys"
                ],
                "summary": "Create auth key",
                "parameters": [
                    {
                        "description": "Key definition",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.authKeyCreateRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "$ref": "#/definitions/admin.authKeyCreateResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/auth/keys/{name}": {
            "delete": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Deletes an API key.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Auth Keys"
                ],
                "summary": "Delete auth key",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Key name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.statusResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/config": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns the current configuration as JSON with sensitive values redacted.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Config"
                ],
                "summary": "Get config",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/config/export": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns the current configuration as downloadable YAML. Sensitive values are redacted by default.",
                "produces": [
                    "application/x-yaml"
                ],
                "tags": [
                    "Config"
                ],
                "summary": "Export config",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Set to 'true' to include sensitive values",
                        "name": "secrets",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "string"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/config/mode": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns the current config store mode (file or database).",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Config"
                ],
                "summary": "Get config mode",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.configModeResponse"
                        }
                    }
                }
            }
        },
        "/admin/connection-instances": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns all database-managed connection instances.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "List connection instances",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/platform.ConnectionInstance"
                            }
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/connection-instances/{kind}/{name}": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns a single database-managed connection instance by kind and name.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Get connection instance",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Toolkit kind (trino, datahub, s3)",
                        "name": "kind",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Instance name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/platform.ConnectionInstance"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Creates or updates a database-managed connection instance.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Create or update connection instance",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Toolkit kind (trino, datahub, s3)",
                        "name": "kind",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Instance name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Connection instance data",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.setConnectionInstanceRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/platform.ConnectionInstance"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            },
            "delete": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Deletes a database-managed connection instance.",
                "tags": [
                    "Connections"
                ],
                "summary": "Delete connection instance",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Toolkit kind (trino, datahub, s3)",
                        "name": "kind",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Instance name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "204": {
                        "description": "No Content"
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/connections": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns all toolkit connections with their tools.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "System"
                ],
                "summary": "List connections",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.connectionListResponse"
                        }
                    }
                }
            }
        },
        "/admin/connections/oauth-health": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Single-shot per-connection OAuth health used by the connection-list view to render a per-row health badge. Returns has_oauth=false for non-OAuth connections so the UI doesn't have to filter client-side.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Bulk OAuth health for all connections",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.connectionsOAuthHealthResponse"
                        }
                    }
                }
            }
        },
        "/admin/connections/{kind}/{name}/auth-events": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "OAuth lifecycle history for a connection",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Connection kind",
                        "name": "kind",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/authevents.Event"
                            }
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/connections/{kind}/{name}/oauth-start": {
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Validates the connection is configured for authorization_code OAuth, generates a PKCE verifier, registers a state token (with kind), and returns the authorization URL the operator should open in their browser. Works for any connection kind registered in OAuthKinds.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Begin OAuth authorization-code flow for any connection",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Connection kind (mcp, api)",
                        "name": "kind",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Optional return URL",
                        "name": "body",
                        "in": "body",
                        "schema": {
                            "$ref": "#/definitions/admin.startConnectionOAuthRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.startConnectionOAuthResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/connections/{kind}/{name}/oauth-status": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "OAuth status for a connection",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Connection kind",
                        "name": "kind",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/connoauth.OAuthStatus"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/connections/{kind}/{name}/reacquire-oauth": {
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Force a refresh-token exchange for a connection",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Connection kind",
                        "name": "kind",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "502": {
                        "description": "Bad Gateway",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/embedding/status": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns the configured embedding provider's kind, model, dimension, and a status enum (ok / unconfigured). Used by the portal to surface a banner when semantic features are disabled.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "System"
                ],
                "summary": "Get embedding provider status",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.embeddingProviderStatusResponse"
                        }
                    }
                }
            }
        },
        "/admin/gateway/connections/{name}/enrichment-rules": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "List enrichment rules for a connection",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Gateway connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Filter by proxied tool name",
                        "name": "tool_name",
                        "in": "query"
                    },
                    {
                        "type": "boolean",
                        "description": "Only return enabled rules",
                        "name": "enabled_only",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/enrichment.Rule"
                            }
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Create an enrichment rule",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Gateway connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Rule",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.enrichmentRuleBody"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "$ref": "#/definitions/enrichment.Rule"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/gateway/connections/{name}/enrichment-rules/{id}": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Get an enrichment rule",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Gateway connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Rule id",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/enrichment.Rule"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Update an enrichment rule",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Gateway connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Rule id",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Rule",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.enrichmentRuleBody"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/enrichment.Rule"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            },
            "delete": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Delete an enrichment rule",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Gateway connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Rule id",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "204": {
                        "description": "No Content"
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/gateway/connections/{name}/enrichment-rules/{id}/dry-run": {
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Loads the rule, applies it against the provided sample args/response/user without persisting and without invoking the live gateway, and returns the merged response + per-rule trace. Use this in the rule editor to validate bindings and merge strategy.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Dry-run a single enrichment rule",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Gateway connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Rule id",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Sample call",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.dryRunEnrichmentRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.dryRunEnrichmentResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/gateway/connections/{name}/oauth-start": {
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Generates a PKCE verifier, derives the SHA256 challenge, registers a state token, and returns the authorization URL the operator should open in their browser. The platform expects the upstream to redirect to /api/v1/admin/oauth/callback after the user authenticates.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Begin OAuth authorization-code flow for a gateway connection",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Gateway connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Optional return URL",
                        "name": "body",
                        "in": "body",
                        "schema": {
                            "$ref": "#/definitions/admin.startGatewayOAuthRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.startGatewayOAuthResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/gateway/connections/{name}/reacquire-oauth": {
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Triggers a client_credentials grant against the configured OAuth token URL, replacing the cached token. Used to recover from upstream-side credential rotations or to verify the configured client_id/client_secret without waiting for token expiry.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Force a fresh OAuth token exchange",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Gateway connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/gateway.ConnectionStatus"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "502": {
                        "description": "Bad Gateway",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/gateway/connections/{name}/refresh": {
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Re-dials a configured gateway connection using the stored config, re-discovers its tool set, and swaps the live connection atomically. Used after an upstream adds, removes, or changes tools.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Refresh a live gateway connection",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Gateway connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.refreshGatewayConnectionResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "502": {
                        "description": "Bad Gateway",
                        "schema": {
                            "$ref": "#/definitions/admin.refreshGatewayConnectionResponse"
                        }
                    }
                }
            }
        },
        "/admin/gateway/connections/{name}/status": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Reports whether the connection is healthy, its tool count, and (when AuthMode=oauth) the current token state — expiry, last refreshed, last error.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Get a gateway connection's runtime status",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Gateway connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/gateway.ConnectionStatus"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/gateway/connections/{name}/test": {
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Tests a gateway connection by listing its tools. When a connection with this name is already registered in the live toolkit AND has an active upstreamClient, the request body is IGNORED and the live client (with its loaded TokenStore + auth round-tripper) is exercised — green proves real tool calls would work right now. When no live client exists for this name (the connection is unregistered, OR it's a placeholder awaiting first OAuth Connect, OR a prior dial left it without a client), falls back to a one-shot dial against the submitted config (preview-before-save semantics). The redacted-field merge from the stored config only applies to the fallback path. Does not persist anything.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "Test a gateway connection config",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Gateway connection name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Config to test",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.testGatewayConnectionRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.testGatewayConnectionResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "502": {
                        "description": "Bad Gateway",
                        "schema": {
                            "$ref": "#/definitions/admin.testGatewayConnectionResponse"
                        }
                    }
                }
            }
        },
        "/admin/knowledge/changesets": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns paginated changesets with optional filtering.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Knowledge"
                ],
                "summary": "List changesets",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Filter by entity URN",
                        "name": "entity_urn",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by applier",
                        "name": "applied_by",
                        "in": "query"
                    },
                    {
                        "type": "boolean",
                        "description": "Filter by rollback state",
                        "name": "rolled_back",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Changesets after this time (RFC 3339)",
                        "name": "since",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Changesets before this time (RFC 3339)",
                        "name": "until",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Page number, 1-based (default: 1)",
                        "name": "page",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Results per page (default: 20)",
                        "name": "per_page",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.changesetListResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/knowledge/changesets/{id}": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns a single changeset by ID.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Knowledge"
                ],
                "summary": "Get changeset",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Changeset ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/knowledge.Changeset"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/knowledge/changesets/{id}/rollback": {
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Rolls back a changeset, restoring previous values to DataHub.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Knowledge"
                ],
                "summary": "Rollback changeset",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Changeset ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.statusResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/knowledge/insights": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns paginated insights with optional filtering.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Knowledge"
                ],
                "summary": "List insights",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Filter by status",
                        "name": "status",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by category",
                        "name": "category",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by entity URN",
                        "name": "entity_urn",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by capturer",
                        "name": "captured_by",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by confidence level",
                        "name": "confidence",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Insights after this time (RFC 3339)",
                        "name": "since",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Insights before this time (RFC 3339)",
                        "name": "until",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Page number, 1-based (default: 1)",
                        "name": "page",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Results per page (default: 20)",
                        "name": "per_page",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.insightListResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/knowledge/insights/stats": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns aggregated insight statistics by entity, category, confidence, and status.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Knowledge"
                ],
                "summary": "Get insight stats",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Filter by status",
                        "name": "status",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by category",
                        "name": "category",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by entity URN",
                        "name": "entity_urn",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by capturer",
                        "name": "captured_by",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by confidence level",
                        "name": "confidence",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Insights after this time (RFC 3339)",
                        "name": "since",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Insights before this time (RFC 3339)",
                        "name": "until",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/knowledge.InsightStats"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/knowledge/insights/{id}": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns a single insight by ID.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Knowledge"
                ],
                "summary": "Get insight",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Insight ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/knowledge.Insight"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Update insight text, category, or confidence. Cannot edit an applied insight.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Knowledge"
                ],
                "summary": "Update insight",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Insight ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Fields to update",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.insightUpdateRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.statusResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/knowledge/insights/{id}/status": {
            "put": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Approve or reject an insight. Status must be 'approved' or 'rejected'.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Knowledge"
                ],
                "summary": "Update insight status",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Insight ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Status update",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.statusUpdateRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.statusResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/memory/records": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns paginated memory records with optional filtering.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Memory"
                ],
                "summary": "List memory records",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Filter by persona",
                        "name": "persona",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by dimension",
                        "name": "dimension",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by category",
                        "name": "category",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by status",
                        "name": "status",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by source",
                        "name": "source",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by entity URN",
                        "name": "entity_urn",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by creator",
                        "name": "created_by",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Records after this time (RFC 3339)",
                        "name": "since",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Records before this time (RFC 3339)",
                        "name": "until",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Page number, 1-based (default: 1)",
                        "name": "page",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Results per page (default: 20)",
                        "name": "per_page",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.memoryListResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/memory/records/stats": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns aggregated memory record statistics by dimension, category, and status.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Memory"
                ],
                "summary": "Get memory record stats",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Filter by persona",
                        "name": "persona",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by dimension",
                        "name": "dimension",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by category",
                        "name": "category",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by status",
                        "name": "status",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by source",
                        "name": "source",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by entity URN",
                        "name": "entity_urn",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by creator",
                        "name": "created_by",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Records after this time (RFC 3339)",
                        "name": "since",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Records before this time (RFC 3339)",
                        "name": "until",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.memoryStatsResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/memory/records/{id}": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns a single memory record by ID.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Memory"
                ],
                "summary": "Get memory record",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Record ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/memory.Record"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Update content, category, confidence, dimension, or metadata on a record.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Memory"
                ],
                "summary": "Update memory record",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Record ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Fields to update",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.memoryUpdateRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.statusResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            },
            "delete": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Soft-deletes a memory record by setting its status to archived.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Memory"
                ],
                "summary": "Archive memory record",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Record ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.statusResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/oauth/callback": {
            "get": {
                "description": "Public endpoint hit by the upstream OAuth provider after the operator authenticates. Exchanges the code for tokens and stores them. Renders an HTML page on error so a stranded browser tab still gives a useful message.",
                "produces": [
                    "text/html"
                ],
                "tags": [
                    "Connections"
                ],
                "summary": "OAuth authorization-code callback",
                "parameters": [
                    {
                        "type": "string",
                        "description": "OAuth authorization code",
                        "name": "code",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "PKCE state token from oauth-start",
                        "name": "state",
                        "in": "query",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "OAuth error code from upstream",
                        "name": "error",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Human-readable error from upstream",
                        "name": "error_description",
                        "in": "query"
                    }
                ],
                "responses": {
                    "302": {
                        "description": "Found"
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/personas": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns all configured personas with tool counts.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Personas"
                ],
                "summary": "List personas",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.personaListResponse"
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Creates a new persona. Only available in database config mode.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Personas"
                ],
                "summary": "Create persona",
                "parameters": [
                    {
                        "description": "Persona definition",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.personaCreateRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "$ref": "#/definitions/admin.personaDetail"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/personas/{name}": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns a single persona with resolved tool list.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Personas"
                ],
                "summary": "Get persona",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Persona name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.personaDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Updates an existing persona. Only available in database config mode.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Personas"
                ],
                "summary": "Update persona",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Persona name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Persona definition",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.personaCreateRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.personaDetail"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            },
            "delete": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Deletes a persona. Only available in database config mode. Cannot delete the admin persona.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Personas"
                ],
                "summary": "Delete persona",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Persona name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.statusResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/personas/{name}/test-access": {
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Evaluates the named persona's allow/deny rules against a tool name and returns the decision plus the matching pattern. Used by the admin Tools page to preview \"would persona X allow this tool?\" without traversing every persona.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Personas"
                ],
                "summary": "Preview a persona's decision for a tool",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Persona name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Tool to evaluate",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.testPersonaAccessRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.testPersonaAccessResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/system/info": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns platform identity, version, runtime feature availability, and config mode.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "System"
                ],
                "summary": "Get system info",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.systemInfoResponse"
                        }
                    }
                }
            }
        },
        "/admin/tools": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns all registered tools across all toolkits and platform-level tools.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "System"
                ],
                "summary": "List tools",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.toolListResponse"
                        }
                    }
                }
            }
        },
        "/admin/tools/call": {
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Executes a tool via the MCP server and returns the result.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Tools"
                ],
                "summary": "Call a tool",
                "parameters": [
                    {
                        "description": "Tool call request",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.toolCallRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.toolCallResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/tools/schemas": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns JSON schemas for all registered tools including parameter definitions.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Tools"
                ],
                "summary": "Get tool schemas",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.toolSchemaResponse"
                        }
                    }
                }
            }
        },
        "/admin/tools/{name}": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns everything the admin Tools page needs to render a single tool: kind, toolkit, connection, schema, per-persona allow/deny matrix with matched pattern, hidden state, description-override status, recent audit aggregate, and enrichment-rule count for gateway-proxied tools.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Tools"
                ],
                "summary": "Get aggregating tool detail",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Tool name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.ToolDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/admin/tools/{name}/visibility": {
            "put": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Adds or removes the named tool from the platform-wide tools.deny list. The deny list controls visibility in tools/list responses; persona auth gates execution independently. Read-modify-write through the standard config_entries store, so the value is JSON-encoded as []string and persists across restarts.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Tools"
                ],
                "summary": "Toggle a tool's global visibility",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Tool name",
                        "name": "name",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Visibility toggle",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.toolVisibilityRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/admin.toolVisibilityResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/admin.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/activity/breakdown": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns activity breakdown grouped by a dimension (tool_name, user_id, persona, toolkit_kind, or connection).",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Activity"
                ],
                "summary": "Get activity breakdown",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Grouping dimension (default: tool_name)",
                        "name": "group_by",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Maximum entries to return",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Start time (RFC 3339)",
                        "name": "start_time",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "End time (RFC 3339)",
                        "name": "end_time",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/audit.BreakdownEntry"
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/activity/overview": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns aggregate activity metrics for the current user within an optional time range.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Activity"
                ],
                "summary": "Get activity overview",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Start time (RFC 3339)",
                        "name": "start_time",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "End time (RFC 3339)",
                        "name": "end_time",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/audit.Overview"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/activity/timeseries": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns time-bucketed activity data for the current user.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Activity"
                ],
                "summary": "Get activity timeseries",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Bucket resolution: minute, hour, day (default: hour)",
                        "name": "resolution",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Start time (RFC 3339)",
                        "name": "start_time",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "End time (RFC 3339)",
                        "name": "end_time",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/audit.TimeseriesBucket"
                            }
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/assets": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns paginated assets owned by the current user with optional filtering.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Assets"
                ],
                "summary": "List assets",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Filter by content type",
                        "name": "content_type",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by tag",
                        "name": "tag",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Results per page (default: 20)",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Offset for pagination (default: 0)",
                        "name": "offset",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.paginatedResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Creates a new asset by uploading inline text content (markdown, HTML, SVG, JSON, etc.). Use this to snapshot generated content into the asset portal without going through the MCP save_artifact tool.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Assets"
                ],
                "summary": "Create asset from inline content",
                "parameters": [
                    {
                        "description": "Asset content and metadata",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/portal.createAssetRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "$ref": "#/definitions/portal.Asset"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "413": {
                        "description": "Request Entity Too Large",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "415": {
                        "description": "Unsupported Media Type",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "503": {
                        "description": "Service Unavailable",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/assets/{id}": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns a single asset by ID. Non-owners need share access.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Assets"
                ],
                "summary": "Get asset",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Asset ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.assetResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "410": {
                        "description": "Gone",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Updates the asset's name, description, or tags. Only the owner can update.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Assets"
                ],
                "summary": "Update asset metadata",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Asset ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Fields to update",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/portal.updateAssetRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.statusResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            },
            "delete": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Soft-deletes an asset. Only the owner can delete.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Assets"
                ],
                "summary": "Delete asset",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Asset ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.statusResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/assets/{id}/content": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Downloads the asset's binary content from S3.",
                "produces": [
                    "application/octet-stream"
                ],
                "tags": [
                    "Assets"
                ],
                "summary": "Get asset content",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Asset ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "file"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "410": {
                        "description": "Gone",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "503": {
                        "description": "Service Unavailable",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Uploads new binary content for the asset, creating a new version.",
                "consumes": [
                    "application/octet-stream"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Assets"
                ],
                "summary": "Update asset content",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Asset ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Change summary for the new version",
                        "name": "X-Change-Summary",
                        "in": "header"
                    },
                    {
                        "description": "Raw file content",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "type": "array",
                            "items": {
                                "type": "integer"
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.statusResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "410": {
                        "description": "Gone",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "413": {
                        "description": "Request Entity Too Large",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "503": {
                        "description": "Service Unavailable",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/assets/{id}/copy": {
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Creates an independent copy of a shared asset in the current user's My Assets.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Assets"
                ],
                "summary": "Copy asset",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Asset ID to copy",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "$ref": "#/definitions/portal.Asset"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "410": {
                        "description": "Gone",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "413": {
                        "description": "Request Entity Too Large",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "503": {
                        "description": "Service Unavailable",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/assets/{id}/shares": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns all shares for an asset. Only the owner can view shares.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Shares"
                ],
                "summary": "List asset shares",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Asset ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/portal.Share"
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Creates a share link or user-targeted share for an asset. Only the owner can share.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Shares"
                ],
                "summary": "Create asset share",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Asset ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Share configuration",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/portal.createShareRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "$ref": "#/definitions/portal.shareResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/assets/{id}/thumbnail": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Downloads the asset's PNG thumbnail image.",
                "produces": [
                    "image/png"
                ],
                "tags": [
                    "Assets"
                ],
                "summary": "Get asset thumbnail",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Asset ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "file"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "410": {
                        "description": "Gone",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "503": {
                        "description": "Service Unavailable",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Uploads a PNG thumbnail image for the asset.",
                "consumes": [
                    "image/png"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Assets"
                ],
                "summary": "Upload asset thumbnail",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Asset ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "PNG image data",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "type": "array",
                            "items": {
                                "type": "integer"
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.statusResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "410": {
                        "description": "Gone",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "413": {
                        "description": "Request Entity Too Large",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "503": {
                        "description": "Service Unavailable",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/assets/{id}/versions": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns paginated version history for an asset.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Assets"
                ],
                "summary": "List asset versions",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Asset ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "integer",
                        "description": "Results per page (default: 20)",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Offset for pagination (default: 0)",
                        "name": "offset",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.paginatedResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "410": {
                        "description": "Gone",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/assets/{id}/versions/{version}/content": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Downloads the binary content of a specific asset version.",
                "produces": [
                    "application/octet-stream"
                ],
                "tags": [
                    "Assets"
                ],
                "summary": "Get version content",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Asset ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "integer",
                        "description": "Version number",
                        "name": "version",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "file"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "410": {
                        "description": "Gone",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "503": {
                        "description": "Service Unavailable",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/assets/{id}/versions/{version}/revert": {
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Reverts the asset content to a specific version by creating a new version with that content.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Assets"
                ],
                "summary": "Revert to version",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Asset ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "type": "integer",
                        "description": "Version number to revert to",
                        "name": "version",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "410": {
                        "description": "Gone",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "503": {
                        "description": "Service Unavailable",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/collections": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns paginated collections owned by the current user.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Collections"
                ],
                "summary": "List collections",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Search term",
                        "name": "search",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Results per page (default: 20)",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Offset for pagination (default: 0)",
                        "name": "offset",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.listCollectionsResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Creates a new collection for the current user.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Collections"
                ],
                "summary": "Create collection",
                "parameters": [
                    {
                        "description": "Collection details",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/portal.createCollectionRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "$ref": "#/definitions/portal.Collection"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/collections/{id}": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns a single collection by ID. Non-owners need share access.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Collections"
                ],
                "summary": "Get collection",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Collection ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.getCollectionResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "410": {
                        "description": "Gone",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Updates a collection's name and/or description. Only the owner can update.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Collections"
                ],
                "summary": "Update collection",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Collection ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Fields to update",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/portal.updateCollectionRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.Collection"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            },
            "delete": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Soft-deletes a collection. Only the owner can delete.",
                "tags": [
                    "Collections"
                ],
                "summary": "Delete collection",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Collection ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "204": {
                        "description": "No Content"
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/collections/{id}/config": {
            "put": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Updates the collection's display configuration. Only the owner can update.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Collections"
                ],
                "summary": "Update collection config",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Collection ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Configuration object",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/portal.CollectionConfig"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.Collection"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/collections/{id}/sections": {
            "put": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Replaces all sections and items in a collection. Only the owner can modify.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Collections"
                ],
                "summary": "Set collection sections",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Collection ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Sections with items",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/portal.setSectionsRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.Collection"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/collections/{id}/shares": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns all shares for a collection. Only the owner can view shares.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Shares"
                ],
                "summary": "List collection shares",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Collection ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/portal.Share"
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Creates a share link or user-targeted share for a collection. Only the owner can share.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Shares"
                ],
                "summary": "Create collection share",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Collection ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Share configuration",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/portal.createShareRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "$ref": "#/definitions/portal.shareResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/collections/{id}/thumbnail": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Downloads the collection's PNG thumbnail image.",
                "produces": [
                    "image/png"
                ],
                "tags": [
                    "Collections"
                ],
                "summary": "Get collection thumbnail",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Collection ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "file"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "503": {
                        "description": "Service Unavailable",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Uploads a PNG thumbnail image for the collection. Only the owner can upload.",
                "consumes": [
                    "image/png"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Collections"
                ],
                "summary": "Upload collection thumbnail",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Collection ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "PNG image data",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "type": "array",
                            "items": {
                                "type": "integer"
                            }
                        }
                    }
                ],
                "responses": {
                    "204": {
                        "description": "No Content"
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "413": {
                        "description": "Request Entity Too Large",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "503": {
                        "description": "Service Unavailable",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/knowledge/insights": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns paginated insights captured by the current user.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Knowledge"
                ],
                "summary": "List my insights",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Filter by status",
                        "name": "status",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by category",
                        "name": "category",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Results per page (default: 20)",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Offset for pagination (default: 0)",
                        "name": "offset",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.paginatedResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/knowledge/insights/stats": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns aggregate statistics for the current user's insights.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Knowledge"
                ],
                "summary": "Get my insight stats",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/knowledge.InsightStats"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/me": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns the authenticated user's profile including roles, persona, and available tools.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "User"
                ],
                "summary": "Get current user info",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.meResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/memory/records": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns paginated memory records for the current user with optional filtering.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Memory"
                ],
                "summary": "List my memory records",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Filter by dimension",
                        "name": "dimension",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by category",
                        "name": "category",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by status",
                        "name": "status",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by source",
                        "name": "source",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Results per page (default: 20)",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Offset for pagination (default: 0)",
                        "name": "offset",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.paginatedResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/memory/records/stats": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns aggregated memory statistics grouped by dimension, category, and status.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Memory"
                ],
                "summary": "Get my memory stats",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.memoryStatsResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/prompts": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns the user's personal prompts plus available global, persona, and system prompts.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Prompts"
                ],
                "summary": "List my prompts",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.portalPromptListResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Creates a new personal prompt for the current user.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Prompts"
                ],
                "summary": "Create personal prompt",
                "parameters": [
                    {
                        "description": "Prompt details",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/portal.portalPromptCreateRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "$ref": "#/definitions/prompt.Prompt"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/prompts/{id}": {
            "put": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Updates a personal prompt owned by the current user. Admins can update any prompt.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Prompts"
                ],
                "summary": "Update personal prompt",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Prompt ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Updated prompt fields",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/portal.portalPromptCreateRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/prompt.Prompt"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            },
            "delete": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Deletes a personal prompt owned by the current user. Admins can delete any prompt.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Prompts"
                ],
                "summary": "Delete personal prompt",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Prompt ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "additionalProperties": {
                                "type": "string"
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/shared-collections": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns paginated collections that other users have shared with the current user.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Shares"
                ],
                "summary": "List collections shared with me",
                "parameters": [
                    {
                        "type": "integer",
                        "description": "Results per page (default: 20)",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Offset for pagination (default: 0)",
                        "name": "offset",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.listSharedCollectionsResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/shared-with-me": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Returns paginated assets that other users have shared with the current user.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Shares"
                ],
                "summary": "List assets shared with me",
                "parameters": [
                    {
                        "type": "integer",
                        "description": "Results per page (default: 20)",
                        "name": "limit",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Offset for pagination (default: 0)",
                        "name": "offset",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.paginatedResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/portal/shares/{id}": {
            "delete": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Revokes a share by its ID. Only the asset owner can revoke.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Shares"
                ],
                "summary": "Revoke share",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Share ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/portal.statusResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/portal.problemDetail"
                        }
                    }
                }
            }
        },
        "/resources": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "List managed resources visible to the caller, with optional filters.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Resources"
                ],
                "summary": "List resources",
                "parameters": [
                    {
                        "enum": [
                            "global",
                            "persona",
                            "user"
                        ],
                        "type": "string",
                        "description": "Filter by scope",
                        "name": "scope",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by scope ID (persona name or user sub)",
                        "name": "scope_id",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by category",
                        "name": "category",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Filter by tag",
                        "name": "tag",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "Search display_name and description",
                        "name": "q",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "Pagination offset (default 0)",
                        "name": "offset",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/resource.listResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Upload a new managed resource with metadata and file content.",
                "consumes": [
                    "multipart/form-data"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Resources"
                ],
                "summary": "Create resource",
                "parameters": [
                    {
                        "type": "file",
                        "description": "File to upload (max 100 MB)",
                        "name": "file",
                        "in": "formData",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Human-readable display name",
                        "name": "display_name",
                        "in": "formData",
                        "required": true
                    },
                    {
                        "enum": [
                            "global",
                            "persona",
                            "user"
                        ],
                        "type": "string",
                        "description": "Visibility scope",
                        "name": "scope",
                        "in": "formData",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Persona name or user sub (required for persona/user scopes)",
                        "name": "scope_id",
                        "in": "formData"
                    },
                    {
                        "type": "string",
                        "description": "Resource category (e.g. runbooks, templates)",
                        "name": "category",
                        "in": "formData",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "Optional description",
                        "name": "description",
                        "in": "formData"
                    },
                    {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "collectionFormat": "multi",
                        "description": "Optional tags",
                        "name": "tags",
                        "in": "formData"
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "$ref": "#/definitions/github_com_txn2_mcp-data-platform_pkg_resource.Resource"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "409": {
                        "description": "Conflict",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    }
                }
            }
        },
        "/resources/{id}": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Retrieve metadata for a single managed resource by ID.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Resources"
                ],
                "summary": "Get resource",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Resource ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/github_com_txn2_mcp-data-platform_pkg_resource.Resource"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    }
                }
            },
            "delete": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Delete a managed resource, removing both the S3 blob and database metadata.",
                "tags": [
                    "Resources"
                ],
                "summary": "Delete resource",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Resource ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "204": {
                        "description": "No Content"
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    }
                }
            },
            "patch": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Update mutable metadata fields of a managed resource.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Resources"
                ],
                "summary": "Update resource",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Resource ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Fields to update",
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/resource.Update"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/github_com_txn2_mcp-data-platform_pkg_resource.Resource"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    }
                }
            }
        },
        "/resources/{id}/content": {
            "get": {
                "security": [
                    {
                        "ApiKeyAuth": []
                    },
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Download the binary content of a managed resource.",
                "produces": [
                    "application/octet-stream"
                ],
                "tags": [
                    "Resources"
                ],
                "summary": "Download resource content",
                "parameters": [
                    {
                        "type": "string",
                        "description": "Resource ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "file"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    },
                    "503": {
                        "description": "Service Unavailable",
                        "schema": {
                            "$ref": "#/definitions/resource.errorResponse"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "admin.ToolActivityAggregate": {
            "type": "object",
            "properties": {
                "avg_duration_ms": {
                    "type": "number"
                },
                "call_count": {
                    "type": "integer"
                },
                "success_rate": {
                    "type": "number"
                },
                "window_seconds": {
                    "type": "integer"
                }
            }
        },
        "admin.ToolDetail": {
            "type": "object",
            "properties": {
                "activity": {
                    "$ref": "#/definitions/admin.ToolActivityAggregate"
                },
                "connection": {
                    "type": "string"
                },
                "description": {
                    "type": "string"
                },
                "description_overridden": {
                    "description": "Description-override status (populated when a\ntool.\u003cname\u003e.description config-entry exists).",
                    "type": "boolean"
                },
                "enrichment_rule_count": {
                    "description": "Number of cross-enrichment rules attached to this tool. Only\nmeaningful for proxied tools (kind=mcp); zero for native.",
                    "type": "integer"
                },
                "global_deny_pattern": {
                    "type": "string"
                },
                "hidden_by_global_deny": {
                    "description": "HiddenByGlobalDeny is true when the platform-level tools.deny\nlist matches this tool. GlobalDenyPattern is the matching glob.",
                    "type": "boolean"
                },
                "hidden_by_persona": {
                    "description": "HiddenByPersona maps persona name → true for any persona where\nthis tool is denied.",
                    "type": "object",
                    "additionalProperties": {
                        "type": "boolean"
                    }
                },
                "input_schema": {
                    "description": "JSON Schema for the tool's input parameters."
                },
                "name": {
                    "type": "string"
                },
                "override_author": {
                    "type": "string"
                },
                "personas": {
                    "description": "Persona allow/deny matrix — one entry per database-managed\npersona, with the matched pattern and source recorded.",
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/admin.ToolPersonaAccess"
                    }
                },
                "title": {
                    "type": "string"
                },
                "toolkit_kind": {
                    "type": "string"
                },
                "toolkit_name": {
                    "type": "string"
                }
            }
        },
        "admin.ToolPersonaAccess": {
            "type": "object",
            "properties": {
                "allowed": {
                    "type": "boolean"
                },
                "connection_allowed": {
                    "type": "boolean"
                },
                "matched_pattern": {
                    "type": "string"
                },
                "persona": {
                    "type": "string"
                },
                "source": {
                    "$ref": "#/definitions/persona.AccessSource"
                }
            }
        },
        "admin.auditEventResponse": {
            "type": "object",
            "properties": {
                "data": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/audit.Event"
                    }
                },
                "page": {
                    "type": "integer",
                    "example": 1
                },
                "per_page": {
                    "type": "integer",
                    "example": 50
                },
                "total": {
                    "type": "integer",
                    "example": 196
                }
            }
        },
        "admin.auditFiltersResponse": {
            "type": "object",
            "properties": {
                "sources": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "mcp",
                        "rest",
                        "admin"
                    ]
                },
                "toolkit_kinds": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "api",
                        "datahub",
                        "trino",
                        "s3",
                        "memory"
                    ]
                },
                "tools": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "trino_query",
                        "datahub_search",
                        "s3_list_objects"
                    ]
                },
                "user_labels": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "string"
                    }
                },
                "users": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "marcus.johnson@example.com",
                        "lisa.chang@example.com"
                    ]
                }
            }
        },
        "admin.auditStatsResponse": {
            "type": "object",
            "properties": {
                "failures": {
                    "type": "integer",
                    "example": 77
                },
                "success": {
                    "type": "integer",
                    "example": 1423
                },
                "total": {
                    "type": "integer",
                    "example": 1500
                }
            }
        },
        "admin.authKeyCreateRequest": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string",
                    "example": "CI/CD pipeline integration"
                },
                "email": {
                    "type": "string",
                    "example": "ci@example.com"
                },
                "expires_in": {
                    "description": "e.g. \"24h\", \"720h\", \"8760h\"",
                    "type": "string",
                    "example": "720h"
                },
                "name": {
                    "type": "string",
                    "example": "ci-pipeline"
                },
                "roles": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "analyst"
                    ]
                }
            }
        },
        "admin.authKeyCreateResponse": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string",
                    "example": "CI/CD pipeline integration"
                },
                "email": {
                    "type": "string",
                    "example": "ci@example.com"
                },
                "expires_at": {
                    "type": "string"
                },
                "key": {
                    "type": "string",
                    "example": "mdp_a1b2c3d4e5f6g7h8i9j0"
                },
                "name": {
                    "type": "string",
                    "example": "ci-pipeline"
                },
                "roles": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "analyst"
                    ]
                },
                "warning": {
                    "type": "string",
                    "example": "Store this key securely. It will not be shown again."
                }
            }
        },
        "admin.authKeyListResponse": {
            "type": "object",
            "properties": {
                "keys": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/auth.APIKeySummary"
                    }
                },
                "total": {
                    "type": "integer",
                    "example": 3
                }
            }
        },
        "admin.changesetListResponse": {
            "type": "object",
            "properties": {
                "data": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/knowledge.Changeset"
                    }
                },
                "page": {
                    "type": "integer",
                    "example": 1
                },
                "per_page": {
                    "type": "integer",
                    "example": 20
                },
                "total": {
                    "type": "integer",
                    "example": 8
                }
            }
        },
        "admin.configModeResponse": {
            "type": "object",
            "properties": {
                "mode": {
                    "type": "string",
                    "example": "database"
                },
                "read_only": {
                    "type": "boolean",
                    "example": false
                }
            }
        },
        "admin.connectionInfo": {
            "type": "object",
            "properties": {
                "connection": {
                    "type": "string",
                    "example": "acme-warehouse"
                },
                "hidden_tools": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "kind": {
                    "type": "string",
                    "example": "trino"
                },
                "name": {
                    "type": "string",
                    "example": "acme-warehouse"
                },
                "tools": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "trino_query",
                        "trino_describe_table",
                        "trino_browse"
                    ]
                }
            }
        },
        "admin.connectionListResponse": {
            "type": "object",
            "properties": {
                "connections": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/admin.connectionInfo"
                    }
                },
                "total": {
                    "type": "integer",
                    "example": 5
                }
            }
        },
        "admin.connectionOAuthHealthSummary": {
            "type": "object",
            "properties": {
                "has_oauth": {
                    "type": "boolean"
                },
                "idp_error_code": {
                    "type": "string"
                },
                "kind": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                },
                "needs_reauth": {
                    "type": "boolean"
                },
                "token_acquired": {
                    "type": "boolean"
                }
            }
        },
        "admin.connectionsOAuthHealthResponse": {
            "type": "object",
            "properties": {
                "connections": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/admin.connectionOAuthHealthSummary"
                    }
                }
            }
        },
        "admin.dryRunEnrichmentRequest": {
            "type": "object",
            "properties": {
                "args": {
                    "type": "object",
                    "additionalProperties": {}
                },
                "response": {},
                "user": {
                    "$ref": "#/definitions/admin.dryRunUser"
                }
            }
        },
        "admin.dryRunEnrichmentResponse": {
            "type": "object",
            "properties": {
                "fired": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/enrichment.FiredRule"
                    }
                },
                "response": {},
                "warnings": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "admin.dryRunUser": {
            "type": "object",
            "properties": {
                "email": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                }
            }
        },
        "admin.embeddingProviderStatusResponse": {
            "type": "object",
            "properties": {
                "dimension": {
                    "description": "Dimension is the embedding vector length.",
                    "type": "integer",
                    "example": 768
                },
                "kind": {
                    "description": "Kind is the provider implementation identifier: \"ollama\", \"noop\",\nor a future kind. Empty string when no provider was wired.",
                    "type": "string",
                    "example": "ollama"
                },
                "model": {
                    "description": "Model identifies the underlying embedding model when the provider\nexposes it (e.g., \"nomic-embed-text\" for Ollama). Empty for\nproviders whose backend has no model concept (noop).",
                    "type": "string",
                    "example": "nomic-embed-text"
                },
                "status": {
                    "description": "Status is the operator-visible health enum:\n  - \"ok\": a real provider is configured; semantic features active.\n  - \"unconfigured\": no provider configured (or noop placeholder).\n    Semantic ranking falls back to lexical; memory writes persist\n    with Embedding: nil.",
                    "type": "string",
                    "example": "ok"
                }
            }
        },
        "admin.enrichmentRuleBody": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string"
                },
                "enabled": {
                    "type": "boolean"
                },
                "enrich_action": {
                    "$ref": "#/definitions/enrichment.Action"
                },
                "merge_strategy": {
                    "$ref": "#/definitions/enrichment.Merge"
                },
                "tool_name": {
                    "type": "string"
                },
                "when_predicate": {
                    "$ref": "#/definitions/enrichment.Predicate"
                }
            }
        },
        "admin.insightListResponse": {
            "type": "object",
            "properties": {
                "data": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/knowledge.Insight"
                    }
                },
                "page": {
                    "type": "integer",
                    "example": 1
                },
                "per_page": {
                    "type": "integer",
                    "example": 20
                },
                "total": {
                    "type": "integer",
                    "example": 50
                }
            }
        },
        "admin.insightUpdateRequest": {
            "type": "object",
            "properties": {
                "category": {
                    "type": "string",
                    "example": "correction"
                },
                "confidence": {
                    "type": "string",
                    "example": "high"
                },
                "insight_text": {
                    "type": "string",
                    "example": "The amount column represents gross margin before returns."
                }
            }
        },
        "admin.memoryListResponse": {
            "type": "object",
            "properties": {
                "data": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/memory.Record"
                    }
                },
                "page": {
                    "type": "integer",
                    "example": 1
                },
                "per_page": {
                    "type": "integer",
                    "example": 20
                },
                "total": {
                    "type": "integer",
                    "example": 20
                }
            }
        },
        "admin.memoryStatsResponse": {
            "type": "object",
            "properties": {
                "by_category": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "integer"
                    }
                },
                "by_dimension": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "integer"
                    }
                },
                "by_status": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "integer"
                    }
                },
                "total": {
                    "type": "integer",
                    "example": 20
                }
            }
        },
        "admin.memoryUpdateRequest": {
            "type": "object",
            "properties": {
                "category": {
                    "type": "string",
                    "example": "business_context"
                },
                "confidence": {
                    "type": "string",
                    "example": "high"
                },
                "content": {
                    "type": "string",
                    "example": "The daily_sales table in the retail schema is partitioned by date."
                },
                "dimension": {
                    "type": "string",
                    "example": "knowledge"
                },
                "metadata": {
                    "type": "object",
                    "additionalProperties": {}
                }
            }
        },
        "admin.personaContextDetail": {
            "type": "object",
            "properties": {
                "agent_instructions_override": {
                    "type": "string"
                },
                "agent_instructions_suffix": {
                    "type": "string",
                    "example": "Focus on schema details, data lineage, and query optimization."
                },
                "description_override": {
                    "type": "string"
                },
                "description_prefix": {
                    "type": "string",
                    "example": "This user is a data engineer responsible for ETL pipelines."
                }
            }
        },
        "admin.personaCreateRequest": {
            "type": "object",
            "properties": {
                "agent_instructions_override": {
                    "type": "string"
                },
                "agent_instructions_suffix": {
                    "type": "string"
                },
                "allow_connections": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "allow_tools": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "datahub_*"
                    ]
                },
                "deny_connections": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "deny_tools": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "description": {
                    "type": "string",
                    "example": "Read-only access to DataHub"
                },
                "description_override": {
                    "type": "string"
                },
                "description_prefix": {
                    "type": "string"
                },
                "display_name": {
                    "type": "string",
                    "example": "Data Viewer"
                },
                "name": {
                    "type": "string",
                    "example": "viewer"
                },
                "priority": {
                    "type": "integer",
                    "example": 0
                },
                "roles": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "viewer"
                    ]
                }
            }
        },
        "admin.personaDetail": {
            "type": "object",
            "properties": {
                "allow_connections": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "allow_tools": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "trino_*",
                        "datahub_*",
                        "s3_*"
                    ]
                },
                "context": {
                    "$ref": "#/definitions/admin.personaContextDetail"
                },
                "deny_connections": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "deny_tools": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "capture_insight"
                    ]
                },
                "description": {
                    "type": "string",
                    "example": "ETL pipeline development and schema management"
                },
                "display_name": {
                    "type": "string",
                    "example": "Data Engineer"
                },
                "name": {
                    "type": "string",
                    "example": "data-engineer"
                },
                "priority": {
                    "type": "integer",
                    "example": 10
                },
                "roles": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "data_engineer"
                    ]
                },
                "source": {
                    "description": "\"file\", \"database\", or \"both\"",
                    "type": "string",
                    "example": "file"
                },
                "tools": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "trino_query",
                        "trino_describe_table",
                        "datahub_search"
                    ]
                }
            }
        },
        "admin.personaListResponse": {
            "type": "object",
            "properties": {
                "personas": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/admin.personaSummary"
                    }
                },
                "total": {
                    "type": "integer",
                    "example": 6
                }
            }
        },
        "admin.personaSummary": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string",
                    "example": "ETL pipeline development and schema management"
                },
                "display_name": {
                    "type": "string",
                    "example": "Data Engineer"
                },
                "name": {
                    "type": "string",
                    "example": "data-engineer"
                },
                "roles": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "data_engineer"
                    ]
                },
                "source": {
                    "description": "\"file\", \"database\", or \"both\"",
                    "type": "string",
                    "example": "file"
                },
                "tool_count": {
                    "type": "integer",
                    "example": 19
                }
            }
        },
        "admin.problemDetail": {
            "type": "object",
            "properties": {
                "detail": {
                    "type": "string",
                    "example": "resource not found"
                },
                "status": {
                    "type": "integer",
                    "example": 404
                },
                "title": {
                    "type": "string",
                    "example": "Not Found"
                },
                "type": {
                    "type": "string",
                    "example": "about:blank"
                }
            }
        },
        "admin.refreshGatewayConnectionResponse": {
            "type": "object",
            "properties": {
                "error": {
                    "type": "string"
                },
                "healthy": {
                    "type": "boolean"
                },
                "tools": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "admin.setConnectionInstanceRequest": {
            "type": "object",
            "properties": {
                "config": {
                    "type": "object",
                    "additionalProperties": {}
                },
                "description": {
                    "type": "string",
                    "example": "Production data warehouse"
                }
            }
        },
        "admin.startConnectionOAuthRequest": {
            "type": "object",
            "properties": {
                "return_url": {
                    "type": "string"
                }
            }
        },
        "admin.startConnectionOAuthResponse": {
            "type": "object",
            "properties": {
                "authorization_url": {
                    "type": "string"
                },
                "expires_at": {
                    "type": "string"
                },
                "redirect_uri": {
                    "type": "string"
                },
                "state": {
                    "type": "string"
                }
            }
        },
        "admin.startGatewayOAuthRequest": {
            "type": "object",
            "properties": {
                "return_url": {
                    "type": "string"
                }
            }
        },
        "admin.startGatewayOAuthResponse": {
            "type": "object",
            "properties": {
                "authorization_url": {
                    "type": "string"
                },
                "expires_at": {
                    "type": "string"
                },
                "redirect_uri": {
                    "type": "string"
                },
                "state": {
                    "type": "string"
                }
            }
        },
        "admin.statusResponse": {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string",
                    "example": "ok"
                }
            }
        },
        "admin.statusUpdateRequest": {
            "type": "object",
            "properties": {
                "review_notes": {
                    "type": "string",
                    "example": "Verified with data engineering team"
                },
                "status": {
                    "type": "string",
                    "example": "approved"
                }
            }
        },
        "admin.systemFeatures": {
            "type": "object",
            "properties": {
                "admin": {
                    "type": "boolean",
                    "example": true
                },
                "audit": {
                    "type": "boolean",
                    "example": true
                },
                "database": {
                    "type": "boolean",
                    "example": true
                },
                "knowledge": {
                    "type": "boolean",
                    "example": true
                },
                "oauth": {
                    "type": "boolean",
                    "example": false
                }
            }
        },
        "admin.systemInfoResponse": {
            "type": "object",
            "properties": {
                "build_date": {
                    "type": "string",
                    "example": "2026-04-15T00:00:00Z"
                },
                "commit": {
                    "type": "string",
                    "example": "b5d2a78"
                },
                "config_mode": {
                    "type": "string",
                    "example": "database"
                },
                "description": {
                    "type": "string",
                    "example": "Semantic data platform"
                },
                "features": {
                    "$ref": "#/definitions/admin.systemFeatures"
                },
                "name": {
                    "type": "string",
                    "example": "acme-data-platform"
                },
                "persona_count": {
                    "type": "integer",
                    "example": 3
                },
                "portal_logo": {
                    "type": "string",
                    "example": "https://example.com/logo.svg"
                },
                "portal_logo_dark": {
                    "type": "string",
                    "example": "https://example.com/logo-dark.svg"
                },
                "portal_logo_light": {
                    "type": "string",
                    "example": "https://example.com/logo-light.svg"
                },
                "portal_title": {
                    "type": "string",
                    "example": "ACME Data Platform"
                },
                "toolkit_count": {
                    "type": "integer",
                    "example": 5
                },
                "transport": {
                    "type": "string",
                    "example": "http"
                },
                "version": {
                    "type": "string",
                    "example": "1.55.11"
                }
            }
        },
        "admin.testGatewayConnectionRequest": {
            "type": "object",
            "properties": {
                "config": {
                    "type": "object",
                    "additionalProperties": {}
                }
            }
        },
        "admin.testGatewayConnectionResponse": {
            "type": "object",
            "properties": {
                "error": {
                    "type": "string"
                },
                "healthy": {
                    "type": "boolean"
                },
                "tools": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/gateway.ProbeTool"
                    }
                }
            }
        },
        "admin.testPersonaAccessRequest": {
            "type": "object",
            "properties": {
                "tool_name": {
                    "type": "string",
                    "example": "trino_query"
                }
            }
        },
        "admin.testPersonaAccessResponse": {
            "type": "object",
            "properties": {
                "allowed": {
                    "type": "boolean",
                    "example": true
                },
                "matched_pattern": {
                    "type": "string",
                    "example": "trino_*"
                },
                "source": {
                    "allOf": [
                        {
                            "$ref": "#/definitions/persona.AccessSource"
                        }
                    ],
                    "example": "allow"
                }
            }
        },
        "admin.toolCallRequest": {
            "type": "object",
            "properties": {
                "connection": {
                    "type": "string",
                    "example": "acme-warehouse"
                },
                "parameters": {
                    "type": "object",
                    "additionalProperties": {}
                },
                "tool_name": {
                    "type": "string",
                    "example": "trino_query"
                }
            }
        },
        "admin.toolCallResponse": {
            "type": "object",
            "properties": {
                "content": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/admin.toolContentBlock"
                    }
                },
                "duration_ms": {
                    "type": "integer",
                    "example": 245
                },
                "is_error": {
                    "type": "boolean",
                    "example": false
                }
            }
        },
        "admin.toolContentBlock": {
            "type": "object",
            "properties": {
                "text": {
                    "type": "string",
                    "example": "| col1 | col2 |\n|------|------|\n| val1 | val2 |"
                },
                "type": {
                    "type": "string",
                    "example": "text"
                }
            }
        },
        "admin.toolInfo": {
            "type": "object",
            "properties": {
                "connection": {
                    "type": "string",
                    "example": "acme-warehouse"
                },
                "hidden": {
                    "description": "Hidden is true when the tool is excluded from tools/list responses by\nthe platform-wide tools.allow / tools.deny visibility filter. Persona\nauthorization is independent and not reflected here.",
                    "type": "boolean",
                    "example": false
                },
                "kind": {
                    "type": "string",
                    "example": "trino"
                },
                "name": {
                    "type": "string",
                    "example": "trino_query"
                },
                "title": {
                    "type": "string",
                    "example": "Trino Query"
                },
                "toolkit": {
                    "type": "string",
                    "example": "acme-warehouse"
                }
            }
        },
        "admin.toolListResponse": {
            "type": "object",
            "properties": {
                "tools": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/admin.toolInfo"
                    }
                },
                "total": {
                    "type": "integer",
                    "example": 12
                }
            }
        },
        "admin.toolSchema": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string",
                    "example": "Execute a SQL query against Trino and return results."
                },
                "kind": {
                    "type": "string",
                    "example": "trino"
                },
                "name": {
                    "type": "string",
                    "example": "trino_query"
                },
                "parameters": {},
                "title": {
                    "type": "string",
                    "example": "Trino Query"
                }
            }
        },
        "admin.toolSchemaResponse": {
            "type": "object",
            "properties": {
                "schemas": {
                    "type": "object",
                    "additionalProperties": {
                        "$ref": "#/definitions/admin.toolSchema"
                    }
                }
            }
        },
        "admin.toolVisibilityRequest": {
            "type": "object",
            "properties": {
                "hidden": {
                    "description": "Hidden=true adds the tool to the global tools.deny list; false removes it.",
                    "type": "boolean",
                    "example": true
                }
            }
        },
        "admin.toolVisibilityResponse": {
            "type": "object",
            "properties": {
                "deny": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "hidden": {
                    "type": "boolean",
                    "example": true
                },
                "tool_name": {
                    "type": "string",
                    "example": "trino_admin_kill"
                }
            }
        },
        "audit.BreakdownEntry": {
            "type": "object",
            "properties": {
                "avg_duration_ms": {
                    "type": "number",
                    "example": 320
                },
                "count": {
                    "type": "integer",
                    "example": 65
                },
                "dimension": {
                    "type": "string",
                    "example": "trino_query"
                },
                "success_rate": {
                    "type": "number",
                    "example": 0.95
                }
            }
        },
        "audit.DiscoveryStats": {
            "type": "object",
            "properties": {
                "discovery_before_query": {
                    "type": "integer",
                    "example": 60
                },
                "discovery_rate": {
                    "type": "number",
                    "example": 0.75
                },
                "discovery_sessions": {
                    "type": "integer",
                    "example": 75
                },
                "query_sessions": {
                    "type": "integer",
                    "example": 80
                },
                "query_without_discovery": {
                    "type": "integer",
                    "example": 20
                },
                "top_discovery_tools": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/audit.BreakdownEntry"
                    }
                },
                "total_sessions": {
                    "type": "integer",
                    "example": 100
                }
            }
        },
        "audit.EnrichmentStats": {
            "type": "object",
            "properties": {
                "avg_tokens_dedup": {
                    "type": "number",
                    "example": 100
                },
                "avg_tokens_full": {
                    "type": "number",
                    "example": 375
                },
                "enriched_calls": {
                    "type": "integer",
                    "example": 1200
                },
                "enrichment_rate": {
                    "type": "number",
                    "example": 0.8
                },
                "full_count": {
                    "type": "integer",
                    "example": 800
                },
                "none_count": {
                    "type": "integer",
                    "example": 0
                },
                "reference_count": {
                    "type": "integer",
                    "example": 100
                },
                "summary_count": {
                    "type": "integer",
                    "example": 300
                },
                "tokens_saved": {
                    "type": "integer",
                    "example": 330000
                },
                "total_calls": {
                    "type": "integer",
                    "example": 1500
                },
                "total_tokens_dedup": {
                    "type": "integer",
                    "example": 120000
                },
                "total_tokens_full": {
                    "type": "integer",
                    "example": 450000
                },
                "unique_sessions": {
                    "type": "integer",
                    "example": 45
                }
            }
        },
        "audit.Event": {
            "type": "object",
            "properties": {
                "authorized": {
                    "type": "boolean",
                    "example": true
                },
                "connection": {
                    "type": "string",
                    "example": "acme-catalog"
                },
                "content_blocks": {
                    "type": "integer",
                    "example": 2
                },
                "duration_ms": {
                    "type": "integer",
                    "example": 143
                },
                "enrichment_applied": {
                    "type": "boolean",
                    "example": true
                },
                "enrichment_mode": {
                    "type": "string",
                    "example": "summary"
                },
                "enrichment_tokens_dedup": {
                    "type": "integer",
                    "example": 350
                },
                "enrichment_tokens_full": {
                    "type": "integer",
                    "example": 850
                },
                "error_message": {
                    "type": "string"
                },
                "id": {
                    "type": "string",
                    "example": "evt_a1b2c3d4e5f6"
                },
                "parameters": {
                    "type": "object",
                    "additionalProperties": {}
                },
                "persona": {
                    "type": "string",
                    "example": "data-engineer"
                },
                "request_chars": {
                    "type": "integer",
                    "example": 120
                },
                "request_id": {
                    "type": "string",
                    "example": "req_x9y8z7"
                },
                "response_chars": {
                    "type": "integer",
                    "example": 2450
                },
                "session_id": {
                    "type": "string",
                    "example": "sess_abc123"
                },
                "source": {
                    "type": "string",
                    "example": "mcp"
                },
                "success": {
                    "type": "boolean",
                    "example": true
                },
                "timestamp": {
                    "type": "string",
                    "example": "2026-04-15T10:41:18Z"
                },
                "tool_name": {
                    "type": "string",
                    "example": "datahub_get_schema"
                },
                "toolkit_kind": {
                    "type": "string",
                    "example": "datahub"
                },
                "toolkit_name": {
                    "type": "string",
                    "example": "acme-catalog"
                },
                "transport": {
                    "type": "string",
                    "example": "http"
                },
                "user_email": {
                    "type": "string",
                    "example": "marcus.johnson@example.com"
                },
                "user_id": {
                    "type": "string",
                    "example": "550e8400-e29b-41d4-a716-446655440000"
                }
            }
        },
        "audit.Overview": {
            "type": "object",
            "properties": {
                "avg_duration_ms": {
                    "type": "number",
                    "example": 522
                },
                "enrichment_rate": {
                    "type": "number",
                    "example": 0.85
                },
                "error_count": {
                    "type": "integer",
                    "example": 10
                },
                "success_rate": {
                    "type": "number",
                    "example": 0.949
                },
                "total_calls": {
                    "type": "integer",
                    "example": 196
                },
                "unique_tools": {
                    "type": "integer",
                    "example": 12
                },
                "unique_users": {
                    "type": "integer",
                    "example": 12
                }
            }
        },
        "audit.PerformanceStats": {
            "type": "object",
            "properties": {
                "avg_ms": {
                    "type": "number",
                    "example": 522
                },
                "avg_request_chars": {
                    "type": "number",
                    "example": 120
                },
                "avg_response_chars": {
                    "type": "number",
                    "example": 1850
                },
                "max_ms": {
                    "type": "number",
                    "example": 5200
                },
                "p50_ms": {
                    "type": "number",
                    "example": 320
                },
                "p95_ms": {
                    "type": "number",
                    "example": 1450
                },
                "p99_ms": {
                    "type": "number",
                    "example": 2400
                }
            }
        },
        "audit.TimeseriesBucket": {
            "type": "object",
            "properties": {
                "avg_duration_ms": {
                    "type": "number",
                    "example": 245.5
                },
                "bucket": {
                    "type": "string",
                    "example": "2026-04-15T14:30:00Z"
                },
                "count": {
                    "type": "integer",
                    "example": 12
                },
                "error_count": {
                    "type": "integer",
                    "example": 1
                },
                "success_count": {
                    "type": "integer",
                    "example": 11
                }
            }
        },
        "auth.APIKeySummary": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string",
                    "example": "CI/CD pipeline integration"
                },
                "email": {
                    "type": "string",
                    "example": "ci@example.com"
                },
                "expired": {
                    "type": "boolean",
                    "example": false
                },
                "expires_at": {
                    "type": "string"
                },
                "name": {
                    "type": "string",
                    "example": "ci-pipeline"
                },
                "roles": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "analyst"
                    ]
                },
                "source": {
                    "description": "\"file\", \"database\", or \"both\"",
                    "type": "string",
                    "example": "database"
                }
            }
        },
        "authevents.Event": {
            "type": "object",
            "properties": {
                "actor": {
                    "description": "Actor is who/what initiated the event. See SystemXxx constants\nfor synthetic actors; operator-driven events use the email or\napikey:name. Required (empty string is rejected at insert).",
                    "type": "string"
                },
                "connection_kind": {
                    "description": "Kind is the connection kind (mcp, api, future).",
                    "type": "string"
                },
                "connection_name": {
                    "description": "Name is the connection name within the kind.",
                    "type": "string"
                },
                "detail": {
                    "description": "Detail is per-Type JSON. May be nil for events with no extra\npayload.\n\nswaggertype tag tells swag (used by make swagger) to treat the\nfield as a generic object; without it swag can't resolve\njson.RawMessage and the generation step fails.",
                    "type": "object"
                },
                "event_type": {
                    "description": "Type is one of the declared TypeXxx constants. Required.",
                    "allOf": [
                        {
                            "$ref": "#/definitions/authevents.Type"
                        }
                    ]
                },
                "id": {
                    "description": "ID is the server-assigned row UUID. Empty on inserts; populated\nby the store after the INSERT … RETURNING id.",
                    "type": "string"
                },
                "idp_host": {
                    "description": "IDPHost is the host portion of the IdP token endpoint. Empty\nwhen not relevant to the event (e.g., TypeTokenDeletedAdmin).",
                    "type": "string"
                },
                "occurred_at": {
                    "description": "OccurredAt is wall-clock time of the event. Empty on inserts;\nthe store stamps NOW().",
                    "type": "string"
                }
            }
        },
        "authevents.Type": {
            "type": "string",
            "enum": [
                "connect_started",
                "connect_completed",
                "refresh_succeeded",
                "refresh_failed_transient",
                "refresh_failed_revoked",
                "refresh_skipped_no_token",
                "refresh_skipped_expired",
                "refresh_rotation_persistence_failed",
                "token_deleted_revoked",
                "token_deleted_admin"
            ],
            "x-enum-varnames": [
                "TypeConnectStarted",
                "TypeConnectCompleted",
                "TypeRefreshSucceeded",
                "TypeRefreshFailedTransient",
                "TypeRefreshFailedRevoked",
                "TypeRefreshSkippedNoToken",
                "TypeRefreshSkippedExpired",
                "TypeRefreshRotationPersistenceFailed",
                "TypeTokenDeletedRevoked",
                "TypeTokenDeletedAdmin"
            ]
        },
        "connoauth.OAuthStatus": {
            "type": "object",
            "properties": {
                "authenticated_at": {
                    "description": "AuthenticatedAt is when the most recent successful Connect\ncompleted. Initial-Connect time, not last-refresh time.",
                    "type": "string"
                },
                "authenticated_by": {
                    "description": "AuthenticatedBy is the email/id of the operator who completed\nthe browser flow. Empty for never-authorized connections.",
                    "type": "string"
                },
                "configured": {
                    "description": "Configured indicates the connection is set up for the\nauthorization_code grant. False means the status endpoint was\nhit for a non-OAuth connection (or one with a different grant)\nand the UI should hide the OAuth block entirely.",
                    "type": "boolean"
                },
                "expires_at": {
                    "description": "ExpiresAt is the access-token deadline. Zero when no token has\nbeen acquired.",
                    "type": "string"
                },
                "grant": {
                    "description": "Grant is the OAuth flow this connection uses\n(` + "`" + `authorization_code` + "`" + ` or ` + "`" + `client_credentials` + "`" + `). Surfaced so the\nadmin UI can adapt prompts (the Connect button only applies to\nauthorization_code; client_credentials has no human-in-the-loop\nstep). Empty for non-OAuth connections.",
                    "type": "string"
                },
                "has_refresh_token": {
                    "description": "HasRefreshToken is true when a refresh token sits in the row.\nFalse for IdPs that don't issue refresh tokens, OR after a\nrevoked-refresh cleanup.",
                    "type": "boolean"
                },
                "last_error": {
                    "description": "LastError is the most recent surfaced failure (transport,\nIdP-rejected, persistence). Cleared by a subsequent success.",
                    "type": "string"
                },
                "last_refreshed_at": {
                    "description": "LastRefreshedAt is the persisted row's UpdatedAt — the time of\nthe most recent successful write (initial Connect or silent\nrefresh).",
                    "type": "string"
                },
                "last_revocation": {
                    "description": "LastRevocation, when present, describes the most recent IdP-\ndriven revocation (refresh_failed_revoked /\ntoken_deleted_revoked) for the connection. Populated by the\nadmin status handler from the authevents history; never set by\nthe Source's own Status() because the Source doesn't know\nabout the events table. The UI uses it to render the \"revoked\"\nstate of the OAuth status card (distinct from \"never\nconnected\") so an operator immediately sees that a Connect is\nneeded because the IdP killed the chain, not because the\nconnection was never set up.",
                    "allOf": [
                        {
                            "$ref": "#/definitions/connoauth.RevocationEvent"
                        }
                    ]
                },
                "needs_reauth": {
                    "description": "NeedsReauth is true when no access token can be minted without\noperator interaction. The admin UI surfaces a Connect button\nwhen this is true.",
                    "type": "boolean"
                },
                "refresh_expires_at": {
                    "description": "RefreshExpiresAt is the IdP-disclosed refresh-token deadline.\nZero when the IdP did not disclose one. The admin UI renders an\nem dash for zero, not \"never\".",
                    "type": "string"
                },
                "scope": {
                    "description": "Scope is the space-delimited scope string negotiated with the\nIdP. Surfaced so operators can verify offline_access is present\non Keycloak/Auth0/Okta IdPs.",
                    "type": "string"
                },
                "token_acquired": {
                    "description": "TokenAcquired is true when a non-empty access_token sits in the\npersisted row. False after a revoked-refresh cleanup or before\nthe first Connect.",
                    "type": "boolean"
                },
                "token_url": {
                    "description": "TokenURL is the IdP's token endpoint, surfaced so the admin\nstatus panel can show \"auth against https://iam.example.com/...\"\nat a glance. Operator-authored config; safe to expose.",
                    "type": "string"
                }
            }
        },
        "connoauth.RevocationEvent": {
            "type": "object",
            "properties": {
                "idp_host": {
                    "description": "IDPHost is the host portion of the IdP token URL the\nrevocation came from. Lets the portal show \"rejected by\nidp.example.com at 10:42\" at a glance.",
                    "type": "string"
                },
                "occurred_at": {
                    "description": "OccurredAt is when the IdP rejected the refresh (or the local\npre-check found no refresh token / expired refresh).",
                    "type": "string"
                },
                "reason": {
                    "description": "Reason is the machine-readable revocation reason from the\nevent detail (` + "`" + `invalid_grant` + "`" + `, ` + "`" + `no_refresh_token` + "`" + `,\n` + "`" + `refresh_expired` + "`" + `, or the generic ` + "`" + `revoked` + "`" + ` fallback).",
                    "type": "string"
                }
            }
        },
        "enrichment.Action": {
            "type": "object",
            "properties": {
                "operation": {
                    "type": "string"
                },
                "parameters": {
                    "type": "object",
                    "additionalProperties": {}
                },
                "source": {
                    "type": "string"
                }
            }
        },
        "enrichment.FiredRule": {
            "type": "object",
            "properties": {
                "duration_ms": {
                    "type": "integer"
                },
                "error": {
                    "type": "string"
                },
                "op": {
                    "type": "string"
                },
                "rule_id": {
                    "type": "string"
                },
                "skipped": {
                    "type": "boolean"
                },
                "source": {
                    "type": "string"
                }
            }
        },
        "enrichment.Merge": {
            "type": "object",
            "properties": {
                "kind": {
                    "type": "string"
                },
                "path": {
                    "type": "string"
                }
            }
        },
        "enrichment.Predicate": {
            "type": "object",
            "properties": {
                "kind": {
                    "type": "string"
                },
                "paths": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "enrichment.Rule": {
            "type": "object",
            "properties": {
                "connection_name": {
                    "type": "string"
                },
                "created_at": {
                    "type": "string"
                },
                "created_by": {
                    "type": "string"
                },
                "description": {
                    "type": "string"
                },
                "enabled": {
                    "type": "boolean"
                },
                "enrich_action": {
                    "$ref": "#/definitions/enrichment.Action"
                },
                "id": {
                    "type": "string"
                },
                "merge_strategy": {
                    "$ref": "#/definitions/enrichment.Merge"
                },
                "tool_name": {
                    "type": "string"
                },
                "updated_at": {
                    "type": "string"
                },
                "when_predicate": {
                    "$ref": "#/definitions/enrichment.Predicate"
                }
            }
        },
        "gateway.ConnectionStatus": {
            "type": "object",
            "properties": {
                "auth_mode": {
                    "type": "string"
                },
                "healthy": {
                    "type": "boolean"
                },
                "name": {
                    "type": "string"
                },
                "oauth": {
                    "$ref": "#/definitions/connoauth.OAuthStatus"
                },
                "tools": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "gateway.ProbeTool": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string"
                },
                "local_name": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                }
            }
        },
        "github_com_txn2_mcp-data-platform_pkg_portal.itemInput": {
            "type": "object",
            "properties": {
                "asset_id": {
                    "type": "string",
                    "example": "550e8400-e29b-41d4-a716-446655440000"
                }
            }
        },
        "github_com_txn2_mcp-data-platform_pkg_portal.sectionInput": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string",
                    "example": "Summary of key findings"
                },
                "items": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/github_com_txn2_mcp-data-platform_pkg_portal.itemInput"
                    }
                },
                "title": {
                    "type": "string",
                    "example": "Key Findings"
                }
            }
        },
        "github_com_txn2_mcp-data-platform_pkg_resource.Resource": {
            "type": "object",
            "properties": {
                "category": {
                    "type": "string",
                    "example": "runbooks"
                },
                "created_at": {
                    "type": "string"
                },
                "description": {
                    "type": "string",
                    "example": "Step-by-step procedures for ETL pipeline operations"
                },
                "display_name": {
                    "type": "string",
                    "example": "ETL Runbook"
                },
                "filename": {
                    "type": "string",
                    "example": "etl-runbook.md"
                },
                "id": {
                    "type": "string",
                    "example": "res_01HK7R9F"
                },
                "mime_type": {
                    "type": "string",
                    "example": "text/markdown"
                },
                "s3_key": {
                    "type": "string",
                    "example": "resources/res_01HK7R9F/etl-runbook.md"
                },
                "scope": {
                    "allOf": [
                        {
                            "$ref": "#/definitions/resource.Scope"
                        }
                    ],
                    "example": "persona"
                },
                "scope_id": {
                    "description": "persona name or user sub; empty for global",
                    "type": "string",
                    "example": "data-engineer"
                },
                "size_bytes": {
                    "type": "integer",
                    "example": 34000
                },
                "tags": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "updated_at": {
                    "type": "string"
                },
                "uploader_email": {
                    "type": "string",
                    "example": "marcus.johnson@example.com"
                },
                "uploader_sub": {
                    "type": "string",
                    "example": "550e8400-e29b-41d4-a716-446655440000"
                },
                "uri": {
                    "type": "string",
                    "example": "mcp://persona/data-engineer/runbooks/etl-runbook.md"
                }
            }
        },
        "knowledge.Changeset": {
            "type": "object",
            "properties": {
                "applied_by": {
                    "type": "string",
                    "example": "admin@example.com"
                },
                "approved_by": {
                    "type": "string",
                    "example": "admin@example.com"
                },
                "change_type": {
                    "type": "string",
                    "example": "update_description"
                },
                "created_at": {
                    "type": "string",
                    "example": "2026-01-15T16:00:00Z"
                },
                "id": {
                    "type": "string",
                    "example": "cs_x1y2z3a4b5c6d7e8"
                },
                "new_value": {
                    "type": "object",
                    "additionalProperties": {}
                },
                "previous_value": {
                    "type": "object",
                    "additionalProperties": {}
                },
                "rolled_back": {
                    "type": "boolean",
                    "example": false
                },
                "rolled_back_at": {
                    "type": "string"
                },
                "rolled_back_by": {
                    "type": "string"
                },
                "source_insight_ids": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "target_urn": {
                    "type": "string",
                    "example": "urn:li:dataset:(urn:li:dataPlatform:trino,hive.sales.orders,PROD)"
                }
            }
        },
        "knowledge.EntityInsightSummary": {
            "type": "object",
            "properties": {
                "categories": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "count": {
                    "type": "integer"
                },
                "entity_urn": {
                    "type": "string"
                },
                "latest_at": {
                    "type": "string"
                }
            }
        },
        "knowledge.Insight": {
            "type": "object",
            "properties": {
                "applied_at": {
                    "type": "string"
                },
                "applied_by": {
                    "type": "string"
                },
                "captured_by": {
                    "type": "string",
                    "example": "analyst@example.com"
                },
                "category": {
                    "type": "string",
                    "example": "correction"
                },
                "changeset_ref": {
                    "type": "string"
                },
                "confidence": {
                    "type": "string",
                    "example": "high"
                },
                "created_at": {
                    "type": "string",
                    "example": "2026-01-15T14:30:00Z"
                },
                "entity_urns": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "id": {
                    "type": "string",
                    "example": "a1b2c3d4e5f67890a1b2c3d4e5f67890"
                },
                "insight_text": {
                    "type": "string",
                    "example": "The amount column represents gross margin before returns, not revenue."
                },
                "persona": {
                    "type": "string",
                    "example": "analyst"
                },
                "related_columns": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/knowledge.RelatedColumn"
                    }
                },
                "review_notes": {
                    "type": "string",
                    "example": "Verified with data engineering team"
                },
                "reviewed_at": {
                    "type": "string"
                },
                "reviewed_by": {
                    "description": "Lifecycle fields (populated by migrations 000007 and 000008)",
                    "type": "string",
                    "example": "admin@example.com"
                },
                "session_id": {
                    "type": "string",
                    "example": "sess_abc123"
                },
                "source": {
                    "type": "string",
                    "example": "user"
                },
                "status": {
                    "type": "string",
                    "example": "pending"
                },
                "suggested_actions": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/knowledge.SuggestedAction"
                    }
                }
            }
        },
        "knowledge.InsightStats": {
            "type": "object",
            "properties": {
                "by_category": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "integer"
                    }
                },
                "by_confidence": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "integer"
                    }
                },
                "by_entity": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/knowledge.EntityInsightSummary"
                    }
                },
                "by_status": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "integer"
                    }
                },
                "total_pending": {
                    "type": "integer"
                }
            }
        },
        "knowledge.RelatedColumn": {
            "type": "object",
            "properties": {
                "column": {
                    "type": "string",
                    "example": "amount"
                },
                "relevance": {
                    "type": "string",
                    "example": "direct"
                },
                "urn": {
                    "type": "string",
                    "example": "urn:li:dataset:(urn:li:dataPlatform:trino,hive.sales.orders,PROD)"
                }
            }
        },
        "knowledge.SuggestedAction": {
            "type": "object",
            "properties": {
                "action_type": {
                    "type": "string",
                    "example": "update_description"
                },
                "detail": {
                    "type": "string",
                    "example": "Gross margin before returns"
                },
                "query_description": {
                    "type": "string"
                },
                "query_sql": {
                    "type": "string"
                },
                "target": {
                    "type": "string",
                    "example": "amount"
                }
            }
        },
        "memory.Record": {
            "type": "object",
            "properties": {
                "category": {
                    "type": "string",
                    "example": "business_context"
                },
                "confidence": {
                    "type": "string",
                    "example": "high"
                },
                "content": {
                    "type": "string",
                    "example": "The daily_sales table in the retail schema is partitioned by date."
                },
                "created_at": {
                    "type": "string",
                    "example": "2026-03-18T08:11:08Z"
                },
                "created_by": {
                    "type": "string",
                    "example": "sarah.chen@example.com"
                },
                "dimension": {
                    "type": "string",
                    "example": "knowledge"
                },
                "embedding": {
                    "type": "array",
                    "items": {
                        "type": "number"
                    }
                },
                "entity_urns": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "id": {
                    "type": "string",
                    "example": "mem_a1b2c3d4e5f6"
                },
                "last_verified": {
                    "type": "string"
                },
                "metadata": {
                    "type": "object",
                    "additionalProperties": {}
                },
                "persona": {
                    "type": "string",
                    "example": "admin"
                },
                "related_columns": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/memory.RelatedColumn"
                    }
                },
                "source": {
                    "type": "string",
                    "example": "user"
                },
                "stale_at": {
                    "type": "string"
                },
                "stale_reason": {
                    "type": "string"
                },
                "status": {
                    "type": "string",
                    "example": "active"
                },
                "updated_at": {
                    "type": "string",
                    "example": "2026-03-18T08:11:08Z"
                }
            }
        },
        "memory.RelatedColumn": {
            "type": "object",
            "properties": {
                "column": {
                    "type": "string",
                    "example": "amount"
                },
                "relevance": {
                    "type": "string",
                    "example": "direct"
                },
                "urn": {
                    "type": "string",
                    "example": "urn:li:dataset:(urn:li:dataPlatform:trino,hive.sales.orders,PROD)"
                }
            }
        },
        "persona.AccessSource": {
            "type": "string",
            "enum": [
                "allow",
                "deny",
                "default"
            ],
            "x-enum-varnames": [
                "AccessSourceAllow",
                "AccessSourceDeny",
                "AccessSourceDefault"
            ]
        },
        "platform.ConnectionInstance": {
            "type": "object",
            "properties": {
                "config": {
                    "type": "object",
                    "additionalProperties": {}
                },
                "created_by": {
                    "type": "string",
                    "example": "admin@example.com"
                },
                "description": {
                    "type": "string",
                    "example": "Production data warehouse"
                },
                "kind": {
                    "type": "string",
                    "example": "trino"
                },
                "name": {
                    "type": "string",
                    "example": "acme-warehouse"
                },
                "updated_at": {
                    "type": "string",
                    "example": "2026-01-15T14:30:00Z"
                }
            }
        },
        "portal.Asset": {
            "type": "object",
            "properties": {
                "collections": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/portal.AssetCollectionRef"
                    }
                },
                "content_type": {
                    "type": "string",
                    "example": "text/html"
                },
                "created_at": {
                    "type": "string"
                },
                "current_version": {
                    "type": "integer",
                    "example": 1
                },
                "deleted_at": {
                    "type": "string"
                },
                "description": {
                    "type": "string",
                    "example": "Interactive revenue breakdown by region"
                },
                "id": {
                    "type": "string",
                    "example": "asset_01HK7R8Z8M0Y6A5G1R6FQ2VQNK"
                },
                "idempotency_key": {
                    "type": "string",
                    "example": "export-2026-04-18-abc123"
                },
                "name": {
                    "type": "string",
                    "example": "Q4 Revenue Dashboard"
                },
                "owner_email": {
                    "type": "string",
                    "example": "alice@example.com"
                },
                "owner_id": {
                    "type": "string",
                    "example": "550e8400-e29b-41d4-a716-446655440000"
                },
                "provenance": {
                    "$ref": "#/definitions/portal.Provenance"
                },
                "s3_bucket": {
                    "type": "string",
                    "example": "portal-assets"
                },
                "s3_key": {
                    "type": "string",
                    "example": "assets/01HK7R8Z/content.html"
                },
                "session_id": {
                    "type": "string",
                    "example": "sess_abc123"
                },
                "size_bytes": {
                    "type": "integer",
                    "example": 4200
                },
                "tags": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "thumbnail_s3_key": {
                    "type": "string",
                    "example": "assets/01HK7R8Z/thumb.png"
                },
                "updated_at": {
                    "type": "string"
                }
            }
        },
        "portal.AssetCollectionRef": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "example": "col_01HK7R8Z"
                },
                "name": {
                    "type": "string",
                    "example": "Q4 Performance Review"
                }
            }
        },
        "portal.Collection": {
            "type": "object",
            "properties": {
                "asset_tags": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "config": {
                    "$ref": "#/definitions/portal.CollectionConfig"
                },
                "created_at": {
                    "type": "string"
                },
                "deleted_at": {
                    "type": "string"
                },
                "description": {
                    "type": "string",
                    "example": "Executive collection with revenue dashboards"
                },
                "id": {
                    "type": "string",
                    "example": "col_01HK7R8Z"
                },
                "name": {
                    "type": "string",
                    "example": "Q4 Performance Review"
                },
                "owner_email": {
                    "type": "string",
                    "example": "alice@example.com"
                },
                "owner_id": {
                    "type": "string",
                    "example": "550e8400-e29b-41d4-a716-446655440000"
                },
                "sections": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/portal.CollectionSection"
                    }
                },
                "thumbnail_s3_key": {
                    "type": "string"
                },
                "updated_at": {
                    "type": "string"
                }
            }
        },
        "portal.CollectionConfig": {
            "type": "object",
            "properties": {
                "thumbnail_size": {
                    "description": "\"large\", \"medium\", \"small\", \"none\"",
                    "type": "string",
                    "example": "medium"
                }
            }
        },
        "portal.CollectionItem": {
            "type": "object",
            "properties": {
                "asset_content_type": {
                    "type": "string",
                    "example": "text/html"
                },
                "asset_description": {
                    "type": "string",
                    "example": "Interactive revenue breakdown"
                },
                "asset_id": {
                    "type": "string",
                    "example": "asset_01HK7R8Z8M0Y6A5G1R6FQ2VQNK"
                },
                "asset_name": {
                    "type": "string",
                    "example": "Q4 Revenue Dashboard"
                },
                "asset_thumbnail_s3_key": {
                    "type": "string"
                },
                "created_at": {
                    "type": "string"
                },
                "id": {
                    "type": "string",
                    "example": "item_01HK7R9D"
                },
                "position": {
                    "type": "integer",
                    "example": 0
                },
                "section_id": {
                    "type": "string",
                    "example": "sec_01HK7R9C"
                }
            }
        },
        "portal.CollectionSection": {
            "type": "object",
            "properties": {
                "collection_id": {
                    "type": "string",
                    "example": "col_01HK7R8Z"
                },
                "created_at": {
                    "type": "string"
                },
                "description": {
                    "type": "string",
                    "example": "High-level revenue and KPI snapshots"
                },
                "id": {
                    "type": "string",
                    "example": "sec_01HK7R9C"
                },
                "items": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/portal.CollectionItem"
                    }
                },
                "position": {
                    "type": "integer",
                    "example": 0
                },
                "title": {
                    "type": "string",
                    "example": "Overview"
                }
            }
        },
        "portal.Provenance": {
            "type": "object",
            "properties": {
                "session_id": {
                    "type": "string",
                    "example": "sess_abc123"
                },
                "tool_calls": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/portal.ProvenanceToolCall"
                    }
                },
                "user_id": {
                    "type": "string",
                    "example": "550e8400-e29b-41d4-a716-446655440000"
                }
            }
        },
        "portal.ProvenanceToolCall": {
            "type": "object",
            "properties": {
                "parameters": {
                    "type": "object",
                    "additionalProperties": {}
                },
                "timestamp": {
                    "type": "string",
                    "example": "2026-04-15T14:30:00Z"
                },
                "tool_name": {
                    "type": "string",
                    "example": "trino_query"
                }
            }
        },
        "portal.Share": {
            "type": "object",
            "properties": {
                "access_count": {
                    "type": "integer",
                    "example": 3
                },
                "asset_id": {
                    "type": "string",
                    "example": "asset_01HK7R8Z8M0Y6A5G1R6FQ2VQNK"
                },
                "collection_id": {
                    "type": "string"
                },
                "created_at": {
                    "type": "string"
                },
                "created_by": {
                    "type": "string",
                    "example": "alice@example.com"
                },
                "expires_at": {
                    "type": "string"
                },
                "hide_expiration": {
                    "type": "boolean",
                    "example": false
                },
                "id": {
                    "type": "string",
                    "example": "share_01HK7R9B"
                },
                "last_accessed_at": {
                    "type": "string"
                },
                "notice_text": {
                    "type": "string",
                    "example": "Proprietary \u0026 Confidential"
                },
                "permission": {
                    "allOf": [
                        {
                            "$ref": "#/definitions/portal.SharePermission"
                        }
                    ],
                    "example": "viewer"
                },
                "revoked": {
                    "type": "boolean",
                    "example": false
                },
                "shared_with_email": {
                    "type": "string",
                    "example": "bob@example.com"
                },
                "shared_with_user_id": {
                    "type": "string"
                },
                "token": {
                    "type": "string",
                    "example": "tk_a1b2c3d4e5f6"
                }
            }
        },
        "portal.SharePermission": {
            "type": "string",
            "enum": [
                "viewer",
                "editor"
            ],
            "x-enum-varnames": [
                "PermissionViewer",
                "PermissionEditor"
            ]
        },
        "portal.ShareSummary": {
            "type": "object",
            "properties": {
                "has_public_link": {
                    "type": "boolean",
                    "example": false
                },
                "has_user_share": {
                    "type": "boolean",
                    "example": true
                }
            }
        },
        "portal.SharedCollection": {
            "type": "object",
            "properties": {
                "collection": {
                    "$ref": "#/definitions/portal.Collection"
                },
                "permission": {
                    "allOf": [
                        {
                            "$ref": "#/definitions/portal.SharePermission"
                        }
                    ],
                    "example": "viewer"
                },
                "share_id": {
                    "type": "string",
                    "example": "share_01HK7R9E"
                },
                "shared_at": {
                    "type": "string"
                },
                "shared_by": {
                    "type": "string",
                    "example": "alice@example.com"
                }
            }
        },
        "portal.assetResponse": {
            "type": "object",
            "properties": {
                "collections": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/portal.AssetCollectionRef"
                    }
                },
                "content_type": {
                    "type": "string",
                    "example": "text/html"
                },
                "created_at": {
                    "type": "string"
                },
                "current_version": {
                    "type": "integer",
                    "example": 1
                },
                "deleted_at": {
                    "type": "string"
                },
                "description": {
                    "type": "string",
                    "example": "Interactive revenue breakdown by region"
                },
                "id": {
                    "type": "string",
                    "example": "asset_01HK7R8Z8M0Y6A5G1R6FQ2VQNK"
                },
                "idempotency_key": {
                    "type": "string",
                    "example": "export-2026-04-18-abc123"
                },
                "is_owner": {
                    "type": "boolean",
                    "example": true
                },
                "name": {
                    "type": "string",
                    "example": "Q4 Revenue Dashboard"
                },
                "owner_email": {
                    "type": "string",
                    "example": "alice@example.com"
                },
                "owner_id": {
                    "type": "string",
                    "example": "550e8400-e29b-41d4-a716-446655440000"
                },
                "provenance": {
                    "$ref": "#/definitions/portal.Provenance"
                },
                "s3_bucket": {
                    "type": "string",
                    "example": "portal-assets"
                },
                "s3_key": {
                    "type": "string",
                    "example": "assets/01HK7R8Z/content.html"
                },
                "session_id": {
                    "type": "string",
                    "example": "sess_abc123"
                },
                "share_permission": {
                    "allOf": [
                        {
                            "$ref": "#/definitions/portal.SharePermission"
                        }
                    ],
                    "example": "viewer"
                },
                "size_bytes": {
                    "type": "integer",
                    "example": 4200
                },
                "tags": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "thumbnail_s3_key": {
                    "type": "string",
                    "example": "assets/01HK7R8Z/thumb.png"
                },
                "updated_at": {
                    "type": "string"
                }
            }
        },
        "portal.createAssetRequest": {
            "type": "object",
            "properties": {
                "content": {
                    "type": "string",
                    "example": "# Prompt content"
                },
                "content_type": {
                    "type": "string",
                    "example": "text/markdown"
                },
                "description": {
                    "type": "string",
                    "example": "Saved from prompt library"
                },
                "name": {
                    "type": "string",
                    "example": "My Prompt"
                },
                "tags": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "portal.createCollectionRequest": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string",
                    "example": "Quarterly analysis collection"
                },
                "name": {
                    "type": "string",
                    "example": "Q4 Analysis"
                }
            }
        },
        "portal.createShareRequest": {
            "type": "object",
            "properties": {
                "expires_in": {
                    "description": "duration string, e.g. \"24h\"",
                    "type": "string",
                    "example": "24h"
                },
                "hide_expiration": {
                    "type": "boolean",
                    "example": false
                },
                "notice_text": {
                    "description": "nil = default, \"\" = hidden, custom = as-is",
                    "type": "string",
                    "example": "Confidential"
                },
                "permission": {
                    "description": "\"viewer\" (default) or \"editor\"",
                    "type": "string",
                    "example": "viewer"
                },
                "shared_with_email": {
                    "type": "string",
                    "example": "colleague@example.com"
                },
                "shared_with_user_id": {
                    "type": "string",
                    "example": "550e8400-e29b-41d4-a716-446655440000"
                }
            }
        },
        "portal.getCollectionResponse": {
            "type": "object",
            "properties": {
                "asset_tags": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "config": {
                    "$ref": "#/definitions/portal.CollectionConfig"
                },
                "created_at": {
                    "type": "string"
                },
                "deleted_at": {
                    "type": "string"
                },
                "description": {
                    "type": "string",
                    "example": "Executive collection with revenue dashboards"
                },
                "id": {
                    "type": "string",
                    "example": "col_01HK7R8Z"
                },
                "is_owner": {
                    "type": "boolean",
                    "example": true
                },
                "name": {
                    "type": "string",
                    "example": "Q4 Performance Review"
                },
                "owner_email": {
                    "type": "string",
                    "example": "alice@example.com"
                },
                "owner_id": {
                    "type": "string",
                    "example": "550e8400-e29b-41d4-a716-446655440000"
                },
                "sections": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/portal.CollectionSection"
                    }
                },
                "share_permission": {
                    "allOf": [
                        {
                            "$ref": "#/definitions/portal.SharePermission"
                        }
                    ],
                    "example": "viewer"
                },
                "thumbnail_s3_key": {
                    "type": "string"
                },
                "updated_at": {
                    "type": "string"
                }
            }
        },
        "portal.listCollectionsResponse": {
            "type": "object",
            "properties": {
                "data": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/portal.Collection"
                    }
                },
                "limit": {
                    "type": "integer",
                    "example": 20
                },
                "offset": {
                    "type": "integer",
                    "example": 0
                },
                "share_summaries": {
                    "type": "object",
                    "additionalProperties": {
                        "$ref": "#/definitions/portal.ShareSummary"
                    }
                },
                "total": {
                    "type": "integer",
                    "example": 10
                }
            }
        },
        "portal.listSharedCollectionsResponse": {
            "type": "object",
            "properties": {
                "data": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/portal.SharedCollection"
                    }
                },
                "limit": {
                    "type": "integer",
                    "example": 20
                },
                "offset": {
                    "type": "integer",
                    "example": 0
                },
                "total": {
                    "type": "integer",
                    "example": 5
                }
            }
        },
        "portal.meResponse": {
            "type": "object",
            "properties": {
                "email": {
                    "type": "string",
                    "example": "analyst@example.com"
                },
                "is_admin": {
                    "type": "boolean",
                    "example": false
                },
                "persona": {
                    "type": "string",
                    "example": "analyst"
                },
                "roles": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "analyst",
                        "data_engineer"
                    ]
                },
                "tools": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "trino_query",
                        "datahub_search"
                    ]
                },
                "user_id": {
                    "type": "string",
                    "example": "550e8400-e29b-41d4-a716-446655440000"
                }
            }
        },
        "portal.memoryStatsResponse": {
            "type": "object",
            "properties": {
                "by_category": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "integer"
                    }
                },
                "by_dimension": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "integer"
                    }
                },
                "by_status": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "integer"
                    }
                },
                "total": {
                    "type": "integer",
                    "example": 150
                }
            }
        },
        "portal.paginatedResponse": {
            "type": "object",
            "properties": {
                "data": {},
                "limit": {
                    "type": "integer",
                    "example": 20
                },
                "offset": {
                    "type": "integer",
                    "example": 0
                },
                "share_summaries": {
                    "type": "object",
                    "additionalProperties": {
                        "$ref": "#/definitions/portal.ShareSummary"
                    }
                },
                "total": {
                    "type": "integer",
                    "example": 42
                }
            }
        },
        "portal.portalPromptCreateRequest": {
            "type": "object",
            "properties": {
                "arguments": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/prompt.Argument"
                    }
                },
                "category": {
                    "type": "string",
                    "example": "analysis"
                },
                "content": {
                    "type": "string",
                    "example": "Analyze the following data: {{data}}"
                },
                "description": {
                    "type": "string",
                    "example": "A prompt for data analysis workflows"
                },
                "display_name": {
                    "type": "string",
                    "example": "My Analysis Prompt"
                },
                "name": {
                    "type": "string",
                    "example": "my-analysis-prompt"
                }
            }
        },
        "portal.portalPromptListResponse": {
            "type": "object",
            "properties": {
                "available": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/prompt.Prompt"
                    }
                },
                "personal": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/prompt.Prompt"
                    }
                }
            }
        },
        "portal.problemDetail": {
            "type": "object",
            "properties": {
                "detail": {
                    "type": "string"
                },
                "status": {
                    "type": "integer"
                },
                "title": {
                    "type": "string"
                },
                "type": {
                    "type": "string"
                }
            }
        },
        "portal.setSectionsRequest": {
            "type": "object",
            "properties": {
                "sections": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/github_com_txn2_mcp-data-platform_pkg_portal.sectionInput"
                    }
                }
            }
        },
        "portal.shareResponse": {
            "type": "object",
            "properties": {
                "share": {
                    "$ref": "#/definitions/portal.Share"
                },
                "share_url": {
                    "type": "string",
                    "example": "https://platform.example.com/portal/view/abc123"
                }
            }
        },
        "portal.statusResponse": {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string",
                    "example": "updated"
                }
            }
        },
        "portal.updateAssetRequest": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string",
                    "example": "Updated quarterly revenue analysis"
                },
                "name": {
                    "type": "string",
                    "example": "Q4 Revenue Report"
                },
                "tags": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "finance",
                        "quarterly"
                    ]
                }
            }
        },
        "portal.updateCollectionRequest": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string",
                    "example": "Updated description"
                },
                "name": {
                    "type": "string",
                    "example": "Updated Collection Name"
                }
            }
        },
        "prompt.Argument": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string",
                    "example": "The date to analyze (YYYY-MM-DD)"
                },
                "name": {
                    "type": "string",
                    "example": "date"
                },
                "required": {
                    "type": "boolean",
                    "example": true
                }
            }
        },
        "prompt.Prompt": {
            "type": "object",
            "properties": {
                "arguments": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/prompt.Argument"
                    }
                },
                "category": {
                    "type": "string",
                    "example": "analysis"
                },
                "content": {
                    "type": "string",
                    "example": "Analyze sales data for {date} grouped by region."
                },
                "created_at": {
                    "type": "string",
                    "example": "2026-01-15T14:30:00Z"
                },
                "description": {
                    "type": "string",
                    "example": "Generate a daily sales summary by region"
                },
                "display_name": {
                    "type": "string",
                    "example": "Daily Sales Report"
                },
                "enabled": {
                    "type": "boolean",
                    "example": true
                },
                "id": {
                    "type": "string",
                    "example": "prompt_a1b2c3d4"
                },
                "name": {
                    "type": "string",
                    "example": "daily-sales-report"
                },
                "owner_email": {
                    "type": "string",
                    "example": "admin@example.com"
                },
                "personas": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "example": [
                        "analyst",
                        "data-engineer"
                    ]
                },
                "scope": {
                    "type": "string",
                    "example": "persona"
                },
                "source": {
                    "type": "string",
                    "example": "database"
                },
                "updated_at": {
                    "type": "string",
                    "example": "2026-01-15T14:30:00Z"
                }
            }
        },
        "resource.Scope": {
            "type": "string",
            "enum": [
                "global",
                "persona",
                "user"
            ],
            "x-enum-varnames": [
                "ScopeGlobal",
                "ScopePersona",
                "ScopeUser"
            ]
        },
        "resource.Update": {
            "type": "object",
            "properties": {
                "category": {
                    "type": "string"
                },
                "description": {
                    "type": "string"
                },
                "display_name": {
                    "type": "string"
                },
                "tags": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "resource.errorResponse": {
            "type": "object",
            "properties": {
                "error": {
                    "type": "string",
                    "example": "descriptive error message"
                }
            }
        },
        "resource.listResponse": {
            "type": "object",
            "properties": {
                "resources": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/github_com_txn2_mcp-data-platform_pkg_resource.Resource"
                    }
                },
                "total": {
                    "type": "integer",
                    "example": 42
                }
            }
        }
    },
    "securityDefinitions": {
        "ApiKeyAuth": {
            "type": "apiKey",
            "name": "X-API-Key",
            "in": "header"
        },
        "BearerAuth": {
            "type": "apiKey",
            "name": "Authorization",
            "in": "header"
        }
    }
,"tags":[{"name": "User", "description": "Current user identity, roles, persona, and available tools."}, {"name": "Activity", "description": "Personal analytics for the authenticated user's tool usage. Timeseries, breakdowns, and summary statistics scoped to the calling user."}, {"name": "Assets", "description": "AI-generated artifacts \u2014 dashboards, reports, visualizations, and data exports. Supports HTML, JSX, SVG, Markdown, and CSV content types with versioning, thumbnails, and sharing."}, {"name": "Collections", "description": "Curated groups of assets organized into ordered sections with markdown descriptions. Collections support sharing via public links and user-level permissions."}, {"name": "Knowledge", "description": "Domain knowledge captured during AI sessions. Insights go through an admin review workflow before being written back to the data catalog. Includes insight statistics and governance lifecycle tracking."}, {"name": "Memory", "description": "Persistent memory records accumulated across sessions \u2014 corrections, preferences, business context, and data quality observations. Backed by PostgreSQL with pgvector for semantic search."}, {"name": "Prompts", "description": "Reusable prompt templates with argument placeholders. Users manage personal prompts and browse available global, persona, and system prompts."}, {"name": "Resources", "description": "Human-uploaded reference materials \u2014 SQL templates, runbooks, checklists, and brand assets. Scoped by visibility (global, persona, user) and accessible to AI agents via the MCP resources protocol."}, {"name": "Shares", "description": "Asset and collection sharing via public links (token-based, time-limited) and user shares (email-based with viewer/editor permissions)."}, {"name": "Audit", "description": "Platform-wide audit log of every tool call. Paginated event queries with filtering, aggregate statistics, performance percentiles, enrichment metrics, and discovery pattern analytics."}, {"name": "Auth Keys", "description": "API key management for programmatic access. Create, list, and revoke keys with role assignment and expiration. Keys from the config file are read-only."}, {"name": "Config", "description": "Platform configuration management. Read the active config, export as YAML, and manage per-key database overrides for whitelisted settings with hot-reload."}, {"name": "Connections", "description": "Toolkit connection management for Trino, DataHub, and S3 backends. View file-configured connections, create database-managed instances, and inspect connection details."}, {"name": "Personas", "description": "Role-based access control profiles that determine which tools and connections a user can access. Each persona defines allow/deny patterns, context overrides, and priority-based role mapping."}, {"name": "System", "description": "Platform identity, version, runtime feature availability, registered tools, and toolkit connections."}, {"name": "Tools", "description": "Tool schema introspection and interactive execution. Browse JSON schemas for all registered tools and execute tool calls with parameter validation."}],"x-tagGroups":[{"name": "User API", "tags": ["User", "Activity", "Assets", "Collections", "Knowledge", "Memory", "Prompts", "Resources", "Shares"]}, {"name": "Admin API", "tags": ["Audit", "Auth Keys", "Config", "Connections", "Personas", "System", "Tools"]}]}`

// SwaggerInfo holds exported Swagger Info so clients can modify it
var SwaggerInfo = &swag.Spec{
	Version:          "1.0",
	Host:             "localhost:8080",
	BasePath:         "/api/v1",
	Schemes:          []string{},
	Title:            "MCP Data Platform API",
	Description:      "REST API for the MCP Data Platform. Covers admin endpoints (system, config, personas, auth keys, audit, knowledge, memory, connections), portal endpoints (assets, collections, shares, prompts, activity), and resource management.",
	InfoInstanceName: "swagger",
	SwaggerTemplate:  docTemplate,
	LeftDelim:        "{{",
	RightDelim:       "}}",
}

func init() {
	swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
}
