{
  "openapi": "3.1.0",
  "info": {
    "title": "Live Neon API",
    "version": "1.0.0",
    "description": "AI agent identity platform. Define, observe, and evolve structured identities for AI agents — beliefs, responsibilities, and system prompts that stay consistent across any LLM or framework.",
    "contact": {
      "name": "Live Neon",
      "url": "https://agentpersona.live"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://agentpersona.live/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Agents",
      "description": "Manage AI agents with structured identities"
    },
    {
      "name": "Beliefs",
      "description": "Agent soul — identity beliefs across 5 categories"
    },
    {
      "name": "Responsibilities",
      "description": "Agent accountabilities across 5 categories"
    },
    {
      "name": "Organizations",
      "description": "Multi-tenant organization management"
    },
    {
      "name": "API Keys",
      "description": "Org-scoped API key management (session auth only)"
    },
    {
      "name": "Groups",
      "description": "Organizational groupings for agents"
    },
    {
      "name": "Models",
      "description": "LLM model configurations"
    },
    {
      "name": "Environments",
      "description": "Deployment contexts (production, staging, etc.)"
    },
    {
      "name": "Conversations",
      "description": "Conversation sessions with messages"
    },
    {
      "name": "Content",
      "description": "Content items and sources for PBD pipeline"
    },
    {
      "name": "GitHub",
      "description": "GitHub connections and OAuth"
    },
    {
      "name": "X Connections",
      "description": "X.com/Twitter connections for tweet sync"
    },
    {
      "name": "LinkedIn Import",
      "description": "Import content from LinkedIn data export ZIP files"
    },
    {
      "name": "Observations",
      "description": "Read-only observations generated by PBD pipeline"
    },
    {
      "name": "Signals",
      "description": "Read-only clustered signals from PBD pipeline"
    },
    {
      "name": "Bootstrap",
      "description": "Import agent definitions from open-source repos"
    },
    {
      "name": "Org Beliefs",
      "description": "Organization-level beliefs (brand identity) that cascade to all agents"
    },
    {
      "name": "Org Responsibilities",
      "description": "Organization-level responsibilities that cascade to all agents"
    },
    {
      "name": "Group Beliefs",
      "description": "Group-level beliefs (team identity) that cascade to group members"
    },
    {
      "name": "Group Responsibilities",
      "description": "Group-level responsibilities that cascade to group members"
    },
    {
      "name": "Agent Overrides",
      "description": "Agent-level overrides for inherited beliefs/responsibilities"
    },
    {
      "name": "Utility",
      "description": "PBD processing and GitHub tree browsing"
    },
    {
      "name": "Cron",
      "description": "Auto-sync cron endpoint (CRON_SECRET auth)"
    },
    {
      "name": "Background Jobs",
      "description": "Track background job status and progress"
    },
    {
      "name": "Consensus",
      "description": "Detect and promote consensus beliefs/responsibilities across agents"
    },
    {
      "name": "Registration",
      "description": "Programmatic account and organization creation — zero PII required"
    },
    {
      "name": "Account",
      "description": "View and update account details"
    }
  ],
  "paths": {
    "/register": {
      "post": {
        "tags": [
          "Registration"
        ],
        "operationId": "register",
        "summary": "Register a new account",
        "description": "Create a new account, organization, and API key in one call. Zero fields required — email is optional for account recovery. Returns an API key immediately. This is the recommended path for AI agents.",
        "security": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Optional — for account recovery later"
                  },
                  "password": {
                    "type": "string",
                    "description": "Optional — for dashboard login"
                  },
                  "org_name": {
                    "type": "string",
                    "description": "Organization name (auto-generated if omitted)"
                  },
                  "org_slug": {
                    "type": "string",
                    "description": "Organization URL slug (auto-generated if omitted)"
                  },
                  "display_name": {
                    "type": "string",
                    "description": "Display name for the account"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account created — returns API key (shown once)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "your_token": {
                      "type": "string",
                      "description": "API key to use immediately as Bearer token"
                    },
                    "key": {
                      "type": "string",
                      "description": "Same API key (alias)"
                    },
                    "organization": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "slug": {
                          "type": "string"
                        }
                      }
                    },
                    "user_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "email": {
                      "type": "string"
                    },
                    "warning": {
                      "type": "string",
                      "nullable": true
                    },
                    "next_steps": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited — 5 requests/min per IP"
          }
        }
      }
    },
    "/account": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getAccount",
        "summary": "Get account details",
        "description": "View the current account's details including email, display name, and account flags.",
        "responses": {
          "200": {
            "description": "Account details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "email": {
                      "type": "string"
                    },
                    "display_name": {
                      "type": "string"
                    },
                    "is_agent": {
                      "type": "boolean"
                    },
                    "has_email": {
                      "type": "boolean"
                    },
                    "has_password": {
                      "type": "boolean"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "patch": {
        "tags": [
          "Account"
        ],
        "operationId": "updateAccount",
        "summary": "Update account details",
        "description": "Update email, password, or display name. Rate limited: 10 requests/min per key.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "password": {
                    "type": "string"
                  },
                  "display_name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "email": {
                      "type": "string"
                    },
                    "display_name": {
                      "type": "string"
                    },
                    "has_email": {
                      "type": "boolean"
                    },
                    "updated": {
                      "type": "boolean"
                    },
                    "next_steps": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/agents": {
      "get": {
        "tags": [
          "Agents"
        ],
        "operationId": "listAgents",
        "summary": "List agents",
        "description": "List agents in an organization. Supports filtering by group and pagination.",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdQuery"
          },
          {
            "$ref": "#/components/parameters/orgSlugQuery"
          },
          {
            "name": "groupId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by group ID"
          },
          {
            "name": "include",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated joins: beliefs, responsibilities (returns identity data inline)"
          },
          {
            "$ref": "#/components/parameters/limitQuery"
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of agents",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/AgentSummary"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "post": {
        "tags": [
          "Agents"
        ],
        "operationId": "createAgent",
        "summary": "Create agent",
        "description": "Create a new agent. Optionally triggers background avatar generation if avatarPrompt is provided.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAgentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agent created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Agent"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/agents/{agentId}": {
      "get": {
        "tags": [
          "Agents"
        ],
        "operationId": "getAgent",
        "summary": "Get agent",
        "description": "Returns the full agent profile including beliefs, responsibilities, and group information.",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Agent with beliefs and responsibilities",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentDetail"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "patch": {
        "tags": [
          "Agents"
        ],
        "operationId": "updateAgent",
        "summary": "Update agent",
        "description": "Update agent fields. Regenerates system prompt if location, timezone, or jobTitle changed. Triggers avatar generation if avatarPrompt provided.",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAgentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated agent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Agent"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Agents"
        ],
        "operationId": "deleteAgent",
        "summary": "Delete agent",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Agent deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/agents/{agentId}/models": {
      "get": {
        "tags": [
          "Agents"
        ],
        "operationId": "listAgentModels",
        "summary": "List agent model assignments",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          },
          {
            "name": "tier",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by tier (e.g., planner, worker, reviewer)"
          },
          {
            "$ref": "#/components/parameters/limitQuery"
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Agent model assignments",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AgentModelAssignment"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "post": {
        "tags": [
          "Agents"
        ],
        "operationId": "addAgentModel",
        "summary": "Assign model to agent",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "environmentId",
                  "modelId"
                ],
                "properties": {
                  "environmentId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "modelId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "isPrimary": {
                    "type": "boolean",
                    "default": true
                  },
                  "tier": {
                    "type": "string",
                    "nullable": true,
                    "description": "Freeform tier name (e.g., planner, worker, reviewer). NULL = simple single-model assignment. Unique per (agent, environment, tier)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Model assigned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentModelAssignment"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Agents"
        ],
        "operationId": "removeAgentModel",
        "summary": "Remove model from agent",
        "description": "Requires a JSON request body with environmentId and modelId.",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "environmentId",
                  "modelId"
                ],
                "properties": {
                  "environmentId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "modelId": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Model removed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/agents/{agentId}/regenerate-prompt": {
      "post": {
        "tags": [
          "Agents"
        ],
        "operationId": "regeneratePrompt",
        "summary": "Regenerate system prompt",
        "description": "Forces regeneration of the agent's system prompt from current beliefs and responsibilities.",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Regenerated prompt",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "systemPrompt": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/agents/{agentId}/files": {
      "get": {
        "tags": [
          "Agents"
        ],
        "operationId": "getAgentFiles",
        "summary": "Get agent files",
        "description": "Returns agent data as downloadable markdown files.",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "agent",
                "soul",
                "responsibilities",
                "identity"
              ],
              "default": "agent"
            },
            "description": "File type to return"
          },
          {
            "name": "download",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Set Content-Disposition for download"
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown file content",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/agents/{agentId}/snapshots": {
      "get": {
        "tags": [
          "Agents"
        ],
        "operationId": "listSnapshots",
        "summary": "List genome snapshots",
        "description": "Returns all genome snapshots for the agent, ordered by most recent first. Does not include the full genome JSONB.",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          },
          {
            "$ref": "#/components/parameters/limitQuery"
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of snapshots",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "snapshots": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SnapshotSummary"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Agents"
        ],
        "operationId": "createSnapshot",
        "summary": "Create genome snapshot",
        "description": "Captures the agent's current beliefs and responsibilities as a timestamped JSON genome snapshot.",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "Optional label (e.g., 'before bootstrap', 'post-PBD round 3')"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Snapshot created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "snapshot": {
                      "$ref": "#/components/schemas/SnapshotSummary"
                    },
                    "next_steps": {
                      "$ref": "#/components/schemas/NextSteps"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/agents/{agentId}/snapshots/{snapshotId}": {
      "get": {
        "tags": [
          "Agents"
        ],
        "operationId": "getSnapshot",
        "summary": "Get snapshot with full genome",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          },
          {
            "name": "snapshotId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot with genome",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "snapshot": {
                      "$ref": "#/components/schemas/SnapshotDetail"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/agents/{agentId}/snapshots/diff": {
      "get": {
        "tags": [
          "Agents"
        ],
        "operationId": "diffSnapshots",
        "summary": "Compare two snapshots",
        "description": "Computes the diff between two snapshots. Returns items added and removed for both beliefs and responsibilities.",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          },
          {
            "name": "a",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Snapshot A ID (base)"
          },
          {
            "name": "b",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Snapshot B ID (comparison)"
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot diff",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SnapshotDiff"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/agents/{agentId}/responsibility-gaps": {
      "post": {
        "tags": [
          "Agents"
        ],
        "operationId": "detectResponsibilityGaps",
        "summary": "Detect responsibility gaps",
        "description": "Analyzes which responsibility categories are empty or thin, then uses Claude to generate suggestions for each gap category.",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Gap analysis with suggestions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "gaps": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ResponsibilityGap"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/agents/{agentId}/dynamic-prompt": {
      "post": {
        "tags": [
          "Agents"
        ],
        "operationId": "generateDynamicPrompt",
        "summary": "Generate randomized prompt variant",
        "description": "Generates a fresh system prompt with per-invocation randomization to combat persona numbing. Starred items always included, non-starred shuffled and sampled per category.",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "seed": {
                    "type": "number",
                    "description": "Deterministic seed for reproducible output"
                  },
                  "config": {
                    "type": "object",
                    "description": "Override dynamic prompt config for this call",
                    "properties": {
                      "enabled": {
                        "type": "boolean"
                      },
                      "emphasis_rate": {
                        "type": "number"
                      },
                      "min_pool_size": {
                        "type": "integer"
                      },
                      "category_overrides": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Dynamic prompt with manifest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DynamicPromptResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/agents/bulk": {
      "patch": {
        "tags": ["Agents"],
        "operationId": "bulkUpdateAgents",
        "summary": "Bulk update agents",
        "description": "Update up to 50 agents at once. Regenerates system prompts for agents whose name, jobTitle, location, or timezone changed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agents"],
                "properties": {
                  "agents": {
                    "type": "array",
                    "maxItems": 50,
                    "items": {
                      "type": "object",
                      "required": ["id"],
                      "properties": {
                        "id": { "type": "string", "format": "uuid" },
                        "name": { "type": "string" },
                        "location": { "type": "string" },
                        "timezone": { "type": "string" },
                        "jobTitle": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bulk update result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "updated": { "type": "integer" },
                    "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSummary" } }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/agents/{agentId}/diff": {
      "get": {
        "tags": ["Agents"],
        "operationId": "getAgentDiff",
        "summary": "Get agent identity diff",
        "description": "Returns beliefs and responsibilities added or modified since a given date.",
        "parameters": [
          { "$ref": "#/components/parameters/agentIdPath" },
          {
            "name": "since",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "format": "date-time" },
            "description": "ISO 8601 date to diff from"
          }
        ],
        "responses": {
          "200": {
            "description": "Diff of beliefs and responsibilities since the given date",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "since": { "type": "string", "format": "date-time" },
                    "beliefs": {
                      "type": "object",
                      "properties": {
                        "added": { "type": "array", "items": { "$ref": "#/components/schemas/Belief" } },
                        "modified": { "type": "array", "items": { "$ref": "#/components/schemas/Belief" } }
                      }
                    },
                    "responsibilities": {
                      "type": "object",
                      "properties": {
                        "added": { "type": "array", "items": { "$ref": "#/components/schemas/Responsibility" } },
                        "modified": { "type": "array", "items": { "$ref": "#/components/schemas/Responsibility" } }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/beliefs": {
      "get": {
        "tags": [
          "Beliefs"
        ],
        "operationId": "listBeliefs",
        "summary": "List beliefs",
        "description": "List beliefs for an agent or group with optional filters. When groupId is provided, returns beliefs from all agents in the group with agent name attribution.",
        "parameters": [
          {
            "name": "agentId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by agent (required if groupId not provided)"
          },
          {
            "name": "groupId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "List all agent beliefs in a group with agent name attribution"
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/BeliefCategory"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/Status"
            }
          },
          {
            "name": "starred",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "hidden",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/limitQuery"
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of beliefs",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Belief"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Beliefs"
        ],
        "operationId": "createBelief",
        "summary": "Create belief",
        "description": "Create a new belief for an agent. Statements are normalized before storage. Regenerates the agent's system prompt.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBeliefRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Belief created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Belief"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/beliefs/{beliefId}": {
      "patch": {
        "tags": [
          "Beliefs"
        ],
        "operationId": "updateBelief",
        "summary": "Update belief (scope-aware)",
        "description": "Scope-aware: automatically detects whether the belief is agent-level, group-level, or org-level. Returns _scope field in response. Approving sets approved_by and unhides. Rejecting hides the belief. Regenerates prompt if status changed.",
        "parameters": [
          {
            "name": "beliefId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateBeliefRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated belief",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Belief"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Beliefs"
        ],
        "operationId": "deleteBelief",
        "summary": "Delete belief (scope-aware)",
        "description": "Scope-aware: automatically detects whether the belief is agent-level, group-level, or org-level. PBD-discovered beliefs are hidden instead of deleted to preserve discovery history. Returns { action: 'deleted', scope } for manual items or { action: 'hidden', reason } for PBD items. Returns 404 if not found in any scope.",
        "parameters": [
          {
            "name": "beliefId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Belief deleted or hidden",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "action": { "type": "string", "enum": ["deleted", "hidden"] },
                    "scope": { "type": "string", "enum": ["agent", "group", "org"] },
                    "reason": { "type": "string" }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/beliefs/{beliefId}/star": {
      "post": {
        "tags": [
          "Beliefs"
        ],
        "operationId": "toggleBeliefStar",
        "summary": "Toggle belief starred",
        "description": "Toggles the starred flag. Starred beliefs are emphasized in the system prompt.",
        "parameters": [
          {
            "name": "beliefId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Belief with toggled starred value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Belief"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/beliefs/{beliefId}/hide": {
      "post": {
        "tags": [
          "Beliefs"
        ],
        "operationId": "toggleBeliefHide",
        "summary": "Toggle belief hidden",
        "description": "Toggles the hidden flag. Hidden beliefs are excluded from the system prompt. Regenerates prompt.",
        "parameters": [
          {
            "name": "beliefId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Belief with toggled hidden value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Belief"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/beliefs/bulk": {
      "post": {
        "tags": ["Beliefs"],
        "operationId": "bulkCreateBeliefs",
        "summary": "Bulk create beliefs",
        "description": "Create up to 100 beliefs at once. Single prompt regeneration after all beliefs created.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agentId", "beliefs"],
                "properties": {
                  "agentId": { "type": "string", "format": "uuid" },
                  "beliefs": {
                    "type": "array",
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "required": ["category", "statement"],
                      "properties": {
                        "category": { "$ref": "#/components/schemas/BeliefCategory" },
                        "statement": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Bulk create result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "created": { "type": "integer" },
                    "beliefs": { "type": "array", "items": { "$ref": "#/components/schemas/Belief" } }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "patch": {
        "tags": ["Beliefs"],
        "operationId": "bulkUpdateBeliefs",
        "summary": "Bulk update beliefs (cross-scope)",
        "description": "Bulk star, hide, or approve beliefs across all scopes (agent, group, and org beliefs in one call). Regenerates prompt for all affected agents.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["ids", "updates"],
                "properties": {
                  "ids": { "type": "array", "items": { "type": "string", "format": "uuid" } },
                  "updates": {
                    "type": "object",
                    "properties": {
                      "starred": { "type": "boolean" },
                      "hidden": { "type": "boolean" },
                      "status": { "$ref": "#/components/schemas/Status" }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bulk update result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "updated": { "type": "integer" },
                    "agents_affected": { "type": "integer" },
                    "groups_affected": { "type": "integer" },
                    "orgs_affected": { "type": "integer" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/responsibilities": {
      "get": {
        "tags": [
          "Responsibilities"
        ],
        "operationId": "listResponsibilities",
        "summary": "List responsibilities",
        "parameters": [
          {
            "name": "agentId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ResponsibilityCategory"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/Status"
            }
          },
          {
            "name": "starred",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "hidden",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/limitQuery"
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of responsibilities",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Responsibility"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Responsibilities"
        ],
        "operationId": "createResponsibility",
        "summary": "Create responsibility",
        "description": "Create a new responsibility for an agent. Statements are normalized before storage. Regenerates the agent's system prompt.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateResponsibilityRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Responsibility created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Responsibility"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/responsibilities/{responsibilityId}": {
      "patch": {
        "tags": [
          "Responsibilities"
        ],
        "operationId": "updateResponsibility",
        "summary": "Update responsibility (scope-aware)",
        "description": "Scope-aware: automatically detects whether the responsibility is agent-level, group-level, or org-level. Returns _scope field in response. Same approval/rejection logic as beliefs. Regenerates prompt if status changed.",
        "parameters": [
          {
            "name": "responsibilityId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateResponsibilityRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated responsibility",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Responsibility"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Responsibilities"
        ],
        "operationId": "deleteResponsibility",
        "summary": "Delete responsibility (scope-aware)",
        "description": "Scope-aware: automatically detects whether the responsibility is agent-level, group-level, or org-level. PBD-discovered responsibilities are hidden instead of deleted to preserve discovery history. Returns { action: 'deleted', scope } for manual items or { action: 'hidden', reason } for PBD items. Returns 404 if not found in any scope.",
        "parameters": [
          {
            "name": "responsibilityId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Responsibility deleted or hidden",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "action": { "type": "string", "enum": ["deleted", "hidden"] },
                    "scope": { "type": "string", "enum": ["agent", "group", "org"] },
                    "reason": { "type": "string" }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/responsibilities/{responsibilityId}/star": {
      "post": {
        "tags": [
          "Responsibilities"
        ],
        "operationId": "toggleResponsibilityStar",
        "summary": "Toggle responsibility starred",
        "parameters": [
          {
            "name": "responsibilityId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Responsibility with toggled starred value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Responsibility"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/responsibilities/{responsibilityId}/hide": {
      "post": {
        "tags": [
          "Responsibilities"
        ],
        "operationId": "toggleResponsibilityHide",
        "summary": "Toggle responsibility hidden",
        "description": "Toggles the hidden flag. Hidden responsibilities are excluded from the system prompt. Regenerates prompt.",
        "parameters": [
          {
            "name": "responsibilityId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Responsibility with toggled hidden value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Responsibility"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/responsibilities/bulk": {
      "post": {
        "tags": ["Responsibilities"],
        "operationId": "bulkCreateResponsibilities",
        "summary": "Bulk create responsibilities",
        "description": "Create up to 100 responsibilities at once. Single prompt regeneration after all created.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["agentId", "responsibilities"],
                "properties": {
                  "agentId": { "type": "string", "format": "uuid" },
                  "responsibilities": {
                    "type": "array",
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "required": ["category", "statement"],
                      "properties": {
                        "category": { "$ref": "#/components/schemas/ResponsibilityCategory" },
                        "statement": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Bulk create result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "created": { "type": "integer" },
                    "responsibilities": { "type": "array", "items": { "$ref": "#/components/schemas/Responsibility" } }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "patch": {
        "tags": ["Responsibilities"],
        "operationId": "bulkUpdateResponsibilities",
        "summary": "Bulk update responsibilities (cross-scope)",
        "description": "Bulk star, hide, or approve responsibilities across all scopes (agent, group, and org responsibilities in one call). Regenerates prompt for all affected agents.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["ids", "updates"],
                "properties": {
                  "ids": { "type": "array", "items": { "type": "string", "format": "uuid" } },
                  "updates": {
                    "type": "object",
                    "properties": {
                      "starred": { "type": "boolean" },
                      "hidden": { "type": "boolean" },
                      "status": { "$ref": "#/components/schemas/Status" }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bulk update result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "updated": { "type": "integer" },
                    "agents_affected": { "type": "integer" },
                    "groups_affected": { "type": "integer" },
                    "orgs_affected": { "type": "integer" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/organizations": {
      "get": {
        "tags": [
          "Organizations"
        ],
        "operationId": "listOrganizations",
        "summary": "List user's organizations",
        "description": "Returns all organizations the authenticated user belongs to, with their role in each.",
        "responses": {
          "200": {
            "description": "Organizations with roles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "role": {
                            "type": "string",
                            "enum": [
                              "owner",
                              "admin",
                              "member"
                            ]
                          },
                          "organization": {
                            "$ref": "#/components/schemas/Organization"
                          }
                        }
                      }
                    },
                    "next_steps": {
                      "$ref": "#/components/schemas/NextSteps"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Organizations"
        ],
        "operationId": "createOrganization",
        "summary": "Create organization",
        "description": "Create a new organization. The creating user is automatically added as owner.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "slug"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "slug": {
                    "type": "string",
                    "pattern": "^[a-z0-9-]+$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Organization created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Organization"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/organizations/{orgId}": {
      "patch": {
        "tags": [
          "Organizations"
        ],
        "operationId": "updateOrganization",
        "summary": "Update organization settings",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateOrganizationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Organization"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "delete": {
        "tags": ["Organizations"],
        "operationId": "deleteOrganization",
        "summary": "Delete organization",
        "description": "Hard delete with cascade. Removes the organization and all associated data (16+ tables). Requires owner role and session auth.",
        "parameters": [
          { "$ref": "#/components/parameters/orgIdPath" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["confirmSlug"],
                "properties": {
                  "confirmSlug": {
                    "type": "string",
                    "description": "Must match the organization's slug to confirm deletion"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Organization deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "deleted_org": { "type": "string", "format": "uuid" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/organizations/{orgId}/summary": {
      "get": {
        "tags": ["Organizations"],
        "operationId": "getOrganizationSummary",
        "summary": "Get organization summary",
        "description": "Full org overview: groups, agents (with belief/responsibility counts), content sources, content items in one call.",
        "parameters": [
          { "$ref": "#/components/parameters/orgIdPath" }
        ],
        "responses": {
          "200": {
            "description": "Organization summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "organization": { "$ref": "#/components/schemas/Organization" },
                    "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } },
                    "agents": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string", "format": "uuid" },
                          "name": { "type": "string" },
                          "belief_count": { "type": "integer" },
                          "responsibility_count": { "type": "integer" }
                        }
                      }
                    },
                    "content_sources": { "type": "array", "items": { "$ref": "#/components/schemas/ContentSource" } },
                    "content_items_count": { "type": "integer" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/organizations/{orgId}/api-keys": {
      "get": {
        "tags": [
          "API Keys"
        ],
        "operationId": "listApiKeys",
        "summary": "List API keys",
        "description": "List API key metadata for an organization. Never includes the key itself. Requires session auth.",
        "security": [
          {
            "sessionToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "List of API key metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ApiKeyMeta"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "API Keys"
        ],
        "operationId": "createApiKey",
        "summary": "Create API key",
        "description": "Create an org-scoped API key. The raw key is returned once and cannot be retrieved again. Requires session auth.",
        "security": [
          {
            "sessionToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "Optional label for identification"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "API key created (raw key shown once)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyCreated"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/organizations/{orgId}/api-keys/{keyId}": {
      "delete": {
        "tags": [
          "API Keys"
        ],
        "operationId": "revokeApiKey",
        "summary": "Revoke API key",
        "description": "Revoke an API key. Requires session auth.",
        "security": [
          {
            "sessionToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          },
          {
            "name": "keyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Key revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/groups": {
      "get": {
        "tags": [
          "Groups"
        ],
        "operationId": "listGroups",
        "summary": "List groups",
        "description": "List groups in an organization with agent counts. Supports pagination.",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdQuery"
          },
          {
            "$ref": "#/components/parameters/orgSlugQuery"
          },
          {
            "$ref": "#/components/parameters/limitQuery"
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of groups with agent_count",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/PaginatedResponse" },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Group"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Groups"
        ],
        "operationId": "createGroup",
        "summary": "Create group",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "orgId",
                  "name"
                ],
                "properties": {
                  "orgId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Group created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Group"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/groups/{groupId}": {
      "patch": {
        "tags": [
          "Groups"
        ],
        "operationId": "updateGroup",
        "summary": "Update group",
        "parameters": [
          {
            "name": "groupId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "displayOrder": {
                    "type": "integer"
                  },
                  "managerAgentId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Manager agent (must be from a different group)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated group",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Group"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "delete": {
        "tags": [
          "Groups"
        ],
        "operationId": "deleteGroup",
        "summary": "Delete group",
        "parameters": [
          {
            "name": "groupId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Group deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/models": {
      "get": {
        "tags": [
          "Models"
        ],
        "operationId": "listModels",
        "summary": "List models",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdQuery"
          },
          {
            "$ref": "#/components/parameters/limitQuery"
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of models",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Model"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Models"
        ],
        "operationId": "createModel",
        "summary": "Create model",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateModelRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Model created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Model"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/models/{modelId}": {
      "patch": {
        "tags": [
          "Models"
        ],
        "operationId": "updateModel",
        "summary": "Update model",
        "parameters": [
          {
            "name": "modelId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string"
                  },
                  "modelId": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "providerUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "description": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated model",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Model"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "Models"
        ],
        "operationId": "deleteModel",
        "summary": "Delete model",
        "parameters": [
          {
            "name": "modelId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Model deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/environments": {
      "get": {
        "tags": [
          "Environments"
        ],
        "operationId": "listEnvironments",
        "summary": "List environments",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdQuery"
          },
          {
            "$ref": "#/components/parameters/limitQuery"
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of environments",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Environment"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Environments"
        ],
        "operationId": "createEnvironment",
        "summary": "Create environment",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateEnvironmentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Environment created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Environment"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/environments/{environmentId}": {
      "patch": {
        "tags": [
          "Environments"
        ],
        "operationId": "updateEnvironment",
        "summary": "Update environment",
        "parameters": [
          {
            "name": "environmentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "slug": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "isDefault": {
                    "type": "boolean"
                  },
                  "displayOrder": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Environment"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "delete": {
        "tags": [
          "Environments"
        ],
        "operationId": "deleteEnvironment",
        "summary": "Delete environment",
        "parameters": [
          {
            "name": "environmentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Environment deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/environments/{environmentId}/models": {
      "get": {
        "tags": [
          "Environments"
        ],
        "operationId": "listEnvironmentModels",
        "summary": "List environment models",
        "parameters": [
          {
            "name": "environmentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Environment model assignments",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/EnvironmentModelAssignment"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Environments"
        ],
        "operationId": "addEnvironmentModel",
        "summary": "Add model to environment",
        "parameters": [
          {
            "name": "environmentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "modelId"
                ],
                "properties": {
                  "modelId": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Model added to environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnvironmentModelAssignment"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      },
      "delete": {
        "tags": [
          "Environments"
        ],
        "operationId": "removeEnvironmentModel",
        "summary": "Remove model from environment",
        "description": "Requires a JSON request body with modelId.",
        "parameters": [
          {
            "name": "environmentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "modelId"
                ],
                "properties": {
                  "modelId": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Model removed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/conversations": {
      "get": {
        "tags": [
          "Conversations"
        ],
        "operationId": "listConversations",
        "summary": "List conversations",
        "parameters": [
          {
            "name": "agentId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/limitQuery"
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of conversations",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ConversationSummary"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Conversations"
        ],
        "operationId": "createConversation",
        "summary": "Create conversation",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateConversationRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Conversation created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Conversation"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/conversations/{sessionId}": {
      "get": {
        "tags": [
          "Conversations"
        ],
        "operationId": "getConversation",
        "summary": "Get conversation with messages",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full conversation with participants and messages",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationDetail"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Conversations"
        ],
        "operationId": "updateConversation",
        "summary": "Update conversation",
        "description": "Update conversation fields. If status is set to 'completed' and org has auto_publish_conversations enabled, auto-publishes to content_items.",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "completed",
                      "archived"
                    ]
                  },
                  "ended_at": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated conversation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Conversation"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/conversations/{sessionId}/messages": {
      "post": {
        "tags": [
          "Conversations"
        ],
        "operationId": "addMessages",
        "summary": "Add messages to conversation",
        "description": "Supports single message, batch messages, or raw transcript formatting modes.",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "title": "SingleMessage",
                    "required": [
                      "participantId",
                      "content"
                    ],
                    "properties": {
                      "participantId": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "content": {
                        "type": "string"
                      },
                      "metadata": {
                        "type": "object"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "title": "BatchMessages",
                    "required": [
                      "messages"
                    ],
                    "properties": {
                      "messages": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "required": [
                            "participantId",
                            "content"
                          ],
                          "properties": {
                            "participantId": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "content": {
                              "type": "string"
                            },
                            "metadata": {
                              "type": "object"
                            }
                          }
                        }
                      }
                    }
                  },
                  {
                    "type": "object",
                    "title": "FormatTranscript",
                    "required": [
                      "format",
                      "rawText",
                      "agentName"
                    ],
                    "properties": {
                      "format": {
                        "type": "boolean",
                        "const": true
                      },
                      "rawText": {
                        "type": "string"
                      },
                      "agentName": {
                        "type": "string"
                      },
                      "otherParticipantName": {
                        "type": "string"
                      },
                      "otherParticipantType": {
                        "type": "string",
                        "default": "human"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Messages added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Message"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/conversations/{sessionId}/publish": {
      "post": {
        "tags": [
          "Conversations"
        ],
        "operationId": "publishConversation",
        "summary": "Publish conversation as content",
        "description": "Creates a content_item from the conversation. Triggers PBD pipeline in background.",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "agentId"
                ],
                "properties": {
                  "agentId": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Content item created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentItem"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "Conversations"
        ],
        "operationId": "unpublishConversation",
        "summary": "Unpublish conversation",
        "description": "Soft-deletes content_items and clears published_at on session.",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "agentId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Unpublished",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/conversations/format": {
      "post": {
        "tags": [
          "Conversations"
        ],
        "operationId": "formatTranscript",
        "summary": "Format raw transcript via LLM",
        "description": "Uses an LLM to parse raw conversation text into structured messages.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "rawText",
                  "agentName"
                ],
                "properties": {
                  "rawText": {
                    "type": "string"
                  },
                  "agentName": {
                    "type": "string"
                  },
                  "otherParticipantName": {
                    "type": "string",
                    "default": "Human"
                  },
                  "otherParticipantType": {
                    "type": "string",
                    "default": "human"
                  },
                  "title": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Formatted messages",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string"
                    },
                    "messages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "role": {
                            "type": "string"
                          },
                          "content": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/content-items": {
      "get": {
        "tags": [
          "Content"
        ],
        "operationId": "listContentItems",
        "summary": "List content items",
        "parameters": [
          {
            "name": "agentId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "sourceId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "sourceType",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of content items",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ContentItem"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/content-items/{itemId}": {
      "patch": {
        "tags": [
          "Content"
        ],
        "operationId": "updateContentItem",
        "summary": "Update content item status",
        "parameters": [
          {
            "name": "itemId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "imported",
                      "hidden"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated content item",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentItem"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/content-sources": {
      "get": {
        "tags": [
          "Content"
        ],
        "operationId": "listContentSources",
        "summary": "List content sources",
        "description": "List content sources filtered by agent, org, group, or scope. At least one of agentId or orgId is required (orgId auto-inferred from API key).",
        "parameters": [
          {
            "name": "agentId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/orgIdQuery"
          },
          {
            "name": "groupId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "agent",
                "group",
                "org"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/limitQuery"
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of content sources",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ContentSource"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Content"
        ],
        "operationId": "createContentSource",
        "summary": "Create content source",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateContentSourceRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Content source created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentSource"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/content-sources/{sourceId}": {
      "get": {
        "tags": [
          "Content"
        ],
        "operationId": "getContentSource",
        "summary": "Get content source",
        "parameters": [
          {
            "name": "sourceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Content source",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentSource"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Content"
        ],
        "operationId": "updateContentSource",
        "summary": "Update content source",
        "parameters": [
          {
            "name": "sourceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "config": {
                    "type": "object"
                  },
                  "enabled": {
                    "type": "boolean"
                  },
                  "name": {
                    "type": "string"
                  },
                  "agentId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Reassign to a different agent"
                  },
                  "groupId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Reassign to a different group"
                  },
                  "githubConnectionId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Change GitHub connection"
                  },
                  "xConnectionId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Change X connection"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated content source",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentSource"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "Content"
        ],
        "operationId": "deleteContentSource",
        "summary": "Delete content source",
        "parameters": [
          {
            "name": "sourceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Content source deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/content-sources/{sourceId}/sync": {
      "post": {
        "tags": [
          "Content"
        ],
        "operationId": "syncContentSource",
        "summary": "Sync content source",
        "description": "Fetches latest data from the source platform (GitHub commits/files, website pages, Twitter tweets, or RSS entries). Triggers PBD pipeline for all agents that received content.",
        "parameters": [
          {
            "name": "sourceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sync result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SyncResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/github/connections": {
      "get": {
        "tags": [
          "GitHub"
        ],
        "operationId": "listGitHubConnections",
        "summary": "List GitHub connections",
        "description": "List connections for an organization. Token is never exposed.",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of connections",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/GitHubConnection"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "GitHub"
        ],
        "operationId": "createGitHubConnection",
        "summary": "Create GitHub connection from PAT",
        "description": "Validates the token against GitHub API, fetches user info, encrypts token for storage.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "orgId",
                  "token"
                ],
                "properties": {
                  "orgId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "token": {
                    "type": "string",
                    "description": "GitHub Personal Access Token"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Connection created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GitHubConnection"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/github/connections/{connectionId}": {
      "get": {
        "tags": [
          "GitHub"
        ],
        "operationId": "getGitHubConnection",
        "summary": "Get GitHub connection details",
        "description": "Returns connection details with usage_count.",
        "parameters": [
          {
            "name": "connectionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Connection details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GitHubConnection"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "GitHub"
        ],
        "operationId": "deleteGitHubConnection",
        "summary": "Delete GitHub connection",
        "description": "Deletes the connection. Content sources using it fall back to public access.",
        "parameters": [
          {
            "name": "connectionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Connection deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/github/oauth/authorize": {
      "get": {
        "tags": [
          "GitHub"
        ],
        "operationId": "githubOAuthAuthorize",
        "summary": "Start GitHub OAuth flow",
        "description": "Redirects to GitHub's OAuth authorization page. Sets a nonce cookie for CSRF protection.",
        "parameters": [
          {
            "name": "orgId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "redirect",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Redirect URL after OAuth completion"
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to GitHub OAuth"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/github/oauth/callback": {
      "get": {
        "tags": [
          "GitHub"
        ],
        "operationId": "githubOAuthCallback",
        "summary": "GitHub OAuth callback",
        "description": "Handles OAuth callback. Exchanges code for token, encrypts and stores it, redirects back to the app.",
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect back to application"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/github/repos": {
      "get": {
        "tags": [
          "GitHub"
        ],
        "operationId": "listGitHubRepos",
        "summary": "List repos for a connection",
        "parameters": [
          {
            "name": "connectionId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of repositories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "full_name": {
                        "type": "string"
                      },
                      "private": {
                        "type": "boolean"
                      },
                      "html_url": {
                        "type": "string",
                        "format": "uri"
                      },
                      "description": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "default_branch": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/x-connections": {
      "get": {
        "tags": [
          "X Connections"
        ],
        "operationId": "listXConnections",
        "summary": "List X connections",
        "description": "List X/Twitter connections for an organization. Encrypted credentials are never exposed.",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "List of X connections",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/XConnection"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "X Connections"
        ],
        "operationId": "createXConnection",
        "summary": "Create X connection",
        "description": "Store X/Twitter OAuth 1.0a credentials. All secrets are encrypted with AES-256-GCM before storage.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateXConnectionRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Connection created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/XConnection"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "delete": {
        "tags": [
          "X Connections"
        ],
        "operationId": "deleteXConnection",
        "summary": "Delete X connection",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Connection deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/linkedin/import": {
      "post": {
        "tags": [
          "LinkedIn Import"
        ],
        "operationId": "importLinkedIn",
        "summary": "Import LinkedIn data export",
        "description": "Import content from a LinkedIn data export ZIP file. Parses Profile.csv, Positions.csv, Education.csv, Skills.csv, Shares.csv, and Articles/ HTML files. Creates content_items with platform 'linkedin' and source_types: linkedin_profile, linkedin_post, linkedin_article. No LinkedIn API key or OAuth needed — user uploads their own export.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "LinkedIn data export ZIP file (max 10MB)"
                  },
                  "orgId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Organization ID (or use orgSlug)"
                  },
                  "orgSlug": {
                    "type": "string",
                    "description": "Organization slug (alternative to orgId)"
                  },
                  "agentId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Agent to associate with (makes it agent-scoped)"
                  },
                  "groupId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Group to associate with (makes it group-scoped)"
                  },
                  "scope": {
                    "type": "string",
                    "description": "Defaults based on which ID is provided"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "LinkedIn data imported",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "source_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Created content source ID"
                    },
                    "profile_imported": {
                      "type": "boolean"
                    },
                    "posts_imported": {
                      "type": "integer",
                      "description": "Number of posts imported from Shares.csv"
                    },
                    "posts_skipped": {
                      "type": "integer"
                    },
                    "articles_imported": {
                      "type": "integer",
                      "description": "Number of articles imported from Articles/ folder"
                    },
                    "articles_skipped": {
                      "type": "integer"
                    },
                    "profile_data": {
                      "type": "object",
                      "properties": {
                        "firstName": {
                          "type": "string"
                        },
                        "lastName": {
                          "type": "string"
                        },
                        "headline": {
                          "type": "string"
                        },
                        "summary": {
                          "type": "string"
                        },
                        "industry": {
                          "type": "string"
                        },
                        "geoLocation": {
                          "type": "string"
                        }
                      }
                    },
                    "positions_count": {
                      "type": "integer"
                    },
                    "skills_count": {
                      "type": "integer"
                    },
                    "education_count": {
                      "type": "integer"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "description": "File exceeds 10MB limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/observations": {
      "get": {
        "tags": [
          "Observations"
        ],
        "operationId": "listObservations",
        "summary": "List observations (read-only)",
        "description": "Observations are generated exclusively by the PBD pipeline.",
        "parameters": [
          {
            "name": "agentId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "contentItemId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "signalId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100
            }
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of observations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/signals": {
      "get": {
        "tags": [
          "Signals"
        ],
        "operationId": "listSignals",
        "summary": "List signals (read-only)",
        "description": "Signals are clustered from observations by the PBD pipeline.",
        "parameters": [
          {
            "name": "agentId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "promoted",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            },
            "description": "Filter by promotion status"
          },
          {
            "name": "minNCount",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Minimum reinforcement count"
          },
          {
            "name": "predict_category",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Use Haiku to predict category for unpromoted signals. Adds predicted_type and predicted_category to response."
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of signals",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/bootstrap/scrape": {
      "post": {
        "tags": [
          "Bootstrap"
        ],
        "operationId": "bootstrapScrape",
        "summary": "Scrape repos and decompose into templates",
        "description": "Scrapes open-source repos, decomposes agent prompts into structured beliefs/responsibilities via Claude, and stores them with vector embeddings. Heavy operation.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "owner": {
                    "type": "string",
                    "description": "GitHub owner (if scraping single repo)"
                  },
                  "repo": {
                    "type": "string",
                    "description": "GitHub repo name (if scraping single repo)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Scrape results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "repos_scraped": {
                      "type": "integer"
                    },
                    "templates_created": {
                      "type": "integer"
                    },
                    "templates_updated": {
                      "type": "integer"
                    },
                    "templates_skipped": {
                      "type": "integer"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/bootstrap/recommend": {
      "post": {
        "tags": [
          "Bootstrap"
        ],
        "operationId": "bootstrapRecommend",
        "summary": "Get tailored recommendations",
        "description": "Generates tailored belief/responsibility recommendations for an agent based on their profile, using vector similarity search and Claude.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "agentId"
                ],
                "properties": {
                  "agentId": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recommendations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BootstrapRecommendations"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/bootstrap/apply": {
      "post": {
        "tags": [
          "Bootstrap"
        ],
        "operationId": "bootstrapApply",
        "summary": "Batch apply recommendations",
        "description": "Batch-creates or updates beliefs and/or responsibilities. Duplicates are upserted. Regenerates system prompt once after all upserts.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BootstrapApplyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Apply results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "beliefsCreated": {
                      "type": "integer"
                    },
                    "responsibilitiesCreated": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/pbd/process": {
      "post": {
        "tags": [
          "Utility"
        ],
        "operationId": "processPbd",
        "summary": "Trigger principle-based distillation",
        "description": "Triggers PBD pipeline for a single agent or all agents in an org. Returns jobId(s) for progress tracking. Provide either agentId or orgId/orgSlug.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agentId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Agent to process (mutually exclusive with orgId/orgSlug)"
                  },
                  "orgId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Process all agents in org"
                  },
                  "orgSlug": {
                    "type": "string",
                    "description": "Organization slug (alternative to orgId)"
                  },
                  "force": {
                    "type": "boolean",
                    "default": false,
                    "description": "Re-process already-processed content items"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Processing started. Single agent returns agentId+jobId. Org-level returns array of {agentId, jobId}.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "const": "processing"
                    },
                    "agentId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "jobId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "orgId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "jobs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "agentId": { "type": "string", "format": "uuid" },
                          "jobId": { "type": "string", "format": "uuid" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/github/tree": {
      "get": {
        "tags": [
          "Utility"
        ],
        "operationId": "getGitHubTree",
        "summary": "Browse GitHub repo folder structure",
        "parameters": [
          {
            "name": "owner",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "repo",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "branch",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "main"
            }
          },
          {
            "name": "connectionId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Optional connection ID for private repos"
          }
        ],
        "responses": {
          "200": {
            "description": "Folder structure",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "folders": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "total_files": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/cron/sync-sources": {
      "post": {
        "tags": [
          "Cron"
        ],
        "operationId": "cronSyncSources",
        "summary": "Auto-sync stale sources and trigger PBD",
        "description": "Called by the hourly cron service. Requires CRON_SECRET authentication, not Supabase auth.",
        "security": [
          {
            "cronSecret": []
          }
        ],
        "responses": {
          "200": {
            "description": "Sync completed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/organizations/{orgId}/beliefs": {
      "get": {
        "tags": [
          "Org Beliefs"
        ],
        "operationId": "listOrgBeliefs",
        "summary": "List org beliefs",
        "description": "List beliefs with optional filters.",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/BeliefCategory"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/Status"
            }
          },
          {
            "name": "starred",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "hidden",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/limitQuery"
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of beliefs",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/OrgBelief"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Org Beliefs"
        ],
        "operationId": "createOrgBelief",
        "summary": "Create org belief",
        "description": "Create a new org-level belief. Regenerates system prompts for affected agents.",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "category",
                  "statement"
                ],
                "properties": {
                  "category": {
                    "$ref": "#/components/schemas/BeliefCategory"
                  },
                  "statement": {
                    "type": "string"
                  },
                  "nCount": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Belief created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgBelief"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/organizations/{orgId}/beliefs/{beliefId}": {
      "patch": {
        "tags": [
          "Org Beliefs"
        ],
        "operationId": "updateOrgBelief",
        "summary": "Update org belief",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          },
          {
            "$ref": "#/components/parameters/beliefIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "statement": {
                    "type": "string"
                  },
                  "category": {
                    "$ref": "#/components/schemas/BeliefCategory"
                  },
                  "displayOrder": {
                    "type": "integer"
                  },
                  "status": {
                    "$ref": "#/components/schemas/Status"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated belief",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgBelief"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Org Beliefs"
        ],
        "operationId": "deleteOrgBelief",
        "summary": "Delete org belief",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          },
          {
            "$ref": "#/components/parameters/beliefIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Belief deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/organizations/{orgId}/beliefs/{beliefId}/star": {
      "post": {
        "tags": [
          "Org Beliefs"
        ],
        "operationId": "toggleOrgBeliefStar",
        "summary": "Toggle org belief starred",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          },
          {
            "$ref": "#/components/parameters/beliefIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Belief with toggled starred value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgBelief"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/organizations/{orgId}/beliefs/{beliefId}/hide": {
      "post": {
        "tags": [
          "Org Beliefs"
        ],
        "operationId": "toggleOrgBeliefHide",
        "summary": "Toggle org belief hidden",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          },
          {
            "$ref": "#/components/parameters/beliefIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Belief with toggled hidden value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgBelief"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/organizations/{orgId}/responsibilities": {
      "get": {
        "tags": [
          "Org Responsibilities"
        ],
        "operationId": "listOrgResponsibilities",
        "summary": "List org responsibilities",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ResponsibilityCategory"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/Status"
            }
          },
          {
            "name": "starred",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "hidden",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/limitQuery"
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of responsibilities",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/OrgResponsibility"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Org Responsibilities"
        ],
        "operationId": "createOrgResponsibility",
        "summary": "Create org responsibility",
        "description": "Create a new org-level responsibility. Regenerates system prompts for affected agents.",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "category",
                  "statement"
                ],
                "properties": {
                  "category": {
                    "$ref": "#/components/schemas/ResponsibilityCategory"
                  },
                  "statement": {
                    "type": "string"
                  },
                  "nCount": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Responsibility created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgResponsibility"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/organizations/{orgId}/responsibilities/{responsibilityId}": {
      "patch": {
        "tags": [
          "Org Responsibilities"
        ],
        "operationId": "updateOrgResponsibility",
        "summary": "Update org responsibility",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          },
          {
            "$ref": "#/components/parameters/responsibilityIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "statement": {
                    "type": "string"
                  },
                  "category": {
                    "$ref": "#/components/schemas/ResponsibilityCategory"
                  },
                  "displayOrder": {
                    "type": "integer"
                  },
                  "status": {
                    "$ref": "#/components/schemas/Status"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated responsibility",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgResponsibility"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Org Responsibilities"
        ],
        "operationId": "deleteOrgResponsibility",
        "summary": "Delete org responsibility",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          },
          {
            "$ref": "#/components/parameters/responsibilityIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Responsibility deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/organizations/{orgId}/responsibilities/{responsibilityId}/star": {
      "post": {
        "tags": [
          "Org Responsibilities"
        ],
        "operationId": "toggleOrgResponsibilityStar",
        "summary": "Toggle org responsibility starred",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          },
          {
            "$ref": "#/components/parameters/responsibilityIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Responsibility with toggled starred value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgResponsibility"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/organizations/{orgId}/responsibilities/{responsibilityId}/hide": {
      "post": {
        "tags": [
          "Org Responsibilities"
        ],
        "operationId": "toggleOrgResponsibilityHide",
        "summary": "Toggle org responsibility hidden",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          },
          {
            "$ref": "#/components/parameters/responsibilityIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Responsibility with toggled hidden value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgResponsibility"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/groups/{groupId}/beliefs": {
      "get": {
        "tags": [
          "Group Beliefs"
        ],
        "operationId": "listGroupBeliefs",
        "summary": "List group beliefs",
        "description": "List beliefs with optional filters.",
        "parameters": [
          {
            "$ref": "#/components/parameters/groupIdPath"
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/BeliefCategory"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/Status"
            }
          },
          {
            "name": "starred",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "hidden",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/limitQuery"
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of beliefs",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/GroupBelief"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Group Beliefs"
        ],
        "operationId": "createGroupBelief",
        "summary": "Create group belief",
        "description": "Create a new group-level belief. Regenerates system prompts for affected agents.",
        "parameters": [
          {
            "$ref": "#/components/parameters/groupIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "category",
                  "statement"
                ],
                "properties": {
                  "category": {
                    "$ref": "#/components/schemas/BeliefCategory"
                  },
                  "statement": {
                    "type": "string"
                  },
                  "nCount": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Belief created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GroupBelief"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/groups/{groupId}/beliefs/{beliefId}": {
      "patch": {
        "tags": [
          "Group Beliefs"
        ],
        "operationId": "updateGroupBelief",
        "summary": "Update group belief",
        "parameters": [
          {
            "$ref": "#/components/parameters/groupIdPath"
          },
          {
            "$ref": "#/components/parameters/beliefIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "statement": {
                    "type": "string"
                  },
                  "category": {
                    "$ref": "#/components/schemas/BeliefCategory"
                  },
                  "displayOrder": {
                    "type": "integer"
                  },
                  "status": {
                    "$ref": "#/components/schemas/Status"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated belief",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GroupBelief"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Group Beliefs"
        ],
        "operationId": "deleteGroupBelief",
        "summary": "Delete group belief",
        "parameters": [
          {
            "$ref": "#/components/parameters/groupIdPath"
          },
          {
            "$ref": "#/components/parameters/beliefIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Belief deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/groups/{groupId}/beliefs/{beliefId}/star": {
      "post": {
        "tags": [
          "Group Beliefs"
        ],
        "operationId": "toggleGroupBeliefStar",
        "summary": "Toggle group belief starred",
        "parameters": [
          {
            "$ref": "#/components/parameters/groupIdPath"
          },
          {
            "$ref": "#/components/parameters/beliefIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Belief with toggled starred value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GroupBelief"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/groups/{groupId}/beliefs/{beliefId}/hide": {
      "post": {
        "tags": [
          "Group Beliefs"
        ],
        "operationId": "toggleGroupBeliefHide",
        "summary": "Toggle group belief hidden",
        "parameters": [
          {
            "$ref": "#/components/parameters/groupIdPath"
          },
          {
            "$ref": "#/components/parameters/beliefIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Belief with toggled hidden value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GroupBelief"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/groups/{groupId}/responsibilities": {
      "get": {
        "tags": [
          "Group Responsibilities"
        ],
        "operationId": "listGroupResponsibilities",
        "summary": "List group responsibilities",
        "parameters": [
          {
            "$ref": "#/components/parameters/groupIdPath"
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ResponsibilityCategory"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/Status"
            }
          },
          {
            "name": "starred",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "hidden",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/limitQuery"
          },
          {
            "$ref": "#/components/parameters/offsetQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of responsibilities",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PaginatedResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/GroupResponsibility"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Group Responsibilities"
        ],
        "operationId": "createGroupResponsibility",
        "summary": "Create group responsibility",
        "description": "Create a new group-level responsibility. Regenerates system prompts for affected agents.",
        "parameters": [
          {
            "$ref": "#/components/parameters/groupIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "category",
                  "statement"
                ],
                "properties": {
                  "category": {
                    "$ref": "#/components/schemas/ResponsibilityCategory"
                  },
                  "statement": {
                    "type": "string"
                  },
                  "nCount": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Responsibility created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GroupResponsibility"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/groups/{groupId}/responsibilities/{responsibilityId}": {
      "patch": {
        "tags": [
          "Group Responsibilities"
        ],
        "operationId": "updateGroupResponsibility",
        "summary": "Update group responsibility",
        "parameters": [
          {
            "$ref": "#/components/parameters/groupIdPath"
          },
          {
            "$ref": "#/components/parameters/responsibilityIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "statement": {
                    "type": "string"
                  },
                  "category": {
                    "$ref": "#/components/schemas/ResponsibilityCategory"
                  },
                  "displayOrder": {
                    "type": "integer"
                  },
                  "status": {
                    "$ref": "#/components/schemas/Status"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated responsibility",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GroupResponsibility"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Group Responsibilities"
        ],
        "operationId": "deleteGroupResponsibility",
        "summary": "Delete group responsibility",
        "parameters": [
          {
            "$ref": "#/components/parameters/groupIdPath"
          },
          {
            "$ref": "#/components/parameters/responsibilityIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Responsibility deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/groups/{groupId}/responsibilities/{responsibilityId}/star": {
      "post": {
        "tags": [
          "Group Responsibilities"
        ],
        "operationId": "toggleGroupResponsibilityStar",
        "summary": "Toggle group responsibility starred",
        "parameters": [
          {
            "$ref": "#/components/parameters/groupIdPath"
          },
          {
            "$ref": "#/components/parameters/responsibilityIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Responsibility with toggled starred value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GroupResponsibility"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/groups/{groupId}/responsibilities/{responsibilityId}/hide": {
      "post": {
        "tags": [
          "Group Responsibilities"
        ],
        "operationId": "toggleGroupResponsibilityHide",
        "summary": "Toggle group responsibility hidden",
        "parameters": [
          {
            "$ref": "#/components/parameters/groupIdPath"
          },
          {
            "$ref": "#/components/parameters/responsibilityIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Responsibility with toggled hidden value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GroupResponsibility"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/agents/{agentId}/overrides": {
      "get": {
        "tags": [
          "Agent Overrides"
        ],
        "operationId": "listAgentOverrides",
        "summary": "List agent overrides",
        "description": "List all overrides for inherited beliefs/responsibilities.",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "List of overrides",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AgentBeliefOverride"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Agent Overrides"
        ],
        "operationId": "createAgentOverride",
        "summary": "Create agent override",
        "description": "Override (hide) an inherited belief or responsibility for this agent.",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sourceType",
                  "sourceId"
                ],
                "properties": {
                  "sourceType": {
                    "type": "string",
                    "enum": [
                      "org_belief",
                      "group_belief",
                      "org_responsibility",
                      "group_responsibility"
                    ]
                  },
                  "sourceId": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Override created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentBeliefOverride"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/agents/{agentId}/overrides/{overrideId}": {
      "delete": {
        "tags": [
          "Agent Overrides"
        ],
        "operationId": "deleteAgentOverride",
        "summary": "Delete agent override",
        "description": "Remove an override, restoring the inherited belief/responsibility.",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          },
          {
            "$ref": "#/components/parameters/overrideIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Override deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/agents/{agentId}/resolved-identity": {
      "get": {
        "tags": [
          "Agent Overrides"
        ],
        "operationId": "getResolvedIdentity",
        "summary": "Get resolved agent identity",
        "description": "Returns the merged identity with beliefs and responsibilities from all three layers (org, group, agent) with source attribution and override status.",
        "parameters": [
          {
            "$ref": "#/components/parameters/agentIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Resolved identity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResolvedIdentity"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/jobs": {
      "get": {
        "tags": [
          "Background Jobs"
        ],
        "operationId": "listJobs",
        "summary": "List background jobs",
        "description": "List background jobs with optional filters by agent, org, or status.",
        "parameters": [
          {
            "name": "agentId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by agent ID"
          },
          {
            "name": "orgId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by organization ID"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "queued",
                "running",
                "completed",
                "failed"
              ]
            },
            "description": "Filter by job status"
          }
        ],
        "responses": {
          "200": {
            "description": "List of jobs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Job"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/jobs/{jobId}": {
      "get": {
        "tags": [
          "Background Jobs"
        ],
        "operationId": "getJob",
        "summary": "Get job status",
        "description": "Get the status and progress of a single background job.",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Job ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Job details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/organizations/{orgId}/consensus": {
      "post": {
        "tags": [
          "Consensus"
        ],
        "operationId": "detectOrgConsensus",
        "summary": "Detect consensus beliefs/responsibilities across agents",
        "description": "Analyzes beliefs and responsibilities across all agents in the organization to detect consensus items shared by multiple agents, and promotes them to org-level.",
        "parameters": [
          {
            "$ref": "#/components/parameters/orgIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Consensus detection results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsensusResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/groups/{groupId}/consensus": {
      "post": {
        "tags": [
          "Consensus"
        ],
        "operationId": "detectGroupConsensus",
        "summary": "Detect consensus beliefs/responsibilities across group agents",
        "description": "Analyzes beliefs and responsibilities across all agents in the group to detect consensus items shared by multiple agents, and promotes them to group-level.",
        "parameters": [
          {
            "$ref": "#/components/parameters/groupIdPath"
          }
        ],
        "responses": {
          "200": {
            "description": "Consensus detection results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsensusResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/beliefs/backfill-embeddings": {
      "post": {
        "tags": [
          "Beliefs"
        ],
        "operationId": "backfillBeliefEmbeddings",
        "summary": "Backfill embeddings for beliefs and responsibilities",
        "description": "Generate vector embeddings for beliefs and responsibilities that are missing them. Useful after bulk imports or migrations.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "orgId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Organization ID to scope the backfill"
                  }
                },
                "required": [
                  "orgId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Backfill results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "updated": {
                      "type": "integer",
                      "description": "Number of items that had embeddings generated"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Org-scoped API key with `ln_` prefix. Header: `Authorization: Bearer ln_<key>`"
      },
      "sessionToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Browser session cookie (internal use only — required for API key management endpoints)"
      },
      "cronSecret": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Bearer token with CRON_SECRET value for cron endpoints"
      }
    },
    "parameters": {
      "orgIdQuery": {
        "name": "orgId",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "Organization ID (or use orgSlug). Auto-inferred from API key if omitted."
      },
      "orgSlugQuery": {
        "name": "orgSlug",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Organization slug (alternative to orgId)"
      },
      "orgIdPath": {
        "name": "orgId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Organization ID (UUID) or slug"
      },
      "agentIdPath": {
        "name": "agentId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "Agent ID"
      },
      "limitQuery": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "default": 100
        },
        "description": "Maximum number of results"
      },
      "offsetQuery": {
        "name": "offset",
        "in": "query",
        "schema": {
          "type": "integer",
          "default": 0
        },
        "description": "Number of results to skip"
      },
      "groupIdPath": {
        "name": "groupId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "Group ID"
      },
      "beliefIdPath": {
        "name": "beliefId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "Belief ID"
      },
      "responsibilityIdPath": {
        "name": "responsibilityId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "Responsibility ID"
      },
      "overrideIdPath": {
        "name": "overrideId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "Override ID"
      }
    },
    "schemas": {
      "Agent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "group_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "job_title": {
            "type": [
              "string",
              "null"
            ]
          },
          "identity_markers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "min_n_count": {
            "type": "integer"
          },
          "decay_rate": {
            "type": "number"
          },
          "promotion_threshold": {
            "type": "number"
          },
          "avatar_prompt": {
            "type": [
              "string",
              "null"
            ]
          },
          "avatar_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "github_username": {
            "type": [
              "string",
              "null"
            ]
          },
          "location": {
            "type": [
              "string",
              "null"
            ]
          },
          "timezone": {
            "type": [
              "string",
              "null"
            ]
          },
          "system_prompt": {
            "type": [
              "string",
              "null"
            ]
          },
          "system_prompt_updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "dynamic_prompt_config": {
            "type": "object"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "org_id",
          "name",
          "created_at",
          "updated_at"
        ]
      },
      "AgentSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "job_title": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "group_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "avatar_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "agent_groups": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "name": {
                "type": "string"
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "org_id",
          "name"
        ]
      },
      "AgentDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Agent"
          },
          {
            "type": "object",
            "properties": {
              "agent_groups": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string"
                  }
                }
              },
              "beliefs": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Belief"
                }
              },
              "responsibilities": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Responsibility"
                }
              }
            }
          }
        ]
      },
      "CreateAgentRequest": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "orgId": {
            "type": "string",
            "format": "uuid",
            "description": "Organization ID (or use orgSlug)"
          },
          "orgSlug": {
            "type": "string",
            "description": "Organization slug (alternative to orgId)"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "groupId": {
            "type": "string",
            "format": "uuid"
          },
          "identityMarkers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "jobTitle": {
            "type": "string"
          },
          "avatarPrompt": {
            "type": "string",
            "description": "Prompt for avatar generation (triggers background generation)"
          }
        }
      },
      "UpdateAgentRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "groupId": {
            "type": "string",
            "format": "uuid"
          },
          "identityMarkers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "minNCount": {
            "type": "integer"
          },
          "decayRate": {
            "type": "number"
          },
          "jobTitle": {
            "type": "string"
          },
          "avatarPrompt": {
            "type": "string"
          },
          "location": {
            "type": "string"
          },
          "timezone": {
            "type": "string",
            "description": "IANA timezone identifier"
          },
          "githubUsername": {
            "type": "string"
          }
        }
      },
      "AgentModelAssignment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "agent_id": {
            "type": "string",
            "format": "uuid"
          },
          "environment_id": {
            "type": "string",
            "format": "uuid"
          },
          "model_id": {
            "type": "string",
            "format": "uuid"
          },
          "is_primary": {
            "type": "boolean"
          },
          "tier": {
            "type": "string",
            "nullable": true,
            "description": "Freeform tier name (e.g., planner, worker, reviewer). NULL = simple single-model."
          },
          "environments": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              }
            }
          },
          "models": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "provider": {
                "type": "string"
              },
              "model_id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          }
        }
      },
      "Belief": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "agent_id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "category": {
            "$ref": "#/components/schemas/BeliefCategory"
          },
          "statement": {
            "type": "string"
          },
          "n_count": {
            "type": "integer"
          },
          "starred": {
            "type": "boolean"
          },
          "hidden": {
            "type": "boolean"
          },
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "approved_by": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "display_order": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "agent_id",
          "org_id",
          "category",
          "statement",
          "n_count",
          "starred",
          "hidden",
          "status",
          "display_order"
        ]
      },
      "CreateBeliefRequest": {
        "type": "object",
        "required": [
          "agentId",
          "category",
          "statement"
        ],
        "properties": {
          "agentId": {
            "type": "string",
            "format": "uuid"
          },
          "category": {
            "$ref": "#/components/schemas/BeliefCategory"
          },
          "statement": {
            "type": "string"
          },
          "sourceType": {
            "type": "string",
            "description": "Source type for attribution"
          },
          "quote": {
            "type": "string",
            "description": "Source quote"
          },
          "nCount": {
            "type": "integer",
            "default": 1,
            "description": "Observation count"
          }
        }
      },
      "UpdateBeliefRequest": {
        "type": "object",
        "properties": {
          "statement": {
            "type": "string"
          },
          "category": {
            "$ref": "#/components/schemas/BeliefCategory"
          },
          "displayOrder": {
            "type": "integer"
          },
          "status": {
            "$ref": "#/components/schemas/Status"
          }
        }
      },
      "BeliefCategory": {
        "type": "string",
        "enum": [
          "axiom",
          "principle",
          "voice",
          "preference",
          "boundary"
        ]
      },
      "Responsibility": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "agent_id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "category": {
            "$ref": "#/components/schemas/ResponsibilityCategory"
          },
          "statement": {
            "type": "string"
          },
          "n_count": {
            "type": "integer"
          },
          "starred": {
            "type": "boolean"
          },
          "hidden": {
            "type": "boolean"
          },
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "approved_by": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "display_order": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "agent_id",
          "org_id",
          "category",
          "statement",
          "n_count",
          "starred",
          "hidden",
          "status",
          "display_order"
        ]
      },
      "CreateResponsibilityRequest": {
        "type": "object",
        "required": [
          "agentId",
          "category",
          "statement"
        ],
        "properties": {
          "agentId": {
            "type": "string",
            "format": "uuid"
          },
          "category": {
            "$ref": "#/components/schemas/ResponsibilityCategory"
          },
          "statement": {
            "type": "string"
          },
          "nCount": {
            "type": "integer",
            "default": 1,
            "description": "Observation count"
          }
        }
      },
      "UpdateResponsibilityRequest": {
        "type": "object",
        "properties": {
          "statement": {
            "type": "string"
          },
          "category": {
            "$ref": "#/components/schemas/ResponsibilityCategory"
          },
          "displayOrder": {
            "type": "integer"
          },
          "status": {
            "$ref": "#/components/schemas/Status"
          }
        }
      },
      "ResponsibilityCategory": {
        "type": "string",
        "enum": [
          "ownership",
          "execution",
          "collaboration",
          "deliverables",
          "monitoring"
        ]
      },
      "Status": {
        "type": "string",
        "enum": [
          "pending",
          "approved",
          "rejected"
        ]
      },
      "Organization": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "created_by": {
            "type": "string",
            "format": "uuid"
          },
          "auto_approve_beliefs": {
            "type": "boolean"
          },
          "auto_approve_responsibilities": {
            "type": "boolean"
          },
          "auto_publish_conversations": {
            "type": "boolean"
          },
          "dynamic_prompt_config": {
            "type": "object"
          },
          "auto_promote_shared_beliefs": {
            "type": "boolean"
          },
          "auto_promote_shared_responsibilities": {
            "type": "boolean"
          },
          "consensus_similarity_threshold": {
            "type": "number"
          },
          "consensus_agent_percentage": {
            "type": "number"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "name",
          "slug"
        ]
      },
      "UpdateOrganizationRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "autoApproveBeliefs": {
            "type": "boolean"
          },
          "autoApproveResponsibilities": {
            "type": "boolean"
          },
          "autoPublishConversations": {
            "type": "boolean"
          },
          "autoPromoteSharedBeliefs": {
            "type": "boolean"
          },
          "autoPromoteSharedResponsibilities": {
            "type": "boolean"
          },
          "consensusSimilarityThreshold": {
            "type": "number"
          },
          "consensusAgentPercentage": {
            "type": "number"
          }
        }
      },
      "ApiKeyMeta": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "created_by": {
            "type": "string",
            "format": "uuid"
          },
          "label": {
            "type": [
              "string",
              "null"
            ]
          },
          "key_hint": {
            "type": "string",
            "description": "Last 4 characters of the key"
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "org_id",
          "key_hint"
        ]
      },
      "ApiKeyCreated": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "label": {
            "type": [
              "string",
              "null"
            ]
          },
          "key_hint": {
            "type": "string"
          },
          "key": {
            "type": "string",
            "description": "Raw API key (shown once, prefixed with ln_)"
          },
          "warning": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "org_id",
          "key_hint",
          "key",
          "warning"
        ]
      },
      "Group": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "display_order": {
            "type": "integer"
          },
          "manager_agent_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "org_id",
          "name"
        ]
      },
      "Model": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "provider": {
            "type": "string"
          },
          "model_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "provider_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "org_id",
          "provider",
          "model_id",
          "name"
        ]
      },
      "CreateModelRequest": {
        "type": "object",
        "required": [
          "orgId",
          "provider",
          "modelId",
          "name"
        ],
        "properties": {
          "orgId": {
            "type": "string",
            "format": "uuid"
          },
          "provider": {
            "type": "string"
          },
          "modelId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "providerUrl": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "Environment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "is_default": {
            "type": "boolean"
          },
          "display_order": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "org_id",
          "name",
          "slug"
        ]
      },
      "CreateEnvironmentRequest": {
        "type": "object",
        "required": [
          "orgId",
          "name",
          "slug"
        ],
        "properties": {
          "orgId": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "isDefault": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "EnvironmentModelAssignment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "environment_id": {
            "type": "string",
            "format": "uuid"
          },
          "model_id": {
            "type": "string",
            "format": "uuid"
          },
          "models": {
            "$ref": "#/components/schemas/Model"
          }
        }
      },
      "ConversationSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "completed",
              "archived"
            ]
          },
          "started_at": {
            "type": "string",
            "format": "date-time"
          },
          "participant_count": {
            "type": "integer"
          },
          "message_count": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "org_id",
          "status"
        ]
      },
      "Conversation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "completed",
              "archived"
            ]
          },
          "started_at": {
            "type": "string",
            "format": "date-time"
          },
          "ended_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "participants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Participant"
            }
          }
        },
        "required": [
          "id",
          "org_id",
          "status"
        ]
      },
      "ConversationDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Conversation"
          },
          {
            "type": "object",
            "properties": {
              "messages": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Message"
                }
              }
            }
          }
        ]
      },
      "CreateConversationRequest": {
        "type": "object",
        "required": [
          "orgId",
          "participants"
        ],
        "properties": {
          "orgId": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "participants": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "participantType",
                "displayName"
              ],
              "properties": {
                "participantType": {
                  "type": "string",
                  "enum": [
                    "agent",
                    "human"
                  ]
                },
                "displayName": {
                  "type": "string"
                },
                "agentId": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Required if participantType is agent"
                },
                "userId": {
                  "type": "string",
                  "format": "uuid"
                },
                "role": {
                  "type": "string",
                  "default": "participant"
                }
              }
            }
          }
        }
      },
      "Participant": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "participant_type": {
            "type": "string",
            "enum": [
              "agent",
              "human"
            ]
          },
          "display_name": {
            "type": "string"
          },
          "agent_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "user_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "role": {
            "type": "string"
          }
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "session_id": {
            "type": "string",
            "format": "uuid"
          },
          "participant_id": {
            "type": "string",
            "format": "uuid"
          },
          "content": {
            "type": "string"
          },
          "sequence_number": {
            "type": "integer"
          },
          "metadata": {
            "type": "object"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ContentItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "agent_id": {
            "type": "string",
            "format": "uuid"
          },
          "group_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Group ID (set for group-scoped content)"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "scope": {
            "type": "string",
            "enum": [
              "agent",
              "group",
              "org"
            ],
            "description": "Scope level inherited from the content source"
          },
          "source_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "source_type": {
            "type": "string",
            "enum": [
              "github_commit",
              "github_file",
              "conversation",
              "website_page"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "content": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {
            "type": "object"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "agent_id",
          "org_id"
        ]
      },
      "ContentSource": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "agent_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Agent ID (set for agent-scoped sources, null for group/org scope)"
          },
          "group_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Group ID (set for group-scoped sources)"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "scope": {
            "type": "string",
            "enum": [
              "agent",
              "group",
              "org"
            ],
            "description": "Scope level: agent (single agent), group (all group members), org (all agents)"
          },
          "platform": {
            "type": "string",
            "enum": [
              "github",
              "website",
              "twitter",
              "rss"
            ]
          },
          "config": {
            "type": "object",
            "description": "Platform-specific configuration. See GitHubSourceConfig, WebsiteSourceConfig, TwitterSourceConfig, or RSSSourceConfig.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/GitHubSourceConfig"
              },
              {
                "$ref": "#/components/schemas/WebsiteSourceConfig"
              },
              {
                "$ref": "#/components/schemas/TwitterSourceConfig"
              },
              {
                "$ref": "#/components/schemas/RSSSourceConfig"
              }
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "last_synced_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "org_id",
          "platform",
          "scope"
        ]
      },
      "GitHubSourceConfig": {
        "type": "object",
        "description": "Configuration for platform: github",
        "properties": {
          "owner": {
            "type": "string"
          },
          "repo": {
            "type": "string"
          },
          "branch": {
            "type": "string",
            "default": "main"
          },
          "import_commits": {
            "type": "boolean",
            "default": true
          },
          "import_files": {
            "type": "boolean",
            "default": false
          },
          "included_folders": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "excluded_folders": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "WebsiteSourceConfig": {
        "type": "object",
        "description": "Configuration for platform: website",
        "properties": {
          "domain": {
            "type": "string",
            "description": "Root domain to crawl (e.g., example.com)"
          },
          "discovery": {
            "type": "string",
            "enum": [
              "llms_txt",
              "sitemap",
              "manual"
            ],
            "default": "llms_txt",
            "description": "How to find pages: llms_txt (reads /llms.txt), sitemap (parses /sitemap.xml), manual (explicit URL list)"
          },
          "urls": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "description": "Explicit URLs to import (required when discovery is manual)"
          },
          "url_pattern": {
            "type": "string",
            "description": "Regex to filter discovered URLs (e.g., /blog/.*)"
          },
          "max_pages": {
            "type": "integer",
            "default": 50,
            "description": "Maximum pages to import per sync"
          },
          "sync_interval_hours": {
            "type": "integer",
            "default": 24,
            "description": "Hours between auto-syncs"
          },
          "extract_mode": {
            "type": "string",
            "enum": [
              "article",
              "full",
              "markdown"
            ],
            "default": "article",
            "description": "Content extraction strategy"
          }
        },
        "required": [
          "domain"
        ]
      },
      "CreateContentSourceRequest": {
        "type": "object",
        "required": [
          "platform"
        ],
        "description": "Create a content source. Exactly one of agentId, groupId, or orgId determines the scope.",
        "properties": {
          "agentId": {
            "type": "string",
            "format": "uuid",
            "description": "Agent ID (for agent-scoped sources)"
          },
          "groupId": {
            "type": "string",
            "format": "uuid",
            "description": "Group ID (for group-scoped sources)"
          },
          "orgId": {
            "type": "string",
            "format": "uuid",
            "description": "Organization ID (for org-scoped sources)"
          },
          "platform": {
            "type": "string",
            "enum": [
              "github",
              "website",
              "twitter",
              "rss"
            ]
          },
          "config": {
            "type": "object",
            "description": "Platform-specific configuration object. For github: owner/repo/branch/import_commits/import_files. For website: domain/discovery/urls/url_pattern/max_pages/sync_interval_hours/extract_mode. For twitter: username/exclude_retweets/exclude_replies/max_pages/sync_interval_hours. For rss: feed_url/max_entries/sync_interval_hours.",
            "oneOf": [
              {
                "title": "GitHub config",
                "properties": {
                  "repoUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "Full GitHub URL (owner/repo extracted automatically)"
                  },
                  "owner": {
                    "type": "string",
                    "description": "GitHub owner (alternative to repoUrl)"
                  },
                  "repo": {
                    "type": "string",
                    "description": "GitHub repo name (alternative to repoUrl)"
                  },
                  "branch": {
                    "type": "string",
                    "default": "main"
                  },
                  "import_commits": {
                    "type": "boolean",
                    "default": true
                  },
                  "import_files": {
                    "type": "boolean",
                    "default": false
                  },
                  "included_folders": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "excluded_folders": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              },
              {
                "title": "Website config",
                "$ref": "#/components/schemas/WebsiteSourceConfig"
              },
              {
                "title": "Twitter config",
                "$ref": "#/components/schemas/TwitterSourceConfig"
              },
              {
                "title": "RSS config",
                "$ref": "#/components/schemas/RSSSourceConfig"
              }
            ]
          },
          "githubConnectionId": {
            "type": "string",
            "format": "uuid",
            "description": "GitHub connection for private repo access (github platform only)"
          },
          "xConnectionId": {
            "type": "string",
            "format": "uuid",
            "description": "X connection for tweet access (twitter platform only)"
          }
        }
      },
      "SyncResult": {
        "type": "object",
        "properties": {
          "commits_imported": {
            "type": "integer",
            "description": "New commits imported (GitHub only)"
          },
          "files_imported": {
            "type": "integer",
            "description": "New files imported (GitHub only)"
          },
          "pages_imported": {
            "type": "integer",
            "description": "New pages imported (website only)"
          },
          "pages_skipped": {
            "type": "integer",
            "description": "Pages skipped — already imported or filtered out (website only)"
          },
          "pages_blocked": {
            "type": "integer",
            "description": "Pages blocked by robots.txt or url_pattern (website only)"
          },
          "tweets_imported": {
            "type": "integer",
            "description": "New tweets imported (Twitter only)"
          },
          "rss_entries_imported": {
            "type": "integer",
            "description": "New RSS entries imported (RSS only)"
          },
          "scope": {
            "type": "string",
            "enum": [
              "agent",
              "group",
              "org"
            ],
            "description": "Source scope level"
          },
          "affected_agent_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "GitHubConnection": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "github_username": {
            "type": "string"
          },
          "github_avatar_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "auth_type": {
            "type": "string",
            "enum": [
              "oauth",
              "pat"
            ]
          },
          "usage_count": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "org_id",
          "github_username",
          "auth_type"
        ]
      },
      "RSSSourceConfig": {
        "type": "object",
        "description": "Configuration for platform: rss. Works with any RSS 2.0 or Atom feed. No connection required.",
        "properties": {
          "feed_url": {
            "type": "string",
            "format": "uri",
            "description": "RSS 2.0 or Atom feed URL (e.g., https://blog.example.com/feed)"
          },
          "max_entries": {
            "type": "integer",
            "default": 50,
            "description": "Maximum entries to import per sync"
          },
          "sync_interval_hours": {
            "type": "integer",
            "default": 24,
            "description": "Hours between auto-syncs"
          }
        },
        "required": [
          "feed_url"
        ]
      },
      "TwitterSourceConfig": {
        "type": "object",
        "description": "Configuration for platform: twitter",
        "properties": {
          "username": {
            "type": "string",
            "description": "X/Twitter username to sync tweets from"
          },
          "exclude_retweets": {
            "type": "boolean",
            "default": true,
            "description": "Exclude retweets from sync"
          },
          "exclude_replies": {
            "type": "boolean",
            "default": true,
            "description": "Exclude replies from sync"
          },
          "max_pages": {
            "type": "integer",
            "default": 3,
            "description": "Max pages to fetch (100 tweets per page)"
          },
          "sync_interval_hours": {
            "type": "integer",
            "default": 24,
            "description": "Hours between auto-syncs"
          }
        },
        "required": [
          "username"
        ]
      },
      "XConnection": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "label": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "org_id",
          "label"
        ]
      },
      "CreateXConnectionRequest": {
        "type": "object",
        "required": [
          "label",
          "xUsername",
          "xUserId",
          "apiKey",
          "apiSecret",
          "accessToken",
          "accessTokenSecret"
        ],
        "properties": {
          "orgId": {
            "type": "string",
            "format": "uuid",
            "description": "Organization ID"
          },
          "orgSlug": {
            "type": "string",
            "description": "Organization slug (alternative to orgId)"
          },
          "label": {
            "type": "string",
            "description": "Display label for the connection"
          },
          "xUsername": {
            "type": "string",
            "description": "X/Twitter username"
          },
          "xUserId": {
            "type": "string",
            "description": "X/Twitter user ID"
          },
          "apiKey": {
            "type": "string",
            "description": "X API key"
          },
          "apiSecret": {
            "type": "string",
            "description": "X API secret"
          },
          "accessToken": {
            "type": "string",
            "description": "X access token"
          },
          "accessTokenSecret": {
            "type": "string",
            "description": "X access token secret"
          }
        }
      },
      "SnapshotSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "agent_id": {
            "type": "string",
            "format": "uuid"
          },
          "label": {
            "type": [
              "string",
              "null"
            ]
          },
          "belief_count": {
            "type": "integer"
          },
          "responsibility_count": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_by": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          }
        },
        "required": [
          "id",
          "agent_id",
          "belief_count",
          "responsibility_count",
          "created_at"
        ]
      },
      "SnapshotDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SnapshotSummary"
          },
          {
            "type": "object",
            "properties": {
              "genome": {
                "type": "object",
                "properties": {
                  "beliefs": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "category": {
                          "$ref": "#/components/schemas/BeliefCategory"
                        },
                        "statement": {
                          "type": "string"
                        },
                        "starred": {
                          "type": "boolean"
                        },
                        "hidden": {
                          "type": "boolean"
                        },
                        "status": {
                          "$ref": "#/components/schemas/Status"
                        }
                      }
                    }
                  },
                  "responsibilities": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "category": {
                          "$ref": "#/components/schemas/ResponsibilityCategory"
                        },
                        "statement": {
                          "type": "string"
                        },
                        "starred": {
                          "type": "boolean"
                        },
                        "hidden": {
                          "type": "boolean"
                        },
                        "status": {
                          "$ref": "#/components/schemas/Status"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "SnapshotDiff": {
        "type": "object",
        "properties": {
          "snapshot_a": {
            "$ref": "#/components/schemas/SnapshotSummary"
          },
          "snapshot_b": {
            "$ref": "#/components/schemas/SnapshotSummary"
          },
          "diff": {
            "type": "object",
            "properties": {
              "beliefs": {
                "type": "object",
                "properties": {
                  "added": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "removed": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  }
                }
              },
              "responsibilities": {
                "type": "object",
                "properties": {
                  "added": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "removed": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ResponsibilityGap": {
        "type": "object",
        "properties": {
          "category": {
            "$ref": "#/components/schemas/ResponsibilityCategory"
          },
          "label": {
            "type": "string"
          },
          "current_count": {
            "type": "integer"
          },
          "suggestions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "statement": {
                  "type": "string"
                },
                "confidence": {
                  "type": "string",
                  "enum": [
                    "high",
                    "medium",
                    "low"
                  ]
                }
              }
            }
          }
        }
      },
      "DynamicPromptResponse": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string"
          },
          "manifest": {
            "type": "object",
            "properties": {
              "beliefs_included": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "beliefs_sampled_out": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "responsibilities_included": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "responsibilities_sampled_out": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "emphasis": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "seed": {
                "type": "number"
              }
            }
          },
          "config": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "emphasis_rate": {
                "type": "number"
              },
              "min_pool_size": {
                "type": "integer"
              },
              "category_overrides": {
                "type": "object"
              }
            }
          },
          "next_steps": {
            "$ref": "#/components/schemas/NextSteps"
          }
        }
      },
      "BootstrapRecommendations": {
        "type": "object",
        "properties": {
          "beliefs": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": {
                  "$ref": "#/components/schemas/BeliefCategory"
                },
                "statement": {
                  "type": "string"
                },
                "confidence": {
                  "type": "string",
                  "enum": [
                    "high",
                    "medium",
                    "low"
                  ]
                },
                "source": {
                  "type": "string"
                }
              }
            }
          },
          "responsibilities": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": {
                  "$ref": "#/components/schemas/ResponsibilityCategory"
                },
                "statement": {
                  "type": "string"
                },
                "confidence": {
                  "type": "string",
                  "enum": [
                    "high",
                    "medium",
                    "low"
                  ]
                },
                "source": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "BootstrapApplyRequest": {
        "type": "object",
        "required": [
          "agentId"
        ],
        "properties": {
          "agentId": {
            "type": "string",
            "format": "uuid"
          },
          "beliefs": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "category",
                "statement"
              ],
              "properties": {
                "category": {
                  "$ref": "#/components/schemas/BeliefCategory"
                },
                "statement": {
                  "type": "string"
                },
                "nCount": {
                  "type": "integer",
                  "default": 1
                }
              }
            }
          },
          "responsibilities": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "category",
                "statement"
              ],
              "properties": {
                "category": {
                  "$ref": "#/components/schemas/ResponsibilityCategory"
                },
                "statement": {
                  "type": "string"
                },
                "nCount": {
                  "type": "integer",
                  "default": 1
                }
              }
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "approved",
              "pending"
            ],
            "default": "approved"
          }
        }
      },
      "PaginatedResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {}
          },
          "count": {
            "type": "integer"
          },
          "next_steps": {
            "$ref": "#/components/schemas/NextSteps"
          }
        },
        "required": [
          "data",
          "count"
        ]
      },
      "NextSteps": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "description": {
              "type": "string"
            },
            "method": {
              "type": "string",
              "enum": [
                "GET",
                "POST",
                "PATCH",
                "DELETE"
              ]
            },
            "endpoint": {
              "type": "string"
            },
            "body": {
              "type": "object"
            }
          },
          "required": [
            "description",
            "method",
            "endpoint"
          ]
        }
      },
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": true
          }
        },
        "required": [
          "success"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "OrgBelief": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "category": {
            "$ref": "#/components/schemas/BeliefCategory"
          },
          "statement": {
            "type": "string"
          },
          "n_count": {
            "type": "integer"
          },
          "starred": {
            "type": "boolean"
          },
          "hidden": {
            "type": "boolean"
          },
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "display_order": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "org_id",
          "category",
          "statement"
        ]
      },
      "OrgResponsibility": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "category": {
            "$ref": "#/components/schemas/ResponsibilityCategory"
          },
          "statement": {
            "type": "string"
          },
          "n_count": {
            "type": "integer"
          },
          "starred": {
            "type": "boolean"
          },
          "hidden": {
            "type": "boolean"
          },
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "display_order": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "org_id",
          "category",
          "statement"
        ]
      },
      "GroupBelief": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "group_id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "category": {
            "$ref": "#/components/schemas/BeliefCategory"
          },
          "statement": {
            "type": "string"
          },
          "n_count": {
            "type": "integer"
          },
          "starred": {
            "type": "boolean"
          },
          "hidden": {
            "type": "boolean"
          },
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "display_order": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "group_id",
          "category",
          "statement"
        ]
      },
      "GroupResponsibility": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "group_id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "category": {
            "$ref": "#/components/schemas/ResponsibilityCategory"
          },
          "statement": {
            "type": "string"
          },
          "n_count": {
            "type": "integer"
          },
          "starred": {
            "type": "boolean"
          },
          "hidden": {
            "type": "boolean"
          },
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "display_order": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "group_id",
          "category",
          "statement"
        ]
      },
      "AgentBeliefOverride": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "agent_id": {
            "type": "string",
            "format": "uuid"
          },
          "source_type": {
            "type": "string",
            "enum": [
              "org_belief",
              "group_belief",
              "org_responsibility",
              "group_responsibility"
            ]
          },
          "source_id": {
            "type": "string",
            "format": "uuid"
          },
          "hidden": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "agent_id",
          "source_type",
          "source_id"
        ]
      },
      "ResolvedBelief": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "category": {
            "type": "string"
          },
          "statement": {
            "type": "string"
          },
          "n_count": {
            "type": "integer"
          },
          "starred": {
            "type": "boolean"
          },
          "hidden": {
            "type": "boolean"
          },
          "status": {
            "type": "string"
          },
          "display_order": {
            "type": "integer"
          },
          "source": {
            "type": "string",
            "enum": [
              "org",
              "group",
              "agent"
            ]
          },
          "source_id": {
            "type": "string",
            "format": "uuid"
          },
          "overridden": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "category",
          "statement",
          "source"
        ]
      },
      "ResolvedResponsibility": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "category": {
            "type": "string"
          },
          "statement": {
            "type": "string"
          },
          "n_count": {
            "type": "integer"
          },
          "starred": {
            "type": "boolean"
          },
          "hidden": {
            "type": "boolean"
          },
          "status": {
            "type": "string"
          },
          "display_order": {
            "type": "integer"
          },
          "source": {
            "type": "string",
            "enum": [
              "org",
              "group",
              "agent"
            ]
          },
          "source_id": {
            "type": "string",
            "format": "uuid"
          },
          "overridden": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "category",
          "statement",
          "source"
        ]
      },
      "ResolvedIdentity": {
        "type": "object",
        "properties": {
          "agent_id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "group_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "beliefs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResolvedBelief"
            }
          },
          "responsibilities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResolvedResponsibility"
            }
          },
          "summary": {
            "type": "object",
            "properties": {
              "total_beliefs": {
                "type": "integer"
              },
              "active_beliefs": {
                "type": "integer"
              },
              "overridden_beliefs": {
                "type": "integer"
              },
              "by_source": {
                "type": "object",
                "properties": {
                  "org": {
                    "type": "integer"
                  },
                  "group": {
                    "type": "integer"
                  },
                  "agent": {
                    "type": "integer"
                  }
                }
              },
              "total_responsibilities": {
                "type": "integer"
              },
              "active_responsibilities": {
                "type": "integer"
              },
              "overridden_responsibilities": {
                "type": "integer"
              }
            }
          }
        },
        "required": [
          "agent_id",
          "org_id",
          "beliefs",
          "responsibilities",
          "summary"
        ]
      },
      "Job": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "org_id": {
            "type": "string",
            "format": "uuid"
          },
          "agent_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "job_type": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed"
            ]
          },
          "progress_current": {
            "type": [
              "integer",
              "null"
            ]
          },
          "progress_total": {
            "type": [
              "integer",
              "null"
            ]
          },
          "result": {
            "type": [
              "object",
              "null"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "org_id",
          "job_type",
          "status",
          "created_at"
        ]
      },
      "ConsensusResult": {
        "type": "object",
        "properties": {
          "beliefs_created": {
            "type": "integer"
          },
          "beliefs_skipped": {
            "type": "integer"
          },
          "responsibilities_created": {
            "type": "integer"
          },
          "responsibilities_skipped": {
            "type": "integer"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "beliefs_created",
          "beliefs_skipped",
          "responsibilities_created",
          "responsibilities_skipped",
          "details"
        ]
      },
      "Signal": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "agent_id": {
            "type": "string",
            "format": "uuid"
          },
          "category": {
            "type": "string"
          },
          "statement": {
            "type": "string"
          },
          "n_count": {
            "type": "integer"
          },
          "promoted": {
            "type": "boolean"
          },
          "promoted_to_belief_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "promoted_to_responsibility_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "agent_id",
          "category",
          "statement",
          "n_count",
          "promoted"
        ]
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request — missing or invalid fields",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized — missing or invalid auth token",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Not found — resource doesn't exist or not accessible",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Conflict": {
        "description": "Conflict — duplicate resource",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServerError": {
        "description": "Server error — database or internal failure",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}