@naturali/cli 0.136.0 → 0.137.0

package/dist/index.mjs

@@ -17,7 +17,7 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region package.json
-var version = "0.136.0";
+var version = "0.137.0";
 //#endregion
 //#region ../sdk/src/generated/core/bodySerializer.gen.ts
 const serializeFormDataPair = (data, key, value) => {
@@ -645,6 +645,17 @@ var Activity = class {
 			...options
 		});
 	}
+	/**
+	* Export the activity feed as NDJSON
+	*
+	* Streams a project's activity entries as newline-delimited JSON — one entry object per line, **oldest first**, where the feed itself reads newest first: a feed answers what just happened, and a file is read start to end. `project_id` is required: the export is per-project by design. Filters behave exactly as they do on the list endpoint.
+	*/
+	static exportActivity(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/activity/export",
+			...options
+		});
+	}
 };
 var Actors = class {
 	/**
@@ -2024,6 +2035,17 @@ var Documents = class {
 		});
 	}
 	/**
+	* Export documents as NDJSON
+	*
+	* Streams a project's documents as newline-delimited JSON — one document object per line, oldest first — for archiving the corpus or shipping it into another system. `project_id` is required: the export is per-project by design. The rows are the rows the listing returns for the same caller, so a policy that hides a document hides it here too, and withdrawn documents and the reserved `/.system/` root are left out.
+	*/
+	static exportDocuments(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/documents/export",
+			...options
+		});
+	}
+	/**
 	* Delete a document
 	*
 	* Deletes a document and its underlying file
@@ -2061,6 +2083,45 @@ var Documents = class {
 		});
 	}
 	/**
+	* List a document's relations
+	*
+	* Returns the typed edges this document asserts about others, oldest first. An edge is owned by the document it leaves, so this is what the document claims — use `?related_to=` on the listing to find what claims something about it.
+	*/
+	static listDocumentRelations(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/documents/{document_id}/relations",
+			...options
+		});
+	}
+	/**
+	* Assert a relation
+	*
+	* Asserts a typed edge from this document to another in the same project. Asserting the same edge twice is `409`: an edge is a fact, and the second assertion is the same fact.
+	*
+	* Writing an edge is a write of the asserting document (`documents:UpdateDocument`); the document it points at is unchanged, which is what lets an agent record what its own report derives from without being able to make another report claim anything.
+	*/
+	static createDocumentRelation(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/documents/{document_id}/relations",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Retract a relation
+	*
+	* Removes an edge this document asserts. Both documents are left as they are — retracting a claim is not a change to what it was about.
+	*/
+	static deleteDocumentRelation(options) {
+		return (options.client ?? client).delete({
+			url: "/v1/projects/{project_id}/documents/{document_id}/relations/{relation_id}",
+			...options
+		});
+	}
+	/**
 	* Get document ingestion status
 	*
 	* Returns a lightweight ingestion status payload for polling — `status`,
@@ -2078,6 +2139,70 @@ var Documents = class {
 		});
 	}
 	/**
+	* Withdraw a document
+	*
+	* Takes a document out of every default read while keeping its history. The withdrawal is archived as a **tombstone version**, so one mechanism answers what a document holds now and there is no second lifecycle flag for a reader to miss.
+	*
+	* Its chunks are dropped from the knowledge index, so a withdrawn document costs a live search nothing. The content is not lost with them: it is in the version before the tombstone, which [`POST /v1/projects/{project_id}/documents/{document_id}/versions/{version}/restore`](/docs/api/documents/restore-document-version) re-chunks from.
+	*
+	* `DELETE` stays what it is — permanent, and it removes the backing file. Withdrawal is the reversible act. It does not apply under `/.system/`: a platform-written document keeps the owning module's lifecycle.
+	*
+	*/
+	static withdrawDocument(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/documents/{document_id}/withdraw",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* List a document's content versions
+	*
+	* Returns the document's archived states, newest first. A version is written on create and on every subsequent write that changes the content or its annotations, and a withdrawal is archived as a version carrying no content.
+	*
+	*/
+	static listDocumentVersions(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/documents/{document_id}/versions",
+			...options
+		});
+	}
+	/**
+	* Fetch an archived document version
+	*
+	* Returns the exact content and annotations the document held at a given version, which is what lets a run that cited a version read what it read.
+	*
+	*/
+	static getDocumentVersion(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/documents/{document_id}/versions/{version}",
+			...options
+		});
+	}
+	/**
+	* Restore an archived document version
+	*
+	* Writes an archived version's content and annotations back as the document's live state, which archives them again as a **new** version rather than rewinding the counter — so a run citing any version in between still resolves.
+	*
+	* The restore runs through the ordinary update path, so the content is re-chunked and re-embedded; restoring the state the document already holds is a no-op and archives nothing. Restoring any content version of a withdrawn document brings it back into listings and search.
+	*
+	* A tombstone version has no content, so naming one is `400 VALIDATION_FAILED`: restore the version before it instead.
+	*
+	*/
+	static restoreDocumentVersion(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/documents/{document_id}/versions/{version}/restore",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
 	* Re-ingest an existing document
 	*
 	* Re-runs ingestion for an existing document against its already-stored
@@ -3122,6 +3247,26 @@ var Memories = class {
 		});
 	}
 	/**
+	* Retract a memory
+	*
+	* Retires a fact that stopped holding with nothing replacing it. The memory leaves the default listing, [knowledge search](/docs/api/knowledge/search-knowledge) and write deduplication, so restating the fact later lands as a new memory.
+	*
+	* It is an invalidation with no successor, which is what tells it apart from a supersede: `invalidated_at` is set and `superseded_by_memory_id` stays null. The retraction is appended to the assertion ledger with outcome `retracted`, so who withdrew the fact is part of the record.
+	*
+	* The memory stays readable by id, with its text and its assertions. `DELETE` remains the way to remove it outright.
+	*
+	*/
+	static retractMemory(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/memories/{memory_id}/retract",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
 	* List a memory's assertions
 	*
 	* Returns every write that resolved into this memory, oldest first: the one that created it, the duplicates it absorbed, and the assertion that superseded another memory in its favour. A superseded memory keeps its own assertions, so the chain can be walked in both directions.
@@ -3315,6 +3460,17 @@ var MemoryStores = class {
 		});
 	}
 	/**
+	* Export a memory store's memories as NDJSON
+	*
+	* Streams one store's memories as newline-delimited JSON — one memory object per line, oldest first. Invalidated memories (retracted or superseded) are left out unless `include_invalidated` asks for them, so the file holds what the store currently asserts. The rows are the rows the listing returns for the same caller.
+	*/
+	static exportMemories(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/memory-stores/{memory_store_id}/export",
+			...options
+		});
+	}
+	/**
 	* Get memory store tags
 	*
 	* Returns all tags attached to the memory store
@@ -3356,6 +3512,92 @@ var MemoryStores = class {
 		});
 	}
 };
+var MetadataSchemas = class {
+	/**
+	* List metadata schemas
+	*
+	* Returns the declarations in scope, oldest first. `resource_type` narrows them to one governed resource.
+	*/
+	static listMetadataSchemas(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/metadata-schemas",
+			...options
+		});
+	}
+	/**
+	* Declare a metadata schema
+	*
+	* Declares what `metadata` must satisfy for one resource type under one selector. A document is selected by `path_prefix`, matched on a path boundary: `/reports` covers `/reports/q1.txt` and never `/reports-archive/q1.txt`.
+	*
+	* The schema is compiled here, so one JSON Schema cannot parse is refused rather than stored — a stored one would be a rule that silently governs nothing. One selector has one schema per resource type; a second declaration of the same one is `409 NAME_CONFLICT`. The reserved root `/.system` cannot be governed: a platform-written document carries no caller metadata.
+	*
+	*/
+	static createMetadataSchema(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/metadata-schemas",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Check metadata against what is declared
+	*
+	* Answers what a write would be told, without writing: a caller preparing a batch learns which declaration would refuse it, and why, before it sends anything.
+	*
+	* It reports; it does not enforce. The refusal itself lives in each resource's own write path, because a check a writer has to call is advisory and the writer who skips it is the one the rule exists for.
+	*
+	*/
+	static validateMetadata(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/metadata-schemas/validate",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Delete a metadata schema
+	*
+	* Removes the declaration. Documents already stored keep the metadata they hold — the rule governed writes, not rows.
+	*/
+	static deleteMetadataSchema(options) {
+		return (options.client ?? client).delete({
+			url: "/v1/projects/{project_id}/metadata-schemas/{metadata_schema_id}",
+			...options
+		});
+	}
+	/**
+	* Get a metadata schema
+	*
+	* Returns one declaration by id.
+	*/
+	static getMetadataSchema(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/metadata-schemas/{metadata_schema_id}",
+			...options
+		});
+	}
+	/**
+	* Update a metadata schema
+	*
+	* Changes the schema, the selector, or both. `resource_type` is fixed at creation: it decides the selector's spelling and which write path reads the row, so changing it would silently repoint the declaration at a different door — delete it and declare again instead.
+	*/
+	static updateMetadataSchema(options) {
+		return (options.client ?? client).patch({
+			url: "/v1/projects/{project_id}/metadata-schemas/{metadata_schema_id}",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+};
 var ModelRoutes = class {
 	/**
 	* List model routes
@@ -4993,6 +5235,7 @@ var NaturaliClient = class {
 	memories;
 	memoryRules;
 	memoryStores;
+	metadataSchemas;
 	modelRoutes;
 	quotas;
 	models;
@@ -5044,6 +5287,7 @@ var NaturaliClient = class {
 		this.memories = bindResource(Memories, this.http);
 		this.memoryRules = bindResource(MemoryRules, this.http);
 		this.memoryStores = bindResource(MemoryStores, this.http);
+		this.metadataSchemas = bindResource(MetadataSchemas, this.http);
 		this.modelRoutes = bindResource(ModelRoutes, this.http);
 		this.quotas = bindResource(Quotas, this.http);
 		this.models = bindResource(Models, this.http);
@@ -5090,6 +5334,7 @@ var src_exports = /* @__PURE__ */ __exportAll({
 	Memories: () => Memories,
 	MemoryRules: () => MemoryRules,
 	MemoryStores: () => MemoryStores,
+	MetadataSchemas: () => MetadataSchemas,
 	ModelRoutes: () => ModelRoutes,
 	Models: () => Models,
 	NaturaliClient: () => NaturaliClient,
@@ -5775,6 +6020,67 @@ const routes = {
 			}
 		]
 	},
+	"export-activity": {
+		serviceClass: "Activity",
+		operationId: "exportActivity",
+		description: "Streams a project's activity entries as newline-delimited JSON — one entry object per line, **oldest first**, where the feed itself reads newest first: a feed answers what just happened, and a file is read start to end. `project_id` is required: the export is per-project by design. Filters behave exactly as they do on the list endpoint.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/activity",
+		httpMethod: "get",
+		pathParams: ["project_id"],
+		queryParams: [
+			"kind",
+			"severity",
+			"agent_id",
+			"generation_id",
+			"orchestration_run_id"
+		],
+		headerParams: [],
+		cookieParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "kind",
+				"description": "Only entries of this kind",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "severity",
+				"description": "Only entries of this severity",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "agent_id",
+				"description": "Only entries an agent produced",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "generation_id",
+				"description": "Only entries a generation produced",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "orchestration_run_id",
+				"description": "Only entries an orchestration run produced",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			}
+		]
+	},
 	"list-actors": {
 		serviceClass: "Actors",
 		operationId: "listActors",
@@ -6001,7 +6307,7 @@ const routes = {
 			},
 			{
 				"name": "tags",
-				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.\n\nKeys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.",
+				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.\n\nKeys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.\n\nThe bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is `400 VALIDATION_FAILED` with `meta.limit` naming the bound it crossed. `system.*` keys are the platform's and do not count against the 50.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -6937,6 +7243,13 @@ const routes = {
 				"required": false,
 				"type": "string",
 				"in": "body"
+			},
+			{
+				"name": "expected_version",
+				"description": "Refuses the write unless the resource is at this version.",
+				"required": false,
+				"type": "string",
+				"in": "body"
 			}
 		]
 	},
@@ -6948,7 +7261,7 @@ const routes = {
 		httpMethod: "patch",
 		pathParams: ["project_id", "agent_id"],
 		queryParams: [],
-		headerParams: [],
+		headerParams: ["If-Match"],
 		cookieParams: [],
 		flags: [
 			{
@@ -6965,6 +7278,13 @@ const routes = {
 				"type": "string",
 				"in": "path"
 			},
+			{
+				"name": "If-Match",
+				"description": "The version the caller believes the resource holds, as an entity tag (`3` or `\"3\"`). Equivalent to `expected_version` in the request body; `*` states no precondition beyond the resource existing. A mismatch is `409 VERSION_CONFLICT`.",
+				"required": false,
+				"type": "string",
+				"in": "header"
+			},
 			{
 				"name": "ai_provider_id",
 				"description": "",
@@ -7118,6 +7438,13 @@ const routes = {
 				"required": false,
 				"type": "string",
 				"in": "body"
+			},
+			{
+				"name": "expected_version",
+				"description": "Refuses the write unless the resource is at this version.",
+				"required": false,
+				"type": "string",
+				"in": "body"
 			}
 		]
 	},
@@ -7254,7 +7581,7 @@ const routes = {
 				"name": "metadata",
 				"description": "Caller-supplied key/value metadata attached to the generation record for per-run audit attribution (e.g. the knowledge-corpus version that produced this action). Round-trips verbatim when the generation is fetched via the generations API. The bag is caller-owned and no key is reserved: server-owned state (usage attribution, the served agent version, the model route's record, the extraction summary) lives in its own top-level generation fields and cannot be written from here. Use the request's own `action_id` field to set the usage-attribution label.",
 				"required": false,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			},
 			{
@@ -9695,9 +10022,9 @@ const routes = {
 			},
 			{
 				"name": "metadata",
-				"description": "Optional structured metadata to attach to the message (e.g. phone number, channel). Stored as-is and injected into the AI prompt context.",
+				"description": "Caller-owned annotations on the message (e.g. a phone number, a channel), stored as sent and returned verbatim. The platform does not read the bag, so nothing in it reaches the model: a value the model should see belongs in `message`.",
 				"required": false,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			}
 		]
@@ -9883,7 +10210,10 @@ const routes = {
 		pathParams: ["project_id"],
 		queryParams: [
 			"path_prefix",
+			"include_withdrawn",
+			"related_to",
 			"tags",
+			"metadata",
 			"limit",
 			"offset"
 		],
@@ -9904,6 +10234,20 @@ const routes = {
 				"type": "string",
 				"in": "query"
 			},
+			{
+				"name": "include_withdrawn",
+				"description": "Include withdrawn documents. A withdrawn document leaves every default read and is not in the knowledge index at all — its chunks are dropped when it is withdrawn — so this shows it in the listing but never in a search.",
+				"required": false,
+				"type": "boolean",
+				"in": "query"
+			},
+			{
+				"name": "related_to",
+				"description": "Only documents related to this one, on either side of the edge: what it points at, and what points at it. An id with no relations narrows the listing to nothing.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
 			{
 				"name": "tags",
 				"description": "Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; **all** must be present with exactly that value.\n",
@@ -9911,6 +10255,13 @@ const routes = {
 				"type": "array",
 				"in": "query"
 			},
+			{
+				"name": "metadata",
+				"description": "A `MetadataFilter` as JSON, url-encoded. It travels as JSON rather than as `key:value` pairs because the match is exact and a query string cannot otherwise say whether `3` is the number or the string.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
 			{
 				"name": "limit",
 				"description": "Maximum number of results to return",
@@ -9977,12 +10328,12 @@ const routes = {
 				"name": "metadata",
 				"description": "Arbitrary metadata object. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase.",
 				"required": false,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			},
 			{
 				"name": "tags",
-				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.\n\nKeys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.",
+				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.\n\nKeys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.\n\nThe bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is `400 VALIDATION_FAILED` with `meta.limit` naming the bound it crossed. `system.*` keys are the platform's and do not count against the 50.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -10051,7 +10402,7 @@ const routes = {
 			},
 			{
 				"name": "tags",
-				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.\n\nKeys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.",
+				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.\n\nKeys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.\n\nThe bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is `400 VALIDATION_FAILED` with `meta.limit` naming the bound it crossed. `system.*` keys are the platform's and do not count against the 50.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -10079,10 +10430,34 @@ const routes = {
 			}
 		]
 	},
-	"get-document": {
+	"export-documents": {
 		serviceClass: "Documents",
-		operationId: "getDocument",
-		description: "Returns a document with its text content",
+		operationId: "exportDocuments",
+		description: "Streams a project's documents as newline-delimited JSON — one document object per line, oldest first — for archiving the corpus or shipping it into another system. `project_id` is required: the export is per-project by design. The rows are the rows the listing returns for the same caller, so a policy that hides a document hides it here too, and withdrawn documents and the reserved `/.system/` root are left out.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/documents",
+		httpMethod: "get",
+		pathParams: ["project_id"],
+		queryParams: ["path_prefix"],
+		headerParams: [],
+		cookieParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "path_prefix",
+			"description": "Only documents filed under this directory. The prefix is a path boundary, not a substring, exactly as on the listing.",
+			"required": false,
+			"type": "string",
+			"in": "query"
+		}]
+	},
+	"get-document": {
+		serviceClass: "Documents",
+		operationId: "getDocument",
+		description: "Returns a document with its text content",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/documents",
 		httpMethod: "get",
 		pathParams: ["project_id", "document_id"],
@@ -10111,7 +10486,7 @@ const routes = {
 		httpMethod: "patch",
 		pathParams: ["project_id", "document_id"],
 		queryParams: [],
-		headerParams: [],
+		headerParams: ["If-Match"],
 		cookieParams: [],
 		flags: [
 			{
@@ -10128,6 +10503,13 @@ const routes = {
 				"type": "string",
 				"in": "path"
 			},
+			{
+				"name": "If-Match",
+				"description": "The version the caller believes the resource holds, as an entity tag (`3` or `\"3\"`). Equivalent to `expected_version` in the request body; `*` states no precondition beyond the resource existing. A mismatch is `409 VERSION_CONFLICT`.",
+				"required": false,
+				"type": "string",
+				"in": "header"
+			},
 			{
 				"name": "content",
 				"description": "New text content",
@@ -10151,17 +10533,24 @@ const routes = {
 			},
 			{
 				"name": "metadata",
-				"description": "Arbitrary metadata object. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase.",
+				"description": "Arbitrary metadata object, replacing the stored bag; `null` clears it. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase.",
 				"required": false,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			},
 			{
 				"name": "tags",
-				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.\n\nKeys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.",
+				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.\n\nKeys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.\n\nThe bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is `400 VALIDATION_FAILED` with `meta.limit` naming the bound it crossed. `system.*` keys are the platform's and do not count against the 50.",
 				"required": false,
 				"type": "object",
 				"in": "body"
+			},
+			{
+				"name": "expected_version",
+				"description": "Refuses the write unless the document is at this version.",
+				"required": false,
+				"type": "string",
+				"in": "body"
 			}
 		]
 	},
@@ -10189,6 +10578,109 @@ const routes = {
 			"in": "path"
 		}]
 	},
+	"list-document-relations": {
+		serviceClass: "Documents",
+		operationId: "listDocumentRelations",
+		description: "Returns the typed edges this document asserts about others, oldest first. An edge is owned by the document it leaves, so this is what the document claims — use `?related_to=` on the listing to find what claims something about it.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/documents",
+		httpMethod: "get",
+		pathParams: ["project_id", "document_id"],
+		queryParams: [],
+		headerParams: [],
+		cookieParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "document_id",
+			"description": "",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
+	"create-document-relation": {
+		serviceClass: "Documents",
+		operationId: "createDocumentRelation",
+		description: "Asserts a typed edge from this document to another in the same project. Asserting the same edge twice is `409`: an edge is a fact, and the second assertion is the same fact. Writing an edge is a write of the asserting document (`documents:UpdateDocument`); the document it points at is unchanged, which is what lets an agent record what its own report derives from without being able to make another report claim anything.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/documents",
+		httpMethod: "post",
+		pathParams: ["project_id", "document_id"],
+		queryParams: [],
+		headerParams: [],
+		cookieParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "document_id",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "type",
+				"description": "What this document claims about the other",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "to_document_id",
+				"description": "The document the edge points at. Must be in the same project, and visible to the caller.",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			}
+		]
+	},
+	"delete-document-relation": {
+		serviceClass: "Documents",
+		operationId: "deleteDocumentRelation",
+		description: "Removes an edge this document asserts. Both documents are left as they are — retracting a claim is not a change to what it was about.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/documents",
+		httpMethod: "delete",
+		pathParams: [
+			"project_id",
+			"document_id",
+			"relation_id"
+		],
+		queryParams: [],
+		headerParams: [],
+		cookieParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "document_id",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "relation_id",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			}
+		]
+	},
 	"get-document-status": {
 		serviceClass: "Documents",
 		operationId: "getDocumentStatus",
@@ -10213,6 +10705,178 @@ const routes = {
 			"in": "path"
 		}]
 	},
+	"withdraw-document": {
+		serviceClass: "Documents",
+		operationId: "withdrawDocument",
+		description: "Takes a document out of every default read while keeping its history. The withdrawal is archived as a **tombstone version**, so one mechanism answers what a document holds now and there is no second lifecycle flag for a reader to miss. Its chunks are dropped from the knowledge index, so a withdrawn document costs a live search nothing. The content is not lost with them: it is in the version before the tombstone, which [`POST /v1/projects/{project_id}/documents/{document_id}/versions/{version}/restore`](/docs/api/documents/restore-document-version) re-chunks from. `DELETE` stays what it is — permanent, and it removes the backing file. Withdrawal is the reversible act. It does not apply under `/.system/`: a platform-written document keeps the owning module's lifecycle.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/documents",
+		httpMethod: "post",
+		pathParams: ["project_id", "document_id"],
+		queryParams: [],
+		headerParams: ["If-Match"],
+		cookieParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "document_id",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "If-Match",
+				"description": "The version the caller believes the resource holds, as an entity tag (`3` or `\"3\"`). Equivalent to `expected_version` in the request body; `*` states no precondition beyond the resource existing. A mismatch is `409 VERSION_CONFLICT`.",
+				"required": false,
+				"type": "string",
+				"in": "header"
+			},
+			{
+				"name": "version_label",
+				"description": "Optional tag for the tombstone version this write archives.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "expected_version",
+				"description": "Refuses the withdrawal unless the document is at this version.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			}
+		]
+	},
+	"list-document-versions": {
+		serviceClass: "Documents",
+		operationId: "listDocumentVersions",
+		description: "Returns the document's archived states, newest first. A version is written on create and on every subsequent write that changes the content or its annotations, and a withdrawal is archived as a version carrying no content.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/documents",
+		httpMethod: "get",
+		pathParams: ["project_id", "document_id"],
+		queryParams: ["limit", "offset"],
+		headerParams: [],
+		cookieParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "document_id",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "limit",
+				"description": "Maximum number of results to return",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			},
+			{
+				"name": "offset",
+				"description": "Number of results to skip",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			}
+		]
+	},
+	"get-document-version": {
+		serviceClass: "Documents",
+		operationId: "getDocumentVersion",
+		description: "Returns the exact content and annotations the document held at a given version, which is what lets a run that cited a version read what it read.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/documents",
+		httpMethod: "get",
+		pathParams: [
+			"project_id",
+			"document_id",
+			"version"
+		],
+		queryParams: [],
+		headerParams: [],
+		cookieParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "document_id",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "version",
+				"description": "",
+				"required": true,
+				"type": "integer",
+				"in": "path"
+			}
+		]
+	},
+	"restore-document-version": {
+		serviceClass: "Documents",
+		operationId: "restoreDocumentVersion",
+		description: "Writes an archived version's content and annotations back as the document's live state, which archives them again as a **new** version rather than rewinding the counter — so a run citing any version in between still resolves. The restore runs through the ordinary update path, so the content is re-chunked and re-embedded; restoring the state the document already holds is a no-op and archives nothing. Restoring any content version of a withdrawn document brings it back into listings and search. A tombstone version has no content, so naming one is `400 VALIDATION_FAILED`: restore the version before it instead.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/documents",
+		httpMethod: "post",
+		pathParams: [
+			"project_id",
+			"document_id",
+			"version"
+		],
+		queryParams: [],
+		headerParams: [],
+		cookieParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "document_id",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "version",
+				"description": "",
+				"required": true,
+				"type": "integer",
+				"in": "path"
+			},
+			{
+				"name": "label",
+				"description": "Optional tag for the version this restore archives. Defaults to `restored from v<version>`.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			}
+		]
+	},
 	"reingest-document": {
 		serviceClass: "Documents",
 		operationId: "reingestDocument",
@@ -10615,7 +11279,7 @@ const routes = {
 				"name": "metadata",
 				"description": "Free-form tags, opaque to the platform",
 				"required": false,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			}
 		]
@@ -10663,7 +11327,7 @@ const routes = {
 				"name": "metadata",
 				"description": "Free-form tags, opaque to the platform",
 				"required": false,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			}
 		]
@@ -10722,7 +11386,7 @@ const routes = {
 				"name": "metadata",
 				"description": "",
 				"required": false,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			}
 		]
@@ -11055,7 +11719,7 @@ const routes = {
 				"name": "metadata",
 				"description": "Caller-supplied key/value metadata attached to the run record for attribution — what this measurement was of (the commit or release candidate being scored, the CI job that asked for it). Round-trips verbatim on every read of the run, the list included.\n\nThe bag is caller-owned and no key is reserved: everything the platform decides about a run (`status`, `agent_version`, `baseline_run_id`, `aggregate_scores`, `passed`, the counts) is a field of its own and cannot be written from here. Nothing in the scoring path reads it. A non-object is rejected with `400 VALIDATION_FAILED` and no run is created.",
 				"required": false,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			},
 			{
@@ -11439,9 +12103,9 @@ const routes = {
 			},
 			{
 				"name": "metadata",
-				"description": "JSON string with additional metadata",
+				"description": "Caller-owned annotations on a resource, stored as the object they were written as: the types a value was written with are the types a read returns, so a filter can ask an ordering question about a number. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase.\n\nNo key is reserved, and that is the point: every piece of state the platform owns lives in its own typed column, so nothing written here reaches platform state. The platform never reads the bag — it is not an IAM context, not a policy input and not part of a prompt — which is what separates it from a tag bag.",
 				"required": false,
-				"type": "string",
+				"type": "object",
 				"in": "body"
 			}
 		]
@@ -11512,9 +12176,9 @@ const routes = {
 			},
 			{
 				"name": "metadata",
-				"description": "JSON string with additional metadata",
+				"description": "Caller-owned annotations on a resource, stored as the object they were written as: the types a value was written with are the types a read returns, so a filter can ask an ordering question about a number. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase.\n\nNo key is reserved, and that is the point: every piece of state the platform owns lives in its own typed column, so nothing written here reaches platform state. The platform never reads the bag — it is not an IAM context, not a policy input and not part of a prompt — which is what separates it from a tag bag.",
 				"required": false,
-				"type": "string",
+				"type": "object",
 				"in": "body"
 			}
 		]
@@ -11628,7 +12292,7 @@ const routes = {
 			},
 			{
 				"name": "metadata",
-				"description": "New metadata as a JSON string",
+				"description": "Replaces the stored bag; `null` clears it.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -11907,7 +12571,7 @@ const routes = {
 				"name": "metadata",
 				"description": "Static annotations stored on the formation record. This field is NOT a substitution site: `sub`/`param`/`ref` expressions are rejected with 400 (`FORMATION_INVALID_METADATA`). For deploy-time substitution use the template's top-level `metadata` block, which is resolved into `resolved_metadata`.\n",
 				"required": false,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			}
 		]
@@ -11979,7 +12643,7 @@ const routes = {
 				"name": "metadata",
 				"description": "Static annotations stored on the formation record. This field is NOT a substitution site: `sub`/`param`/`ref` expressions are rejected with 400 (`FORMATION_INVALID_METADATA`). For deploy-time substitution use the template's top-level `metadata` block, which is resolved into `resolved_metadata`.\n",
 				"required": false,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			}
 		]
@@ -12211,7 +12875,7 @@ const routes = {
 				"name": "metadata",
 				"description": "Caller-supplied key/value metadata to shallow-merge into the generation record's caller-owned `metadata` bag. No key is reserved: server-owned state lives in its own top-level fields and cannot be written from here.\n",
 				"required": true,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			}
 		]
@@ -12392,7 +13056,7 @@ const routes = {
 		httpMethod: "patch",
 		pathParams: ["project_id", "guardrail_id"],
 		queryParams: [],
-		headerParams: [],
+		headerParams: ["If-Match"],
 		cookieParams: [],
 		flags: [
 			{
@@ -12409,6 +13073,13 @@ const routes = {
 				"type": "string",
 				"in": "path"
 			},
+			{
+				"name": "If-Match",
+				"description": "The version the caller believes the resource holds, as an entity tag (`3` or `\"3\"`). Equivalent to `expected_version` in the request body; `*` states no precondition beyond the resource existing. A mismatch is `409 VERSION_CONFLICT`.",
+				"required": false,
+				"type": "string",
+				"in": "header"
+			},
 			{
 				"name": "name",
 				"description": "",
@@ -12450,6 +13121,13 @@ const routes = {
 				"required": false,
 				"type": "string",
 				"in": "body"
+			},
+			{
+				"name": "expected_version",
+				"description": "Refuses the write unless the resource is at this version.",
+				"required": false,
+				"type": "string",
+				"in": "body"
 			}
 		]
 	},
@@ -12775,7 +13453,7 @@ const routes = {
 				"name": "metadata",
 				"description": "Arbitrary JSON metadata",
 				"required": false,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			}
 		]
@@ -12901,7 +13579,7 @@ const routes = {
 			},
 			{
 				"name": "metadata",
-				"description": "",
+				"description": "A `MetadataBag` on a field where `null` is meaningful — a full-replacement update that clears the bag, or a record whose bag was never set.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -13026,6 +13704,13 @@ const routes = {
 				"required": false,
 				"type": "string",
 				"in": "body"
+			},
+			{
+				"name": "metadata",
+				"description": "Filter document results by their `metadata` bag. A document-store filter: a memory carries no such bag, so passing it alone searches documents, as `document_paths` does.",
+				"required": false,
+				"type": "string",
+				"in": "body"
 			}
 		]
 	},
@@ -13083,7 +13768,7 @@ const routes = {
 			},
 			{
 				"name": "include_invalidated",
-				"description": "Include invalidated (superseded) memories. They are excluded by default; set this to audit the supersede history.",
+				"description": "Include invalidated memories — superseded or retracted. They are excluded by default; set this to audit what a store once held.",
 				"required": false,
 				"type": "boolean",
 				"in": "query"
@@ -13147,7 +13832,7 @@ const routes = {
 				"name": "metadata",
 				"description": "Arbitrary structured metadata attached to the memory",
 				"required": false,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			},
 			{
@@ -13205,7 +13890,7 @@ const routes = {
 		httpMethod: "put",
 		pathParams: ["project_id", "memory_id"],
 		queryParams: [],
-		headerParams: [],
+		headerParams: ["If-Match"],
 		cookieParams: [],
 		flags: [
 			{
@@ -13222,6 +13907,13 @@ const routes = {
 				"type": "string",
 				"in": "path"
 			},
+			{
+				"name": "If-Match",
+				"description": "The version the caller believes the resource holds, as an entity tag (`3` or `\"3\"`). Equivalent to `expected_version` in the request body; `*` states no precondition beyond the resource existing. A mismatch is `409 VERSION_CONFLICT`.",
+				"required": false,
+				"type": "string",
+				"in": "header"
+			},
 			{
 				"name": "content",
 				"description": "Updated text content",
@@ -13237,10 +13929,17 @@ const routes = {
 				"in": "body"
 			},
 			{
-				"name": "metadata",
-				"description": "Replaces the memory's metadata. Pass null to clear.",
+				"name": "metadata",
+				"description": "Replaces the memory's metadata. Pass null to clear.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "expected_version",
+				"description": "Refuses the write unless the memory is at this version.",
 				"required": false,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			}
 		]
@@ -13269,6 +13968,47 @@ const routes = {
 			"in": "path"
 		}]
 	},
+	"retract-memory": {
+		serviceClass: "Memories",
+		operationId: "retractMemory",
+		description: "Retires a fact that stopped holding with nothing replacing it. The memory leaves the default listing, [knowledge search](/docs/api/knowledge/search-knowledge) and write deduplication, so restating the fact later lands as a new memory. It is an invalidation with no successor, which is what tells it apart from a supersede: `invalidated_at` is set and `superseded_by_memory_id` stays null. The retraction is appended to the assertion ledger with outcome `retracted`, so who withdrew the fact is part of the record. The memory stays readable by id, with its text and its assertions. `DELETE` remains the way to remove it outright.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/memories",
+		httpMethod: "post",
+		pathParams: ["project_id", "memory_id"],
+		queryParams: [],
+		headerParams: ["If-Match"],
+		cookieParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "memory_id",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "If-Match",
+				"description": "The version the caller believes the resource holds, as an entity tag (`3` or `\"3\"`). Equivalent to `expected_version` in the request body; `*` states no precondition beyond the resource existing. A mismatch is `409 VERSION_CONFLICT`.",
+				"required": false,
+				"type": "string",
+				"in": "header"
+			},
+			{
+				"name": "expected_version",
+				"description": "Refuses the retraction unless the memory is at this version.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			}
+		]
+	},
 	"list-memory-assertions": {
 		serviceClass: "Memories",
 		operationId: "listMemoryAssertions",
@@ -13955,6 +14695,47 @@ const routes = {
 			}
 		]
 	},
+	"export-memories": {
+		serviceClass: "MemoryStores",
+		operationId: "exportMemories",
+		description: "Streams one store's memories as newline-delimited JSON — one memory object per line, oldest first. Invalidated memories (retracted or superseded) are left out unless `include_invalidated` asks for them, so the file holds what the store currently asserts. The rows are the rows the listing returns for the same caller.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/memory-stores",
+		httpMethod: "get",
+		pathParams: ["project_id", "memory_store_id"],
+		queryParams: ["include_invalidated", "tags"],
+		headerParams: [],
+		cookieParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "memory_store_id",
+				"description": "Memory store whose memories are exported",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "include_invalidated",
+				"description": "Include memories that were retracted or superseded",
+				"required": false,
+				"type": "boolean",
+				"in": "query"
+			},
+			{
+				"name": "tags",
+				"description": "Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; **all** must be present with exactly that value.\n",
+				"required": false,
+				"type": "array",
+				"in": "query"
+			}
+		]
+	},
 	"get-memory-store-tags": {
 		serviceClass: "MemoryStores",
 		operationId: "getMemoryStoreTags",
@@ -14027,6 +14808,215 @@ const routes = {
 			"in": "path"
 		}]
 	},
+	"list-metadata-schemas": {
+		serviceClass: "MetadataSchemas",
+		operationId: "listMetadataSchemas",
+		description: "Returns the declarations in scope, oldest first. `resource_type` narrows them to one governed resource.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/metadata-schemas",
+		httpMethod: "get",
+		pathParams: ["project_id"],
+		queryParams: [
+			"resource_type",
+			"limit",
+			"offset"
+		],
+		headerParams: [],
+		cookieParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "resource_type",
+				"description": "Return only the declarations governing this resource.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "limit",
+				"description": "Maximum number of results to return",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			},
+			{
+				"name": "offset",
+				"description": "Number of results to skip",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			}
+		]
+	},
+	"create-metadata-schema": {
+		serviceClass: "MetadataSchemas",
+		operationId: "createMetadataSchema",
+		description: "Declares what `metadata` must satisfy for one resource type under one selector. A document is selected by `path_prefix`, matched on a path boundary: `/reports` covers `/reports/q1.txt` and never `/reports-archive/q1.txt`. The schema is compiled here, so one JSON Schema cannot parse is refused rather than stored — a stored one would be a rule that silently governs nothing. One selector has one schema per resource type; a second declaration of the same one is `409 NAME_CONFLICT`. The reserved root `/.system` cannot be governed: a platform-written document carries no caller metadata.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/metadata-schemas",
+		httpMethod: "post",
+		pathParams: ["project_id"],
+		queryParams: [],
+		headerParams: [],
+		cookieParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "resource_type",
+				"description": "The resource whose metadata this declaration governs. A type appears here once its write path reads the registry, so a declaration always has a door that enforces it.",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "path_prefix",
+				"description": "The selector a `document` declaration must carry: the directory it governs.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "schema",
+				"description": "A JSON Schema. Its keywords are its own vocabulary and are stored as written.",
+				"required": true,
+				"type": "object",
+				"in": "body"
+			}
+		]
+	},
+	"validate-metadata": {
+		serviceClass: "MetadataSchemas",
+		operationId: "validateMetadata",
+		description: "Answers what a write would be told, without writing: a caller preparing a batch learns which declaration would refuse it, and why, before it sends anything. It reports; it does not enforce. The refusal itself lives in each resource's own write path, because a check a writer has to call is advisory and the writer who skips it is the one the rule exists for.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/metadata-schemas",
+		httpMethod: "post",
+		pathParams: ["project_id"],
+		queryParams: [],
+		headerParams: [],
+		cookieParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "path",
+				"description": "The path the document would be filed at, which decides which declaration governs it.",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "metadata",
+				"description": "The bag to judge. Absent or `null` is judged as an empty bag.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			}
+		]
+	},
+	"get-metadata-schema": {
+		serviceClass: "MetadataSchemas",
+		operationId: "getMetadataSchema",
+		description: "Returns one declaration by id.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/metadata-schemas",
+		httpMethod: "get",
+		pathParams: ["project_id", "metadata_schema_id"],
+		queryParams: [],
+		headerParams: [],
+		cookieParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "metadata_schema_id",
+			"description": "",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
+	"update-metadata-schema": {
+		serviceClass: "MetadataSchemas",
+		operationId: "updateMetadataSchema",
+		description: "Changes the schema, the selector, or both. `resource_type` is fixed at creation: it decides the selector's spelling and which write path reads the row, so changing it would silently repoint the declaration at a different door — delete it and declare again instead.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/metadata-schemas",
+		httpMethod: "patch",
+		pathParams: ["project_id", "metadata_schema_id"],
+		queryParams: [],
+		headerParams: [],
+		cookieParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "metadata_schema_id",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "path_prefix",
+				"description": "The declaration's new selector.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "schema",
+				"description": "Replaces the declared JSON Schema.",
+				"required": false,
+				"type": "object",
+				"in": "body"
+			}
+		]
+	},
+	"delete-metadata-schema": {
+		serviceClass: "MetadataSchemas",
+		operationId: "deleteMetadataSchema",
+		description: "Removes the declaration. Documents already stored keep the metadata they hold — the rule governed writes, not rows.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/metadata-schemas",
+		httpMethod: "delete",
+		pathParams: ["project_id", "metadata_schema_id"],
+		queryParams: [],
+		headerParams: [],
+		cookieParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "metadata_schema_id",
+			"description": "",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
 	"list-model-routes": {
 		serviceClass: "ModelRoutes",
 		operationId: "listModelRoutes",
@@ -14492,7 +15482,7 @@ const routes = {
 		httpMethod: "patch",
 		pathParams: ["project_id", "orchestration_id"],
 		queryParams: [],
-		headerParams: [],
+		headerParams: ["If-Match"],
 		cookieParams: [],
 		flags: [
 			{
@@ -14509,6 +15499,13 @@ const routes = {
 				"type": "string",
 				"in": "path"
 			},
+			{
+				"name": "If-Match",
+				"description": "The version the caller believes the resource holds, as an entity tag (`3` or `\"3\"`). Equivalent to `expected_version` in the request body; `*` states no precondition beyond the resource existing. A mismatch is `409 VERSION_CONFLICT`.",
+				"required": false,
+				"type": "string",
+				"in": "header"
+			},
 			{
 				"name": "name",
 				"description": "",
@@ -14557,6 +15554,13 @@ const routes = {
 				"required": false,
 				"type": "string",
 				"in": "body"
+			},
+			{
+				"name": "expected_version",
+				"description": "Refuses the write unless the resource is at this version.",
+				"required": false,
+				"type": "string",
+				"in": "body"
 			}
 		]
 	},
@@ -14811,7 +15815,7 @@ const routes = {
 			},
 			{
 				"name": "tool_context",
-				"description": "Key-value pairs forwarded as `X-Naturali-Context-<key>` headers on every `http` and `mcp` tool call made by an agent node of this run — including the agents of any child run a `loop` or `sub_orchestration` node starts. The header name is `X-Naturali-Context-` plus the key verbatim; no character is re-cased.\n\nThe bag is stored on the run and re-read on every step, so it survives an `awaiting_input` pause, a `sleeping` wait, a background worker drive and a crash redrive. It is **write-only**: a run is a record every principal who may read runs can read, and a credential in it is not theirs to see, so it is never returned on one. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with `400 INVALID_TOOL_CONTEXT_KEY` and no run is created.\n\nThe reserved identity keys (`session_id`, `actor_id`, `actor_external_id`) are stripped at generation time — a caller cannot address them from here.",
+				"description": "Key-value pairs forwarded as `X-Naturali-Context-<key>` headers on every `http` and `mcp` tool call made by an agent node of this run — including the agents of any child run a `loop` or `sub_orchestration` node starts. The header name is `X-Naturali-Context-` plus the key verbatim; no character is re-cased.\n\nThe bag is stored on the run and re-read on every step, so it survives an `awaiting_input` pause, a `sleeping` wait, a background worker drive and a crash redrive. It is **write-only**: a run is a record every principal who may read runs can read, and a credential in it is not theirs to see, so it is never returned on one. It also does not outlive the run: reaching a terminal status (`succeeded`, `failed`, `cancelled` or `expired`) clears it. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with `400 INVALID_TOOL_CONTEXT_KEY` and no run is created.\n\nThe reserved identity keys (`session_id`, `actor_id`, `actor_external_id`) are stripped at generation time — a caller cannot address them from here.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -14820,7 +15824,7 @@ const routes = {
 				"name": "metadata",
 				"description": "Caller-supplied key/value metadata attached to the run record for per-run attribution (e.g. which of your own tenants this run belongs to, or the dispatch batch that started it). Round-trips verbatim on every read of the run, on the list as well as the single read.\n\nThe bag is caller-owned and no key is reserved: server-owned state (status, the pinned orchestration version, the trace, usage, artifacts, the run's own `input` and accumulated `state`) lives in its own top-level field and cannot be written from here.\n\nIt is **not** merged into run state: no graph node sees it, and an `input_schema` never has to tolerate it — which is what makes it the place for an infrastructural label, rather than `input`. Keys are never transformed. It is not inherited by the child runs a `loop` or `sub_orchestration` node starts; each child carries whatever the graph gives it, which today is nothing.",
 				"required": false,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			},
 			{
@@ -16183,7 +17187,7 @@ const routes = {
 			},
 			{
 				"name": "tool_context",
-				"description": "Key-value pairs forwarded as `X-Naturali-Context-<key>` headers on every `http` and `mcp` tool call in this session. The header name is the deployment's configured context prefix (`X-Naturali-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with `400 INVALID_TOOL_CONTEXT_KEY`.",
+				"description": "Key-value pairs forwarded as `X-Naturali-Context-<key>` headers on every `http` and `mcp` tool call in this session. The header name is the deployment's configured context prefix (`X-Naturali-Context-` by default) plus the key verbatim — no character is re-cased. Keys are stored exactly as sent and never case-converted. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with `400 INVALID_TOOL_CONTEXT_KEY`. `session_id`, `actor_id` and `actor_external_id` are server-derived and dropped from the stored bag, in any casing. Write-only: no read of a session returns it. It also does not outlive the session: closing or expiring it clears the bag.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -16276,7 +17280,7 @@ const routes = {
 			},
 			{
 				"name": "tool_context",
-				"description": "Key-value pairs forwarded as `X-Naturali-Context-<key>` headers on every `http` and `mcp` tool call in this session. The header name is the deployment's configured context prefix (`X-Naturali-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with `400 INVALID_TOOL_CONTEXT_KEY`.",
+				"description": "Key-value pairs forwarded as `X-Naturali-Context-<key>` headers on every `http` and `mcp` tool call in this session. The header name is the deployment's configured context prefix (`X-Naturali-Context-` by default) plus the key verbatim — no character is re-cased. Keys are stored exactly as sent and never case-converted. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with `400 INVALID_TOOL_CONTEXT_KEY`. `session_id`, `actor_id` and `actor_external_id` are server-derived and dropped from the stored bag, in any casing. Write-only: no read of a session returns it. It also does not outlive the session: closing or expiring it clears the bag.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -16513,7 +17517,7 @@ const routes = {
 			},
 			{
 				"name": "tags",
-				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.\n\nKeys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.",
+				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.\n\nKeys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.\n\nThe bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is `400 VALIDATION_FAILED` with `meta.limit` naming the bound it crossed. `system.*` keys are the platform's and do not count against the 50.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -16781,7 +17785,7 @@ const routes = {
 				"name": "metadata",
 				"description": "Caller-supplied key/value metadata attached to the task record for attribution — which of your own tenants the task belongs to, the ticket that raised it, the import batch that created it. Round-trips verbatim on every read of the task, the list included, and survives every transition (a transition supplies no metadata of its own).\n\nThe bag is caller-owned and no key is reserved: everything the engine decides about a task (`state`, `status`, `workflow_version`, `last_result`, `active_dispatch`, the automation fields) is a field of its own and cannot be written from here.\n\nPrefer this over `payload` for anything that is not task data: `payload` is read by every guard as `task.payload` and may be written by the workflow's declared `payload_writes`, so a label parked there is neither invisible to the state machine nor safe from it. A non-object is rejected with `400 VALIDATION_FAILED` and no task is created.",
 				"required": false,
-				"type": "object",
+				"type": "string",
 				"in": "body"
 			}
 		]
@@ -18454,7 +19458,7 @@ const routes = {
 		httpMethod: "patch",
 		pathParams: ["project_id", "workflow_id"],
 		queryParams: [],
-		headerParams: [],
+		headerParams: ["If-Match"],
 		cookieParams: [],
 		flags: [
 			{
@@ -18471,6 +19475,13 @@ const routes = {
 				"type": "string",
 				"in": "path"
 			},
+			{
+				"name": "If-Match",
+				"description": "The version the caller believes the resource holds, as an entity tag (`3` or `\"3\"`). Equivalent to `expected_version` in the request body; `*` states no precondition beyond the resource existing. A mismatch is `409 VERSION_CONFLICT`.",
+				"required": false,
+				"type": "string",
+				"in": "header"
+			},
 			{
 				"name": "name",
 				"description": "",
@@ -18512,6 +19523,13 @@ const routes = {
 				"required": false,
 				"type": "string",
 				"in": "body"
+			},
+			{
+				"name": "expected_version",
+				"description": "Refuses the write unless the resource is at this version.",
+				"required": false,
+				"type": "string",
+				"in": "body"
 			}
 		]
 	},