@x12i/memorix-client-api 0.18.0 → 0.19.0

package/openapi/openapi.json

@@ -1,480 +1,3587 @@
-{
-  "openapi": "3.0.3",
-  "info": {
-    "title": "Memorix client API",
-    "version": "0.18.0",
-    "description": "Read API for smart clients. Agents come from x-memorix-agent-ids. The org comes from x-memorix-org-id, or from an Authix bearer token when MEMORIX_AUTH=authix. x-memorix-caller names the calling app. Descriptors are the effective object-type fields for those agents. GET /api/v1/memorix/{path} forwards Memorix read routes. Agent functions are under /api/v1/agent-functions. Nexum subjects and canvas are under /api/v1/nexum. Scoper 3.0.0 is hosted at /api/v1/scoper. MCP is /api/v1/mcp/nexum, /api/v1/mcp/scoper, and /api/v1/mcp/mgc. Aligned with memorix-service 3.17.0 and memorix-skills 0.6.1."
-  },
-  "paths": {
-    "/health": {
-      "get": {
-        "operationId": "health",
-        "summary": "Liveness",
-        "responses": { "200": { "description": "Process is up" } }
-      }
-    },
-    "/api/v1/catalog": {
-      "get": {
-        "operationId": "catalog",
-        "summary": "Object types, content types, and field descriptors for the agent ids",
-        "description": "Each content type has derived true or false. derived true is a processing result stored on the subject. Source content is false. Metadata derived on the content type wins; otherwise the platform result types are used. A field may include mixed and shapes. shapes name a grammar and resolvesTo (objectType, contentTypes, recordId). recordId is value, paired-<sourceProperty>, or a template containing {value}. When every value shape names one object type, refersTo is that object type. A content type may also carry presentation (label, order, tab always|whenPresent|hidden, values[] with value, label, order, origin) and origin (producer model|code|mixed, use always|conditional, record). Both are optional, display metadata only, and absent when the pack has not stamped them. An object type may include functions (id, question, page, composes, pageStory, reads, optional template and kind spine|threads). template is the story template id, the same string as data.template and as presentation.values[].value on content type story. A malformed function is dropped.",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "Catalog" } }
-      }
-    },
-    "/api/v1/object-types/{objectType}": {
-      "get": {
-        "operationId": "objectType",
-        "summary": "One object type and its content-type descriptors",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "$ref": "#/components/parameters/ObjectType" }
-        ],
-        "responses": { "200": { "description": "Object type" }, "404": { "description": "Unknown object type" } }
-      }
-    },
-    "/api/v1/object-types/{objectType}/content-types": {
-      "get": {
-        "operationId": "contentTypes",
-        "summary": "Content types allowed on an object type, with descriptors and the leading content type",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "$ref": "#/components/parameters/ObjectType" }
-        ],
-        "responses": { "200": { "description": "Content types" } }
-      }
-    },
-    "/api/v1/object-types/{objectType}/content-types/{contentType}": {
-      "get": {
-        "operationId": "contentType",
-        "summary": "Descriptors for one content type",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "$ref": "#/components/parameters/ObjectType" },
-          { "$ref": "#/components/parameters/ContentType" }
-        ],
-        "responses": { "200": { "description": "Content type" }, "404": { "description": "Unknown content type" } }
-      }
-    },
-    "/api/v1/object-types/{objectType}/records": {
-      "get": {
-        "operationId": "listRecords",
-        "summary": "Paginated subjects, driven by a leading content type",
-        "description": "Filter, sort, and cursor apply to the leading content type. Sibling content types are attached on each row. leadingContentType defaults to the content type marked leading in metadata, or the first content type that is not relationships. contentTypes defaults to every content type on the object type except relationships. representation is json, markdown, or both (default both). pageInfo.nextCursor is the Memorix cursor. Fields with refersTo are record ids; json and rendered markdown replace them with the records they point at.",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "$ref": "#/components/parameters/ObjectType" },
-          { "name": "leadingContentType", "in": "query", "schema": { "type": "string" } },
-          { "name": "contentTypes", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated content type ids" },
-          { "name": "representation", "in": "query", "schema": { "type": "string", "enum": ["json", "markdown", "both"] } },
-          { "name": "filter", "in": "query", "schema": { "type": "string" }, "description": "JSON SafeFilter" },
-          { "name": "sort", "in": "query", "schema": { "type": "string" }, "description": "JSON sort" },
-          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } },
-          { "name": "cursor", "in": "query", "schema": { "type": "string" } }
-        ],
-        "responses": { "200": { "description": "Page of subjects" } }
-      }
-    },
-    "/api/v1/records/{recordId}": {
-      "get": {
-        "operationId": "getRecord",
-        "summary": "One subject with all stored content types, or a named subset",
-        "description": "recordId may contain slashes; send them as extra path segments. Omit contentTypes to load every content type registered on the subject. representation is json, markdown, or both (default both). Each instance includes descriptor.fields, descriptorCoverage (complete, partial, none), and undeclaredPaths. Markdown stored with source ai or content is returned as stored. Otherwise it is rendered from .data with source rendered. Fields with refersTo are record ids; json and rendered markdown replace them with { recordId, objectType, contentType, data }. A data.<key> field is expanded at every key of that name. Unmatched ids stay strings. Prose is not parsed back into fields.",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string" } },
-          { "name": "contentTypes", "in": "query", "schema": { "type": "string" } },
-          { "name": "representation", "in": "query", "schema": { "type": "string", "enum": ["json", "markdown", "both"] } },
-          { "name": "objectType", "in": "query", "schema": { "type": "string" }, "description": "When set, must match the directory" }
-        ],
-        "responses": { "200": { "description": "Subject" }, "404": { "description": "Subject is not reserved" } }
-      }
-    },
-    "/api/v1/processed-subjects": {
-      "get": {
-        "operationId": "processedSubjects",
-        "summary": "Distinct subjects that have a derived content row on that same record",
-        "description": "rule.id caller-or-preserved opens every catalog content type except relationships. A subject counts when a row on that record has datasource basis caller or preserved. Declared and backfill rows do not count. The process keeps the answer for the org and agent ids. checking stays true until every included collection is read with no nextCursor. A later read returns that answer. continue=true keeps those subjects and reads empty collections again. A new rule.id drops the kept answer. count is the number of distinct subjects, not the page size. pageInfo.nextCursor is omitted on the last page. A working/ record id is not a subject. An unregistered content type is skipped.",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "name": "objectType", "in": "query", "schema": { "type": "string" }, "description": "Only subjects of this object type. Absent means every object type in the catalog." },
-          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } },
-          { "name": "cursor", "in": "query", "schema": { "type": "string" } },
-          { "name": "continue", "in": "query", "schema": { "type": "boolean" }, "description": "Keep the saved subjects and read collections again, including ones kept as empty." }
-        ],
-        "responses": {
-          "200": { "description": "Kept subjects. saved is true once a pass has finished. checking is true while a pass is still reading." },
-          "404": { "description": "Unknown object type" }
-        }
-      },
-      "delete": {
-        "operationId": "deleteProcessedSubjects",
-        "summary": "Drop the kept processed-subject answer for this org and these agent ids",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "The kept answer is gone. The next GET reads again." } }
-      }
-    },
-    "/api/v1/refs/resolve": {
-      "post": {
-        "operationId": "resolveRefs",
-        "summary": "Resolve ref strings from the shapes declared on catalog fields",
-        "description": "Body is { values: string[] }, at most 200. Each string is classified by the first shape grammar that matches the whole value. value loads that reserved record. paired-<sourceProperty> attaches to the sibling subject that publishes matchProperty, or looks up data.<matchProperty>. A template attaches to a subject in the batch that publishes sourceProperty, its plural Ids field, or displayName, title, or name. The template record is loaded when that object type is in the catalog. A lookup runs only when the batch resolved no record-id subjects, on the object types named by sibling value shapes, or across the catalog when the template shape has none. Strings that do not resolve are returned in unresolved. getRecord of a non-reserved id stays 404.",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "required": ["values"],
-                "properties": {
-                  "values": { "type": "array", "maxItems": 200, "items": { "type": "string" } }
-                }
-              }
-            }
-          }
-        },
-        "responses": {
-          "200": { "description": "subjects in first-seen order, plus unresolved strings in input order" },
-          "400": { "description": "values is not an array of strings, or it exceeds 200" }
-        }
-      }
-    },
-    "/api/v1/records/{recordId}/content-types": {
-      "get": {
-        "operationId": "recordContentTypes",
-        "summary": "Content types stored on one record, joined with descriptors",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string" } }
-        ],
-        "responses": { "200": { "description": "Stored content types" }, "404": { "description": "Subject is not reserved" } }
-      }
-    },
-    "/api/v1/memorix/{path}": {
-      "get": {
-        "operationId": "memorixGet",
-        "summary": "Forward a Memorix GET under /api",
-        "description": "path is the remainder of the Memorix path, including extra segments (data/content, memory/sources, pipelines/runs/{runId}, analytics/indexes, metadata/effective, connectors, jobs/v1/work, hooks/v1/subscriptions, data-journey/journeys, relationships/query). Query strings are forwarded. Relationship links and restricted-store break-glass content are refused. data/content: when the content type has a discriminator in the catalog, recordId plus discriminatorValue (or a filter eq clause on the discriminator path) returns that instance in the single-record shape, read from a recordId list on that content type; no match is 404 READ_NOT_FOUND naming the stored values. Without recordId, discriminatorValue is added to filter as an eq clause. recordId plus an eq filter on data.template returns the newest revision of that template, including when the content type has no discriminator. count=true is forwarded unchanged. metadata/effective and metadata/raw are forwarded unchanged, including objectTypes[].functions.",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } }
-        ],
-        "responses": {
-          "200": { "description": "Memorix response" },
-          "403": { "description": "Path is not a fetch route" }
-        }
-      }
-    },
-    "/api/v1/data/story": {
-      "get": {
-        "operationId": "readStory",
-        "summary": "AI-first story for one subject and template",
-        "description": "variant defaults to auto. auto serves a usable story-ai row, otherwise the code story. ai and code read only that content type. A usable AI row is active, has data.input, and _metadata.aiExecution.status outside CODE_ONLY, SKIPPED, FAILED, and DEFERRED. 200 matches a content read (scope, addressing, record, currentRevision) and adds story (template, served ai|code, fallbackReason AI_MISSING|AI_UNUSABLE when auto served code, ai, code). ai.stale is true when ai.basedOnRevision is behind code.revision; a stale AI row is still served. ai or code is null when that content type is not declared. 404 STORY_NOT_FOUND includes the same story block. An unknown object type or a template that is not on story presentation.values is answered as GET data/content.",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": {
-          "200": { "description": "Served story" },
-          "404": { "description": "STORY_NOT_FOUND, or the content read for an undeclared template" }
-        }
-      }
-    },
-    "/api/v1/data/stories": {
-      "get": {
-        "operationId": "readStories",
-        "summary": "One AI-first story per template",
-        "description": "One readStory result per value in story presentation.values, in that order. Each item is template, label, story, and record or null.",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "Stories for the subject" } }
-      }
-    },
-    "/api/v1/data/compose": {
-      "post": {
-        "operationId": "compose",
-        "summary": "Read compose of one subject",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "Composition" } }
-      }
-    },
-    "/api/v1/data/compose/data": {
-      "post": {
-        "operationId": "composeData",
-        "summary": "Read compose projected to content-type .data",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "Data projection" } }
-      }
-    },
-    "/api/v1/data/compose/data/list": {
-      "post": {
-        "operationId": "composeDataList",
-        "summary": "Read a page of subjects as content-type .data",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "Page" } }
-      }
-    },
-    "/api/v1/data/lists": {
-      "post": {
-        "operationId": "runList",
-        "summary": "Run a declared list or an abstract property page",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "List page" } }
-      }
-    },
-    "/api/v1/data/items": {
-      "post": {
-        "operationId": "getItem",
-        "summary": "Read one item view",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "Item" } }
-      }
-    },
-    "/api/v1/nexum/status": {
-      "get": {
-        "operationId": "nexumStatus",
-        "summary": "Nexum canvas health and the gateway MCP URL",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "Canvas status. mcpUrl points at this API." } }
-      }
-    },
-    "/api/v1/nexum/snapshots": {
-      "get": {
-        "operationId": "nexumListSnapshots",
-        "summary": "List content/snapshots subjects",
-        "description": "Same read as nexum_list_snapshots. knowledgeGraphOnly keeps data.kind=knowledge-graph. limit is 1–200, default 50.",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "name": "limit", "in": "query", "schema": { "type": "integer" } },
-          { "name": "cursor", "in": "query", "schema": { "type": "string" } },
-          { "name": "knowledgeGraphOnly", "in": "query", "schema": { "type": "boolean" } }
-        ],
-        "responses": { "200": { "description": "Snapshot page" } }
-      }
-    },
-    "/api/v1/nexum/snapshots/{recordId}": {
-      "get": {
-        "operationId": "nexumGetSnapshot",
-        "summary": "One content/snapshots subject",
-        "description": "recordId may contain slashes as extra path segments. A suffix /connected is nexumGetConnectedContent.",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string" } }
-        ],
-        "responses": { "200": { "description": "Snapshot" }, "404": { "description": "Snapshot is not stored" } }
-      }
-    },
-    "/api/v1/nexum/entities": {
-      "get": {
-        "operationId": "nexumListEntities",
-        "summary": "List or search Nexum canvas entities",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "name": "graphId", "in": "query", "schema": { "type": "string" } },
-          { "name": "q", "in": "query", "schema": { "type": "string" } },
-          { "name": "limit", "in": "query", "schema": { "type": "string" } }
-        ],
-        "responses": {
-          "200": { "description": "Canvas entities" },
-          "502": { "description": "NEXUM_UPSTREAM_UNREACHABLE: the Memorix host cannot reach Nexum explore REST" }
-        }
-      }
-    },
-    "/api/v1/nexum/entities/{entityId}": {
-      "get": {
-        "operationId": "nexumGetEntity",
-        "summary": "One Nexum canvas entity",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "name": "entityId", "in": "path", "required": true, "schema": { "type": "string" } },
-          { "name": "graphId", "in": "query", "schema": { "type": "string" } }
-        ],
-        "responses": {
-          "200": { "description": "Canvas entity" },
-          "502": { "description": "NEXUM_UPSTREAM_UNREACHABLE: the Memorix host cannot reach Nexum explore REST" }
-        }
-      }
-    },
-    "/api/v1/nexum/query": {
-      "post": {
-        "operationId": "nexumQuery",
-        "summary": "Neighbor query on the Nexum canvas",
-        "description": "Body is { nodeId, graphId?, depth? } or { seeds, depth? }. Same read as nexum_query.",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": {
-          "200": { "description": "Neighbors" },
-          "502": { "description": "NEXUM_UPSTREAM_UNREACHABLE: the Memorix host cannot reach Nexum explore REST" }
-        }
-      }
-    },
-    "/api/v1/mcp": {
-      "get": {
-        "operationId": "listMcp",
-        "summary": "MCP servers this API can call",
-        "description": "memorix-nexum and memorix-scoper are always listed. memorix-mgc is listed when its URL is configured or discovered from Memorix connectors.",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "MCP servers" } }
-      }
-    },
-    "/api/v1/mcp/nexum": {
-      "get": {
-        "operationId": "nexumMcpAdvertise",
-        "summary": "Advertise memorix-nexum",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "Advertise document. mcpUrl is this API." } }
-      },
-      "post": {
-        "operationId": "nexumMcpCall",
-        "summary": "JSON-RPC for memorix-nexum",
-        "description": "Methods: initialize, ping, tools/list, tools/call, notifications. Tools: nexum_list_snapshots, nexum_get_snapshot, nexum_get_connected_content, nexum_knowledge_status, nexum_list_entities, nexum_get_entity, nexum_query.",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "JSON-RPC result" } }
-      }
-    },
-    "/api/v1/skills": {
-      "get": {
-        "operationId": "skillsInfo",
-        "summary": "Which process answers agent functions",
-        "description": "mode is embedded or external. source is this process or skill-api. baseUrl is present only when mode is external. The choice is fixed for the process lifetime.",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "Skills backend" } }
-      }
-    },
-    "/api/v1/agent-functions/agents/{agentId}/functions": {
-      "get": {
-        "operationId": "listAgentFunctions",
-        "summary": "List functions for one agent",
-        "description": "agentId must be one of x-memorix-agent-ids. Each item has origin agent or database. Embedded mode reads the pack catalog. External mode proxies skill-api.",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } }
-        ],
-        "responses": { "200": { "description": "Function catalog" }, "403": { "description": "FORBIDDEN" } }
-      }
-    },
-    "/api/v1/agent-functions/agents/{agentId}/functions/{functionId}/run": {
-      "post": {
-        "operationId": "runAgentFunction",
-        "summary": "Run one function for a stored subject",
-        "description": "Body is objectType and recordId. Subject rows are read through @x12i/memorix-client when this process hosts the function. A storyInput result is written as content type story.",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } },
-          { "name": "functionId", "in": "path", "required": true, "schema": { "type": "string" } }
-        ],
-        "responses": {
-          "200": { "description": "FunctionResult with structured and text" },
-          "404": { "description": "NOT_FOUND" },
-          "502": { "description": "MEMORIX_UNREACHABLE or MEMORIX_READ_FAILED" }
-        }
-      }
-    },
-    "/api/v1/agent-functions/agents/{agentId}/functions/{functionId}": {
-      "put": {
-        "operationId": "saveAgentFunction",
-        "summary": "Save a Python function override",
-        "description": "Body is source, and optional question, page, and objectTypes. source must define generate_text. Without ASSISTANT_MONGO_URI or MONGO_URI the embedded host returns 503 PERSISTENCE.",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } },
-          { "name": "functionId", "in": "path", "required": true, "schema": { "type": "string" } }
-        ],
-        "responses": { "200": { "description": "Saved override" }, "503": { "description": "PERSISTENCE" } }
-      },
-      "delete": {
-        "operationId": "removeAgentFunction",
-        "summary": "Delete a saved function override",
-        "parameters": [
-          { "$ref": "#/components/parameters/ScopeHeaders" },
-          { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" } },
-          { "name": "functionId", "in": "path", "required": true, "schema": { "type": "string" } }
-        ],
-        "responses": { "200": { "description": "origin agent or removed" }, "503": { "description": "PERSISTENCE" } }
-      }
-    },
-    "/api/v1/scoper": {
-      "get": {
-        "operationId": "scoperInfo",
-        "summary": "Hosted Scoper release",
-        "description": "Reports @x12i/memorix-scoper 3.0.0, the SDK 2.2.0, whether saved functions are attached, mode embedded or external, and the aligned memorix-service 3.17.0, memorix-skills 0.6.1, memorix-client 3.17.0, and ai-dispatcher 3.2.0. Subject reads use @x12i/memorix-client.",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "Scoper host" } }
-      }
-    },
-    "/api/v1/scoper/scope": {
-      "post": {
-        "operationId": "scoperScope",
-        "summary": "Run a scope",
-        "description": "Body is a ScopeRequest: profileId, question, and optional focus, budgets, options, hints. Org, agents, and caller come from the call headers. The same fields in the body are ignored. Saved query and scope functions run when SCOPER_FUNCTIONS_DIR is set; otherwise the reasoner answers.",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": {
-          "200": { "description": "Evidence bundle" },
-          "400": { "description": "INVALID_REQUEST" }
-        }
-      }
-    },
-    "/api/v1/scoper/subject-data": {
-      "post": {
-        "operationId": "scoperSubjectData",
-        "summary": "Read one subject's content through Scoper",
-        "description": "Body is recordId, objectType, and contentType. Optional alsoContentTypes, sourceContentTypes, include, properties, exclude, and useMarkdown. Scope headers select the org and agents.",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": {
-          "200": { "description": "Subject data" },
-          "400": { "description": "INVALID_REQUEST" },
-          "404": { "description": "READ_NOT_FOUND" }
-        }
-      }
-    },
-    "/api/v1/mcp/scoper": {
-      "get": {
-        "operationId": "scoperMcpAdvertise",
-        "summary": "Advertise memorix-scoper",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "Advertise document. mcpUrl is this API." } }
-      },
-      "post": {
-        "operationId": "scoperMcpCall",
-        "summary": "JSON-RPC for memorix-scoper",
-        "description": "Methods: initialize, ping, tools/list, tools/call, notifications. Tools: catalog, subjects_list, subjects_query, subject_data, scope.",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "JSON-RPC result" } }
-      }
-    },
-    "/api/v1/mcp/mgc": {
-      "get": {
-        "operationId": "mgcMcpAdvertise",
-        "summary": "Advertise memorix-mgc",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "MGC advertise" }, "404": { "description": "MGC URL is not configured" } }
-      },
-      "post": {
-        "operationId": "mgcMcpCall",
-        "summary": "JSON-RPC for the MGC connector MCP",
-        "description": "Forwards to the MGC source host /mcp. Stable fetch tools include mgc_list_connectors, mgc_describe_connector, and mgc_fetch.",
-        "parameters": [{ "$ref": "#/components/parameters/ScopeHeaders" }],
-        "responses": { "200": { "description": "JSON-RPC result" }, "404": { "description": "MGC URL is not configured" } }
-      }
-    }
-  },
-  "components": {
-    "parameters": {
-      "ScopeHeaders": {
-        "name": "scope",
-        "in": "header",
-        "required": true,
-        "description": "Send x-memorix-org-id, x-memorix-agent-ids (comma-separated), and x-memorix-caller on every /api/v1 call.",
-        "schema": { "type": "string" }
-      },
-      "ObjectType": {
-        "name": "objectType",
-        "in": "path",
-        "required": true,
-        "schema": { "type": "string" }
-      },
-      "ContentType": {
-        "name": "contentType",
-        "in": "path",
-        "required": true,
-        "schema": { "type": "string" }
-      }
-    }
-  }
-}
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Memorix client API",
+    "version": "0.19.0",
+    "description": "Read API for smart clients and the visualizer contract (docs/visualizer-api.md, contract visualizer, revision 2026-10-24). Agents come from x-memorix-agent-ids; each must be deployed for the org, and * selects the org's deployed agents. The org comes from x-memorix-org-id, or from an Authix bearer token when MEMORIX_AUTH=authix. x-memorix-caller names the calling app. x-request-id is echoed and appears as error.requestId. Errors are { error: { code, message, requestId, retryable, details?, feature?, current? } }. Descriptors are the effective object-type fields for those agents. GET /api/v1/memorix/{path} forwards Memorix read routes. Agent functions are under /api/v1/agent-functions. Nexum subjects and canvas are under /api/v1/nexum. Scoper 3.0.0 is hosted at /api/v1/scoper. MCP is /api/v1/mcp/nexum, /api/v1/mcp/scoper, and /api/v1/mcp/mgc. Aligned with memorix-service 3.19.1 and memorix-skills 0.6.1.",
+    "x-contract": "visualizer",
+    "x-contract-revision": "2026-10-24"
+  },
+  "paths": {
+    "/health": {
+      "get": {
+        "operationId": "health",
+        "summary": "Liveness",
+        "responses": {
+          "200": {
+            "description": "Process is up"
+          }
+        }
+      }
+    },
+    "/api/v1/catalog": {
+      "get": {
+        "operationId": "catalog",
+        "summary": "Object types, content types, and field descriptors for the agent ids",
+        "description": "Each content type has derived true or false. derived true is a processing result stored on the subject. Source content is false. Metadata derived on the content type wins; otherwise the platform result types are used. A field may include mixed and shapes. shapes name a grammar and resolvesTo (objectType, contentTypes, recordId). recordId is value, paired-<sourceProperty>, or a template containing {value}. When every value shape names one object type, refersTo is that object type. A content type may also carry presentation (label, order, tab always|whenPresent|hidden, values[] with value, label, order, origin) and origin (producer model|code|mixed, use always|conditional, record). Both are optional, display metadata only, and absent when the pack has not stamped them. An object type may include functions (id, question, page, composes, pageStory, reads, optional template and kind spine|threads). template is the story template id, the same string as data.template and as presentation.values[].value on content type story. A malformed function is dropped.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Catalog"
+          }
+        }
+      }
+    },
+    "/api/v1/object-types/{objectType}": {
+      "get": {
+        "operationId": "objectType",
+        "summary": "One object type and its content-type descriptors",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "$ref": "#/components/parameters/ObjectType"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Object type"
+          },
+          "404": {
+            "description": "Unknown object type"
+          }
+        }
+      }
+    },
+    "/api/v1/object-types/{objectType}/content-types": {
+      "get": {
+        "operationId": "contentTypes",
+        "summary": "Content types allowed on an object type, with descriptors and the leading content type",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "$ref": "#/components/parameters/ObjectType"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Content types"
+          }
+        }
+      }
+    },
+    "/api/v1/object-types/{objectType}/content-types/{contentType}": {
+      "get": {
+        "operationId": "contentType",
+        "summary": "Descriptors for one content type",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "$ref": "#/components/parameters/ObjectType"
+          },
+          {
+            "$ref": "#/components/parameters/ContentType"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Content type"
+          },
+          "404": {
+            "description": "Unknown content type"
+          }
+        }
+      }
+    },
+    "/api/v1/object-types/{objectType}/records": {
+      "get": {
+        "operationId": "listRecords",
+        "summary": "Paginated subjects, driven by a leading content type",
+        "description": "Pages by rows of the leading content type. Directory-only records are not listed (FR-14). total is the census directory count when a census for this agent set was read in the last 60 s.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "$ref": "#/components/parameters/ObjectType"
+          },
+          {
+            "name": "leadingContentType",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "contentTypes",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Comma-separated content type ids"
+          },
+          {
+            "name": "representation",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "json",
+                "markdown",
+                "both"
+              ]
+            }
+          },
+          {
+            "name": "filter",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "JSON SafeFilter"
+          },
+          {
+            "name": "sort",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "JSON sort"
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 200,
+              "default": 50
+            }
+          },
+          {
+            "name": "cursor",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "refs",
+            "in": "query",
+            "required": false,
+            "description": "expand (default) or status",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RecordsPage"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/records/{recordId}": {
+      "get": {
+        "operationId": "getRecord",
+        "summary": "One subject with all stored content types, or a named subset",
+        "description": "Send the record id as one segment with / encoded as %2F. A literal trailing /content-types segment is the content-types view. status is stored or directory-only.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "recordId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "contentTypes",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "representation",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "json",
+                "markdown",
+                "both"
+              ]
+            }
+          },
+          {
+            "name": "objectType",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "When set, must match the directory"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Subject"
+          },
+          "404": {
+            "description": "Subject is not reserved"
+          }
+        }
+      }
+    },
+    "/api/v1/processed-subjects": {
+      "get": {
+        "operationId": "processedSubjects",
+        "summary": "Distinct subjects that have a derived content row on that same record",
+        "description": "rule.id caller-or-preserved opens every catalog content type except relationships. A subject counts when a row on that record has datasource basis caller or preserved. Declared and backfill rows do not count. The process keeps the answer for the org and agent ids. checking stays true until every included collection is read with no nextCursor. A later read returns that answer. continue=true keeps those subjects and reads empty collections again. A new rule.id drops the kept answer. count is the number of distinct subjects, not the page size. pageInfo.nextCursor is omitted on the last page. A working/ record id is not a subject. An unregistered content type is skipped.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "objectType",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Only subjects of this object type. Absent means every object type in the catalog."
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 200,
+              "default": 50
+            }
+          },
+          {
+            "name": "cursor",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "continue",
+            "in": "query",
+            "schema": {
+              "type": "boolean"
+            },
+            "description": "Keep the saved subjects and read collections again, including ones kept as empty."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Kept subjects. saved is true once a pass has finished. checking is true while a pass is still reading."
+          },
+          "404": {
+            "description": "Unknown object type"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteProcessedSubjects",
+        "summary": "Drop the kept processed-subject answer for this org and these agent ids",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The kept answer is gone. The next GET reads again."
+          }
+        }
+      }
+    },
+    "/api/v1/refs/resolve": {
+      "post": {
+        "operationId": "resolveRefs",
+        "summary": "Resolve ref strings from the shapes declared on catalog fields",
+        "description": "Body is { values: string[] }, at most 200. Each string is classified by the first shape grammar that matches the whole value. value loads that reserved record. paired-<sourceProperty> attaches to the sibling subject that publishes matchProperty, or looks up data.<matchProperty>. A template attaches to a subject in the batch that publishes sourceProperty, its plural Ids field, or displayName, title, or name. The template record is loaded when that object type is in the catalog. A lookup runs only when the batch resolved no record-id subjects, on the object types named by sibling value shapes, or across the catalog when the template shape has none. Strings that do not resolve are returned in unresolved. getRecord of a non-reserved id stays 404.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "values"
+                ],
+                "properties": {
+                  "values": {
+                    "type": "array",
+                    "maxItems": 200,
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "subjects in first-seen order, plus unresolved strings in input order"
+          },
+          "400": {
+            "description": "values is not an array of strings, or it exceeds 200"
+          }
+        }
+      }
+    },
+    "/api/v1/records/{recordId}/content-types": {
+      "get": {
+        "operationId": "recordContentTypes",
+        "summary": "Content types stored on one record, joined with descriptors",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "recordId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Stored content types"
+          },
+          "404": {
+            "description": "Subject is not reserved"
+          }
+        }
+      }
+    },
+    "/api/v1/memorix/{path}": {
+      "get": {
+        "operationId": "memorixGet",
+        "summary": "Forward a Memorix GET under /api",
+        "description": "path is the remainder of the Memorix path, including extra segments (data/content, memory/sources, pipelines/runs/{runId}, analytics/indexes, metadata/effective, connectors, jobs/v1/work, hooks/v1/subscriptions, data-journey/journeys, relationships/query). Query strings are forwarded. Relationship links and restricted-store break-glass content are refused. data/content: when the content type has a discriminator in the catalog, recordId plus discriminatorValue (or a filter eq clause on the discriminator path) returns that instance in the single-record shape, read from a recordId list on that content type; no match is 404 READ_NOT_FOUND naming the stored values. Without recordId, discriminatorValue is added to filter as an eq clause. recordId plus an eq filter on data.template returns the newest revision of that template, including when the content type has no discriminator. count=true is forwarded unchanged. metadata/effective and metadata/raw are forwarded unchanged, including objectTypes[].functions.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "path",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Memorix response"
+          },
+          "403": {
+            "description": "Path is not a fetch route"
+          }
+        }
+      }
+    },
+    "/api/v1/data/story": {
+      "get": {
+        "operationId": "readStory",
+        "summary": "AI-first story for one subject and template",
+        "description": "variant defaults to auto. auto serves a usable story-ai row, otherwise the code story. ai and code read only that content type. A usable AI row is active, has data.input, and _metadata.aiExecution.status outside CODE_ONLY, SKIPPED, FAILED, and DEFERRED. 200 matches a content read (scope, addressing, record, currentRevision) and adds story (template, served ai|code, fallbackReason AI_MISSING|AI_UNUSABLE when auto served code, ai, code). ai.stale is true when ai.basedOnRevision is behind code.revision; a stale AI row is still served. ai or code is null when that content type is not declared. 404 STORY_NOT_FOUND includes the same story block. An unknown object type or a template that is not on story presentation.values is answered as GET data/content.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Served story"
+          },
+          "404": {
+            "description": "STORY_NOT_FOUND, or the content read for an undeclared template"
+          }
+        }
+      }
+    },
+    "/api/v1/data/stories": {
+      "get": {
+        "operationId": "readStories",
+        "summary": "One AI-first story per template",
+        "description": "One readStory result per value in story presentation.values, in that order. Each item is template, label, story, and record or null.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Stories for the subject"
+          }
+        }
+      }
+    },
+    "/api/v1/data/compose": {
+      "post": {
+        "operationId": "compose",
+        "summary": "Read compose of one subject",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Composition"
+          }
+        }
+      }
+    },
+    "/api/v1/data/compose/data": {
+      "post": {
+        "operationId": "composeData",
+        "summary": "Read compose projected to content-type .data",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Data projection"
+          }
+        }
+      }
+    },
+    "/api/v1/data/compose/data/list": {
+      "post": {
+        "operationId": "composeDataList",
+        "summary": "Read a page of subjects as content-type .data",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Page"
+          }
+        }
+      }
+    },
+    "/api/v1/data/lists": {
+      "post": {
+        "operationId": "runList",
+        "summary": "Run a declared list or an abstract property page",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List page"
+          }
+        }
+      }
+    },
+    "/api/v1/data/items": {
+      "post": {
+        "operationId": "getItem",
+        "summary": "Read one item view",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Item"
+          }
+        }
+      }
+    },
+    "/api/v1/nexum/status": {
+      "get": {
+        "operationId": "nexumStatus",
+        "summary": "Nexum canvas health and the gateway MCP URL",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Canvas status. mcpUrl points at this API."
+          }
+        }
+      }
+    },
+    "/api/v1/nexum/snapshots": {
+      "get": {
+        "operationId": "nexumListSnapshots",
+        "summary": "List content/snapshots subjects",
+        "description": "Same read as nexum_list_snapshots. knowledgeGraphOnly keeps data.kind=knowledge-graph. limit is 1–200, default 50.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "schema": {
+              "type": "integer"
+            }
+          },
+          {
+            "name": "cursor",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "knowledgeGraphOnly",
+            "in": "query",
+            "schema": {
+              "type": "boolean"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Snapshot page"
+          }
+        }
+      }
+    },
+    "/api/v1/nexum/snapshots/{recordId}": {
+      "get": {
+        "operationId": "nexumGetSnapshot",
+        "summary": "One content/snapshots subject",
+        "description": "recordId may contain slashes as extra path segments. A suffix /connected is nexumGetConnectedContent.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "recordId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Snapshot"
+          },
+          "404": {
+            "description": "Snapshot is not stored"
+          }
+        }
+      }
+    },
+    "/api/v1/nexum/entities": {
+      "get": {
+        "operationId": "nexumListEntities",
+        "summary": "List or search Nexum canvas entities",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "graphId",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "q",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Canvas entities"
+          },
+          "502": {
+            "description": "NEXUM_UPSTREAM_UNREACHABLE: the Memorix host cannot reach Nexum explore REST"
+          }
+        }
+      }
+    },
+    "/api/v1/nexum/entities/{entityId}": {
+      "get": {
+        "operationId": "nexumGetEntity",
+        "summary": "One Nexum canvas entity",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "entityId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "graphId",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Canvas entity"
+          },
+          "502": {
+            "description": "NEXUM_UPSTREAM_UNREACHABLE: the Memorix host cannot reach Nexum explore REST"
+          }
+        }
+      }
+    },
+    "/api/v1/nexum/query": {
+      "post": {
+        "operationId": "nexumQuery",
+        "summary": "Neighbor query on the Nexum canvas",
+        "description": "Body is { nodeId, graphId?, depth? } or { seeds, depth? }. Same read as nexum_query.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Neighbors"
+          },
+          "502": {
+            "description": "NEXUM_UPSTREAM_UNREACHABLE: the Memorix host cannot reach Nexum explore REST"
+          }
+        }
+      }
+    },
+    "/api/v1/mcp": {
+      "get": {
+        "operationId": "listMcp",
+        "summary": "MCP servers this API can call",
+        "description": "memorix-nexum and memorix-scoper are always listed. memorix-mgc is listed when its URL is configured or discovered from Memorix connectors.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "MCP servers"
+          }
+        }
+      }
+    },
+    "/api/v1/mcp/nexum": {
+      "get": {
+        "operationId": "nexumMcpAdvertise",
+        "summary": "Advertise memorix-nexum",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Advertise document. mcpUrl is this API."
+          }
+        }
+      },
+      "post": {
+        "operationId": "nexumMcpCall",
+        "summary": "JSON-RPC for memorix-nexum",
+        "description": "Methods: initialize, ping, tools/list, tools/call, notifications. Tools: nexum_list_snapshots, nexum_get_snapshot, nexum_get_connected_content, nexum_knowledge_status, nexum_list_entities, nexum_get_entity, nexum_query.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "JSON-RPC result"
+          }
+        }
+      }
+    },
+    "/api/v1/skills": {
+      "get": {
+        "operationId": "skillsInfo",
+        "summary": "Which process answers agent functions",
+        "description": "mode is embedded or external. source is this process or skill-api. baseUrl is present only when mode is external. The choice is fixed for the process lifetime.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Skills backend"
+          }
+        }
+      }
+    },
+    "/api/v1/agent-functions/agents/{agentId}/functions": {
+      "get": {
+        "operationId": "listAgentFunctions",
+        "summary": "List functions for one agent",
+        "description": "agentId must be one of x-memorix-agent-ids. Each item has origin agent or database. Embedded mode reads the pack catalog. External mode proxies skill-api.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "agentId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Function catalog"
+          },
+          "403": {
+            "description": "FORBIDDEN"
+          }
+        }
+      }
+    },
+    "/api/v1/agent-functions/agents/{agentId}/functions/{functionId}/run": {
+      "post": {
+        "operationId": "runAgentFunction",
+        "summary": "Run one function for a stored subject",
+        "description": "Body is objectType and recordId. Subject rows are read through @x12i/memorix-client when this process hosts the function. A storyInput result is written as content type story.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "agentId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "functionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "FunctionResult with structured and text"
+          },
+          "404": {
+            "description": "NOT_FOUND"
+          },
+          "502": {
+            "description": "MEMORIX_UNREACHABLE or MEMORIX_READ_FAILED"
+          }
+        }
+      }
+    },
+    "/api/v1/agent-functions/agents/{agentId}/functions/{functionId}": {
+      "put": {
+        "operationId": "saveAgentFunction",
+        "summary": "Save a Python function override",
+        "description": "Body is source, and optional question, page, and objectTypes. source must define generate_text. Without ASSISTANT_MONGO_URI or MONGO_URI the embedded host returns 503 PERSISTENCE.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "agentId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "functionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Saved override"
+          },
+          "503": {
+            "description": "PERSISTENCE"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "removeAgentFunction",
+        "summary": "Delete a saved function override",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "agentId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "functionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "origin agent or removed"
+          },
+          "503": {
+            "description": "PERSISTENCE"
+          }
+        }
+      }
+    },
+    "/api/v1/scoper": {
+      "get": {
+        "operationId": "scoperInfo",
+        "summary": "Hosted Scoper release",
+        "description": "Reports @x12i/memorix-scoper 3.0.0, the SDK 2.2.0, whether saved functions are attached, mode embedded or external, and the aligned memorix-service 3.17.0, memorix-skills 0.6.1, memorix-client 3.17.0, and ai-dispatcher 3.2.0. Subject reads use @x12i/memorix-client.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Scoper host"
+          }
+        }
+      }
+    },
+    "/api/v1/scoper/scope": {
+      "post": {
+        "operationId": "scoperScope",
+        "summary": "Run a scope",
+        "description": "Body is a ScopeRequest: profileId, question, and optional focus, budgets, options, hints. Org, agents, and caller come from the call headers. The same fields in the body are ignored. Saved query and scope functions run when SCOPER_FUNCTIONS_DIR is set; otherwise the reasoner answers.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Evidence bundle"
+          },
+          "400": {
+            "description": "INVALID_REQUEST"
+          }
+        }
+      }
+    },
+    "/api/v1/scoper/subject-data": {
+      "post": {
+        "operationId": "scoperSubjectData",
+        "summary": "Read one subject's content through Scoper",
+        "description": "Body is recordId, objectType, and contentType. Optional alsoContentTypes, sourceContentTypes, include, properties, exclude, and useMarkdown. Scope headers select the org and agents.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Subject data"
+          },
+          "400": {
+            "description": "INVALID_REQUEST"
+          },
+          "404": {
+            "description": "READ_NOT_FOUND"
+          }
+        }
+      }
+    },
+    "/api/v1/mcp/scoper": {
+      "get": {
+        "operationId": "scoperMcpAdvertise",
+        "summary": "Advertise memorix-scoper",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Advertise document. mcpUrl is this API."
+          }
+        }
+      },
+      "post": {
+        "operationId": "scoperMcpCall",
+        "summary": "JSON-RPC for memorix-scoper",
+        "description": "Methods: initialize, ping, tools/list, tools/call, notifications. Tools: catalog, subjects_list, subjects_query, subject_data, scope.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "JSON-RPC result"
+          }
+        }
+      }
+    },
+    "/api/v1/mcp/mgc": {
+      "get": {
+        "operationId": "mgcMcpAdvertise",
+        "summary": "Advertise memorix-mgc",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "MGC advertise"
+          },
+          "404": {
+            "description": "MGC URL is not configured"
+          }
+        }
+      },
+      "post": {
+        "operationId": "mgcMcpCall",
+        "summary": "JSON-RPC for the MGC connector MCP",
+        "description": "Forwards to the MGC source host /mcp. Stable fetch tools include mgc_list_connectors, mgc_describe_connector, and mgc_fetch.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "JSON-RPC result"
+          },
+          "404": {
+            "description": "MGC URL is not configured"
+          }
+        }
+      }
+    },
+    "/ready": {
+      "get": {
+        "operationId": "ready",
+        "summary": "200 when this process can reach Memorix, 503 otherwise. No token",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Memorix down",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/capabilities": {
+      "get": {
+        "operationId": "capabilities",
+        "summary": "Contract id, revision, feature flags, and limits. Takes the token and caller, not an org or agents",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Capabilities"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UNAUTHORIZED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/organizations": {
+      "get": {
+        "operationId": "organizations",
+        "summary": "Orgs on the verified token",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UNAUTHORIZED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/organization": {
+      "get": {
+        "operationId": "organization",
+        "summary": "The selected org and its capabilities",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "SCOPE_INVALID, AGENT_UNKNOWN, VALIDATION",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UNAUTHORIZED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "SCOPE_FORBIDDEN, AGENT_NOT_DEPLOYED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "UPSTREAM_UNAVAILABLE",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "504": {
+            "description": "UPSTREAM_TIMEOUT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/agents": {
+      "get": {
+        "operationId": "agents",
+        "summary": "Agents deployed for the org, or installed on the platform",
+        "parameters": [
+          {
+            "name": "deployment",
+            "in": "query",
+            "required": false,
+            "description": "org (default) or platform",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "org",
+                "platform"
+              ]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "SCOPE_INVALID, AGENT_UNKNOWN, VALIDATION",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UNAUTHORIZED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "SCOPE_FORBIDDEN, AGENT_NOT_DEPLOYED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "CAPABILITY_UNAVAILABLE orgAgents",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "UPSTREAM_UNAVAILABLE",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "504": {
+            "description": "UPSTREAM_TIMEOUT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/mapping": {
+      "get": {
+        "operationId": "mapping",
+        "summary": "Declared structure and observed counts for the org and agents",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "include",
+            "in": "query",
+            "required": false,
+            "description": "Comma-separated subset of counts, relationships, functions, sources. Default all",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "onlyPresent",
+            "in": "query",
+            "required": false,
+            "description": "true drops exact-zero object types and content types",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "refresh",
+            "in": "query",
+            "required": false,
+            "description": "true reads the census again",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "If-None-Match",
+            "in": "header",
+            "required": false,
+            "description": "ETag from a previous response. A match is 304",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Mapping"
+                }
+              }
+            }
+          },
+          "304": {
+            "description": "Not modified; empty body"
+          },
+          "400": {
+            "description": "SCOPE_INVALID, AGENT_UNKNOWN, VALIDATION",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UNAUTHORIZED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "SCOPE_FORBIDDEN, AGENT_NOT_DEPLOYED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "UPSTREAM_UNAVAILABLE",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "504": {
+            "description": "UPSTREAM_TIMEOUT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/census": {
+      "get": {
+        "operationId": "census",
+        "summary": "Counts for every declared pair, plus relationship totals and pairs",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "refresh",
+            "in": "query",
+            "required": false,
+            "description": "true reads the census again",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "If-None-Match",
+            "in": "header",
+            "required": false,
+            "description": "ETag from a previous response. A match is 304",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "304": {
+            "description": "Not modified; empty body"
+          },
+          "400": {
+            "description": "SCOPE_INVALID, AGENT_UNKNOWN, VALIDATION",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UNAUTHORIZED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "SCOPE_FORBIDDEN, AGENT_NOT_DEPLOYED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "CAPABILITY_UNAVAILABLE census",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "UPSTREAM_UNAVAILABLE",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "504": {
+            "description": "UPSTREAM_TIMEOUT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/object-types/{objectType}/definitions": {
+      "get": {
+        "operationId": "objectTypeDefinitions",
+        "summary": "Effective body, or both conflict bodies, with the resolution",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "$ref": "#/components/parameters/ObjectType"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "SCOPE_INVALID, AGENT_UNKNOWN, VALIDATION",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UNAUTHORIZED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "SCOPE_FORBIDDEN, AGENT_NOT_DEPLOYED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "READ_NOT_FOUND",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "UPSTREAM_UNAVAILABLE",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "504": {
+            "description": "UPSTREAM_TIMEOUT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/content": {
+      "get": {
+        "operationId": "content",
+        "summary": "Rows of one object type and content type. With recordId, every current head of that record",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "objectType",
+            "in": "query",
+            "required": true,
+            "description": "Object type",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "contentType",
+            "in": "query",
+            "required": true,
+            "description": "Content type",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "recordId",
+            "in": "query",
+            "required": false,
+            "description": "One record: every current head, ordered by discriminator value",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "discriminatorValue",
+            "in": "query",
+            "required": false,
+            "description": "Keep the instance with this discriminator value",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "includeDeleted",
+            "in": "query",
+            "required": false,
+            "description": "Include logically deleted heads",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "filter",
+            "in": "query",
+            "required": false,
+            "description": "JSON array of { field, op, value }",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "sort",
+            "in": "query",
+            "required": false,
+            "description": "JSON array of { field, direction }. Default recordId ascending, then the stored row key",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "1-200, default 50",
+            "schema": {
+              "type": "integer"
+            }
+          },
+          {
+            "name": "cursor",
+            "in": "query",
+            "required": false,
+            "description": "pageInfo.nextCursor",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "refs",
+            "in": "query",
+            "required": false,
+            "description": "status (default) or expand",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "include",
+            "in": "query",
+            "required": false,
+            "description": "history",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "count",
+            "in": "query",
+            "required": false,
+            "description": "true returns { count, countStatus } and no rows",
+            "schema": {
+              "type": "boolean"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ContentPage"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "SCOPE_INVALID, AGENT_UNKNOWN, VALIDATION",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UNAUTHORIZED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "SCOPE_FORBIDDEN, AGENT_NOT_DEPLOYED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "READ_NOT_FOUND",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "METADATA_CONFLICT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "UPSTREAM_UNAVAILABLE",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "504": {
+            "description": "UPSTREAM_TIMEOUT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/content/{objectType}/{contentType}/{recordId}": {
+      "get": {
+        "operationId": "contentHead",
+        "summary": "One current head. The record id is one segment with / as %2F",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "objectType",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "contentType",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "recordId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "discriminatorValue",
+            "in": "query",
+            "required": false,
+            "description": "Required when the content type has a discriminator",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "includeDeleted",
+            "in": "query",
+            "required": false,
+            "description": "",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "refs",
+            "in": "query",
+            "required": false,
+            "description": "status (default) or expand",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "include",
+            "in": "query",
+            "required": false,
+            "description": "history",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "scope": {
+                      "$ref": "#/components/schemas/Scope"
+                    },
+                    "row": {
+                      "$ref": "#/components/schemas/ContentRow"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "SCOPE_INVALID, AGENT_UNKNOWN, VALIDATION",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UNAUTHORIZED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "SCOPE_FORBIDDEN, AGENT_NOT_DEPLOYED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "READ_NOT_FOUND with details.storedValues",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "METADATA_CONFLICT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "UPSTREAM_UNAVAILABLE",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "504": {
+            "description": "UPSTREAM_TIMEOUT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/relationships/definitions": {
+      "get": {
+        "operationId": "relationshipDefinitions",
+        "summary": "Definitions with concrete pairs, cardinality, compilation, and link counts",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "SCOPE_INVALID, AGENT_UNKNOWN, VALIDATION",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UNAUTHORIZED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "SCOPE_FORBIDDEN, AGENT_NOT_DEPLOYED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "UPSTREAM_UNAVAILABLE",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "504": {
+            "description": "UPSTREAM_TIMEOUT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/relationships": {
+      "get": {
+        "operationId": "relationships",
+        "summary": "Stored links of one record, or counts per definition",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "recordId",
+            "in": "query",
+            "required": false,
+            "description": "Required unless countOnly=true",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "direction",
+            "in": "query",
+            "required": false,
+            "description": "forward, inverse, or both (default)",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "definitionId",
+            "in": "query",
+            "required": false,
+            "description": "One or several, comma-separated",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "objectType",
+            "in": "query",
+            "required": false,
+            "description": "Keep links whose other end is this object type",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "countOnly",
+            "in": "query",
+            "required": false,
+            "description": "true returns counts and no links; requires definitionId",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "groupBy",
+            "in": "query",
+            "required": false,
+            "description": "objectType adds pair counts",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "1-200, default 50",
+            "schema": {
+              "type": "integer"
+            }
+          },
+          {
+            "name": "cursor",
+            "in": "query",
+            "required": false,
+            "description": "pageInfo.nextCursor",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "SCOPE_INVALID, AGENT_UNKNOWN, VALIDATION",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UNAUTHORIZED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "SCOPE_FORBIDDEN, AGENT_NOT_DEPLOYED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "UPSTREAM_UNAVAILABLE",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "504": {
+            "description": "UPSTREAM_TIMEOUT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/sources": {
+      "get": {
+        "operationId": "sources",
+        "summary": "Source catalog joined to the source census",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SourcesDocument"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "SCOPE_INVALID, AGENT_UNKNOWN, VALIDATION",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UNAUTHORIZED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "SCOPE_FORBIDDEN, AGENT_NOT_DEPLOYED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "UPSTREAM_UNAVAILABLE",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "504": {
+            "description": "UPSTREAM_TIMEOUT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/sources/{sourceId}": {
+      "get": {
+        "operationId": "source",
+        "summary": "One source with recent runs",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ScopeHeaders"
+          },
+          {
+            "name": "sourceId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "SCOPE_INVALID, AGENT_UNKNOWN, VALIDATION",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UNAUTHORIZED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "SCOPE_FORBIDDEN, AGENT_NOT_DEPLOYED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "READ_NOT_FOUND",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "UPSTREAM_UNAVAILABLE",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "504": {
+            "description": "UPSTREAM_TIMEOUT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/planning/items": {
+      "get": {
+        "operationId": "planningList",
+        "summary": "Planning items of the org. Agent header optional; it only changes targetState",
+        "parameters": [
+          {
+            "name": "stage",
+            "in": "query",
+            "required": false,
+            "description": "",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "priority",
+            "in": "query",
+            "required": false,
+            "description": "",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "assignee",
+            "in": "query",
+            "required": false,
+            "description": "Assignee id or unassigned",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "objectType",
+            "in": "query",
+            "required": false,
+            "description": "",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "contentType",
+            "in": "query",
+            "required": false,
+            "description": "",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "definitionId",
+            "in": "query",
+            "required": false,
+            "description": "",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "archived",
+            "in": "query",
+            "required": false,
+            "description": "Default false",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "",
+            "schema": {
+              "type": "integer"
+            }
+          },
+          {
+            "name": "cursor",
+            "in": "query",
+            "required": false,
+            "description": "",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlanningList"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "SCOPE_INVALID, AGENT_UNKNOWN, VALIDATION",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UNAUTHORIZED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "SCOPE_FORBIDDEN, AGENT_NOT_DEPLOYED",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "CAPABILITY_UNAVAILABLE planning",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "UPSTREAM_UNAVAILABLE",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "504": {
+            "description": "UPSTREAM_TIMEOUT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "planningCreate",
+        "summary": "Create. A repeat clientKey returns the existing item with 200. Needs token feature memorix-planning-write",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": true
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Existing item for clientKey",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlanningItemResponse"
+                }
+              }
+            }
+          },
+          "201": {
+            "description": "Created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlanningItemResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "PLANNING_FORBIDDEN",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "501": {
+            "description": "CAPABILITY_UNAVAILABLE planning",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/planning/items/{itemId}": {
+      "get": {
+        "operationId": "planningGet",
+        "summary": "One item. ETag is the quoted revision",
+        "parameters": [
+          {
+            "name": "itemId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "If-None-Match",
+            "in": "header",
+            "required": false,
+            "description": "ETag from a previous response. A match is 304",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlanningItemResponse"
+                }
+              }
+            }
+          },
+          "304": {
+            "description": "Not modified; empty body"
+          },
+          "404": {
+            "description": "READ_NOT_FOUND",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      },
+      "patch": {
+        "operationId": "planningUpdate",
+        "summary": "Edit title, outcome, category, priority, assigneeId, or stage. If-Match required",
+        "parameters": [
+          {
+            "name": "itemId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "If-Match",
+            "in": "header",
+            "required": false,
+            "description": "Quoted item revision, for example \"3\"",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": true
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlanningItemResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "VALIDATION, ASSIGNEE_UNKNOWN",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "PLANNING_FORBIDDEN",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "PLANNING_CONFLICT; error.current is the current item",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/planning/items/{itemId}/stage": {
+      "post": {
+        "operationId": "planningStage",
+        "summary": "Move stage. If-Match required",
+        "parameters": [
+          {
+            "name": "itemId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "If-Match",
+            "in": "header",
+            "required": false,
+            "description": "Quoted item revision, for example \"3\"",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "stage": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlanningItemResponse"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "PLANNING_CONFLICT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/planning/items/{itemId}/archive": {
+      "post": {
+        "operationId": "planningArchive",
+        "summary": "archived true. If-Match optional, checked when sent",
+        "parameters": [
+          {
+            "name": "itemId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "If-Match",
+            "in": "header",
+            "required": false,
+            "description": "Quoted item revision, for example \"3\"",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlanningItemResponse"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "PLANNING_CONFLICT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/planning/items/{itemId}/reopen": {
+      "post": {
+        "operationId": "planningReopen",
+        "summary": "archived false, stage investigate. If-Match optional, checked when sent",
+        "parameters": [
+          {
+            "name": "itemId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "If-Match",
+            "in": "header",
+            "required": false,
+            "description": "Quoted item revision, for example \"3\"",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlanningItemResponse"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "PLANNING_CONFLICT",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/planning/assignees": {
+      "get": {
+        "operationId": "planningAssignees",
+        "summary": "Assignee options; unassigned (id null) is always present",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "parameters": {
+      "ScopeHeaders": {
+        "name": "scope",
+        "in": "header",
+        "required": true,
+        "description": "Send x-memorix-org-id, x-memorix-agent-ids (comma-separated), and x-memorix-caller on every /api/v1 call.",
+        "schema": {
+          "type": "string"
+        }
+      },
+      "ObjectType": {
+        "name": "objectType",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string"
+        }
+      },
+      "ContentType": {
+        "name": "contentType",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string"
+        }
+      }
+    },
+    "schemas": {
+      "Error": {
+        "type": "object",
+        "required": [
+          "error"
+        ],
+        "properties": {
+          "error": {
+            "type": "object",
+            "required": [
+              "code",
+              "message",
+              "retryable"
+            ],
+            "properties": {
+              "code": {
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              },
+              "requestId": {
+                "type": "string"
+              },
+              "retryable": {
+                "type": "boolean"
+              },
+              "feature": {
+                "type": "string",
+                "description": "Capability flag that is off, on 501 CAPABILITY_UNAVAILABLE"
+              },
+              "details": {
+                "type": "object",
+                "additionalProperties": true
+              },
+              "current": {
+                "$ref": "#/components/schemas/PlanningItem",
+                "description": "Current item on 409 PLANNING_CONFLICT"
+              }
+            }
+          }
+        }
+      },
+      "Scope": {
+        "type": "object",
+        "properties": {
+          "orgId": {
+            "type": "string"
+          },
+          "caller": {
+            "type": "string"
+          },
+          "requestedAgentIds": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "agentSelection": {
+            "type": "string",
+            "enum": [
+              "explicit",
+              "wildcard",
+              "implicit"
+            ]
+          },
+          "agentIds": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "deployedAgentIds": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "unresolvedAgentIds": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "PageInfo": {
+        "type": "object",
+        "required": [
+          "complete"
+        ],
+        "properties": {
+          "complete": {
+            "type": "boolean"
+          },
+          "nextCursor": {
+            "type": "string"
+          },
+          "limit": {
+            "type": "integer"
+          }
+        }
+      },
+      "Count": {
+        "type": "object",
+        "required": [
+          "status",
+          "value"
+        ],
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "exact",
+              "estimated",
+              "unavailable"
+            ]
+          },
+          "value": {
+            "type": "integer",
+            "nullable": true
+          },
+          "reason": {
+            "type": "string"
+          },
+          "retryable": {
+            "type": "boolean"
+          },
+          "deletedExcluded": {
+            "type": "boolean"
+          },
+          "versionSemantics": {
+            "type": "string",
+            "enum": [
+              "current-head",
+              "directory",
+              "stored-links"
+            ]
+          },
+          "method": {
+            "type": "string"
+          },
+          "observedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "aggregated": {
+            "type": "boolean"
+          }
+        }
+      },
+      "Gap": {
+        "type": "object",
+        "required": [
+          "code",
+          "category",
+          "orgId",
+          "agentIds",
+          "retryable"
+        ],
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "category": {
+            "type": "string",
+            "enum": [
+              "empty",
+              "directory-only",
+              "not-measured",
+              "estimated",
+              "inaccessible",
+              "resolution-failure",
+              "unavailable",
+              "stale"
+            ]
+          },
+          "section": {
+            "type": "string",
+            "enum": [
+              "counts",
+              "relationships",
+              "functions",
+              "sources"
+            ]
+          },
+          "orgId": {
+            "type": "string"
+          },
+          "agentIds": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "objectType": {
+            "type": "string"
+          },
+          "contentType": {
+            "type": "string"
+          },
+          "definitionId": {
+            "type": "string"
+          },
+          "sourceId": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "observedAt": {
+            "type": "string"
+          },
+          "retryable": {
+            "type": "boolean"
+          },
+          "evidence": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        }
+      },
+      "Capabilities": {
+        "type": "object",
+        "properties": {
+          "service": {
+            "type": "string"
+          },
+          "api": {
+            "type": "string"
+          },
+          "contract": {
+            "type": "string",
+            "example": "visualizer"
+          },
+          "contractRevision": {
+            "type": "string",
+            "example": "2026-10-24"
+          },
+          "features": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "boolean"
+            }
+          },
+          "limits": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "integer"
+            }
+          },
+          "rateLimit": {
+            "nullable": true,
+            "type": "object"
+          }
+        }
+      },
+      "SourcesDocument": {
+        "type": "object",
+        "required": [
+          "status",
+          "census",
+          "sources",
+          "attribution",
+          "gaps"
+        ],
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "complete",
+              "partial",
+              "unavailable"
+            ]
+          },
+          "census": {
+            "type": "object",
+            "properties": {
+              "status": {
+                "type": "string",
+                "enum": [
+                  "live",
+                  "backfilling",
+                  "disabled",
+                  "error",
+                  "unavailable"
+                ]
+              },
+              "observedAt": {
+                "type": "string",
+                "nullable": true
+              },
+              "censusId": {
+                "type": "string",
+                "nullable": true
+              }
+            }
+          },
+          "sources": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          },
+          "attribution": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "gaps": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Gap"
+            }
+          }
+        }
+      },
+      "Mapping": {
+        "type": "object",
+        "required": [
+          "scope",
+          "status",
+          "observations",
+          "metadata",
+          "objectTypes",
+          "gaps"
+        ],
+        "properties": {
+          "scope": {
+            "$ref": "#/components/schemas/Scope"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "complete",
+              "partial",
+              "unavailable"
+            ]
+          },
+          "observations": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "metadata": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "agents": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          },
+          "objectTypes": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          },
+          "relationshipDefinitions": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          },
+          "sources": {
+            "$ref": "#/components/schemas/SourcesDocument"
+          },
+          "coverage": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "gaps": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Gap"
+            }
+          }
+        }
+      },
+      "ContentRow": {
+        "type": "object",
+        "required": [
+          "format",
+          "recordId",
+          "contentType",
+          "revision",
+          "head",
+          "data",
+          "source",
+          "timestamps",
+          "state",
+          "history",
+          "redactedMetadata",
+          "descriptorCoverage",
+          "undeclaredPaths"
+        ],
+        "properties": {
+          "format": {
+            "type": "string"
+          },
+          "recordId": {
+            "type": "string"
+          },
+          "objectType": {
+            "type": "string"
+          },
+          "contentType": {
+            "type": "string"
+          },
+          "dataCategory": {
+            "type": "string"
+          },
+          "revision": {
+            "type": "integer",
+            "nullable": true
+          },
+          "head": {
+            "type": "boolean"
+          },
+          "discriminatorValue": {
+            "type": "string",
+            "nullable": true
+          },
+          "data": {},
+          "source": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "timestamps": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "state": {
+            "type": "string",
+            "enum": [
+              "active",
+              "deleted"
+            ]
+          },
+          "deletion": {
+            "type": "object",
+            "nullable": true,
+            "additionalProperties": true
+          },
+          "history": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "metadata": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "redactedMetadata": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "descriptorCoverage": {
+            "type": "string",
+            "enum": [
+              "complete",
+              "partial",
+              "none"
+            ]
+          },
+          "undeclaredPaths": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "ContentPage": {
+        "type": "object",
+        "required": [
+          "rows",
+          "pageInfo"
+        ],
+        "properties": {
+          "scope": {
+            "$ref": "#/components/schemas/Scope"
+          },
+          "objectType": {
+            "type": "string"
+          },
+          "contentType": {
+            "type": "string"
+          },
+          "addressing": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "pageInfo": {
+            "$ref": "#/components/schemas/PageInfo"
+          },
+          "truncated": {
+            "type": "boolean"
+          },
+          "rows": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ContentRow"
+            }
+          }
+        }
+      },
+      "RecordsPage": {
+        "type": "object",
+        "required": [
+          "records",
+          "pageInfo"
+        ],
+        "properties": {
+          "scope": {
+            "$ref": "#/components/schemas/Scope"
+          },
+          "objectType": {
+            "type": "string"
+          },
+          "leadingContentType": {
+            "type": "string"
+          },
+          "total": {
+            "type": "integer",
+            "nullable": true
+          },
+          "totalStatus": {
+            "type": "string",
+            "enum": [
+              "exact",
+              "unavailable"
+            ]
+          },
+          "pageInfo": {
+            "$ref": "#/components/schemas/PageInfo"
+          },
+          "truncated": {
+            "type": "boolean"
+          },
+          "records": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          },
+          "items": {
+            "type": "array",
+            "description": "0.18.0 shape, kept for existing callers",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          }
+        }
+      },
+      "PlanningItem": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "orgId": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "outcome": {
+            "type": "string"
+          },
+          "target": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "targetState": {
+            "type": "string",
+            "enum": [
+              "in-catalog",
+              "not-in-catalog",
+              "unknown"
+            ]
+          },
+          "category": {
+            "type": "string",
+            "enum": [
+              "data-gap",
+              "visibility-gap",
+              "unused-structure",
+              "proposed-change"
+            ]
+          },
+          "priority": {
+            "type": "string",
+            "enum": [
+              "low",
+              "medium",
+              "high"
+            ]
+          },
+          "assigneeId": {
+            "type": "string",
+            "nullable": true
+          },
+          "assignee": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "stage": {
+            "type": "string",
+            "enum": [
+              "investigate",
+              "plan-next",
+              "later",
+              "done"
+            ]
+          },
+          "archived": {
+            "type": "boolean"
+          },
+          "revision": {
+            "type": "integer"
+          },
+          "createdBy": {
+            "type": "string"
+          },
+          "createdAt": {
+            "type": "string"
+          },
+          "updatedBy": {
+            "type": "string"
+          },
+          "updatedAt": {
+            "type": "string"
+          },
+          "evidence": {},
+          "clientKey": {
+            "type": "string"
+          }
+        }
+      },
+      "PlanningItemResponse": {
+        "type": "object",
+        "required": [
+          "item"
+        ],
+        "properties": {
+          "scope": {
+            "$ref": "#/components/schemas/Scope"
+          },
+          "item": {
+            "$ref": "#/components/schemas/PlanningItem"
+          },
+          "gaps": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Gap"
+            }
+          }
+        }
+      },
+      "PlanningList": {
+        "type": "object",
+        "required": [
+          "items",
+          "pageInfo"
+        ],
+        "properties": {
+          "scope": {
+            "$ref": "#/components/schemas/Scope"
+          },
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PlanningItem"
+            }
+          },
+          "pageInfo": {
+            "$ref": "#/components/schemas/PageInfo"
+          },
+          "gaps": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Gap"
+            }
+          }
+        }
+      }
+    }
+  }
+}