hngr 0.1.0 → 0.2.0

package/dist/catalog-jU0-wzh3.mjs

@@ -0,0 +1,3184 @@
+// src/generated/catalog.ts
+/** Projects one derived command onto the stable `commands --json` shape. */
+function generatedEntry(spec) {
+	return {
+		name: spec.name,
+		summary: spec.summary,
+		group: spec.group,
+		args: spec.args.map((arg) => ({
+			name: arg.name,
+			required: arg.required,
+			description: arg.description
+		})),
+		flags: spec.flags.map((flag) => ({
+			name: flag.name,
+			type: catalogFlagType(flag),
+			description: flag.description
+		})),
+		destructive: spec.destructive,
+		dryRun: true
+	};
+}
+function catalogFlagType(flag) {
+	return flag.type === "boolean" ? "boolean" : "string";
+}
+// src/generated/overrides.ts
+/**
+* The explicit override table. Every entry that the mechanical naming rules
+* cannot decide lives here, so the ambiguity is reviewable in one place
+* instead of hidden in the derivation algorithm.
+*/
+/** Endpoints that never appear in the command tree. */
+const EXCLUDED_PATHS = [
+	"/api/v1/login",
+	"/api/v1/logout",
+	"/api/v1/me/password",
+	"/api/v1/me/sessions",
+	"/api/v1/me/sessions/{id}",
+	"/api/v1/capabilities/{capability_id}/versions/{version}/content",
+	"/api/v1/auth/methods",
+	"/api/v1/auth/oidc/login",
+	"/api/v1/auth/oidc/callback"
+];
+/**
+* Root-noun aliases. Aliases only affect parsing: help annotates the canonical
+* line, while `commands --json`, `schema` and completion keep the canonical
+* name and the generated catalog never gains an alias entry.
+*/
+const COMMAND_ALIASES = { capabilities: ["caps", "cap"] };
+/**
+* Segments that name a sub-collection rather than an action, even when they
+* follow a path parameter. Without this, `GET /capabilities/{id}/versions`
+* would read as the action `capabilities versions`.
+*/
+const SUBGROUP_SEGMENTS = /* @__PURE__ */ new Set([
+	"versions",
+	"members",
+	"member-candidates",
+	"tokens"
+]);
+const COMMAND_OVERRIDES = [
+	{
+		method: "GET",
+		path: "/api/v1/me",
+		command: "auth whoami",
+		registeredExternally: true,
+		why: "/me is remapped to auth; whoami is hand-written."
+	},
+	{
+		method: "PATCH",
+		path: "/api/v1/me",
+		command: "auth profile update",
+		why: "PATCH /me is the caller's profile, not a principal lookup."
+	},
+	{
+		method: "GET",
+		path: "/api/v1/me/tokens",
+		command: "auth tokens list",
+		why: "/me/tokens belongs under auth, not a `me` noun."
+	},
+	{
+		method: "POST",
+		path: "/api/v1/me/tokens",
+		command: "auth tokens create",
+		why: "/me/tokens belongs under auth, not a `me` noun."
+	},
+	{
+		method: "DELETE",
+		path: "/api/v1/me/tokens/{token_id}",
+		command: "auth tokens revoke",
+		why: "The verb is revoke; the mechanical DELETE verb is delete."
+	},
+	{
+		method: "POST",
+		path: "/api/v1/capabilities",
+		bodyContentType: "application/json",
+		why: "The multipart Skill package variant is published from the Web Console."
+	},
+	{
+		method: "POST",
+		path: "/api/v1/capabilities/{capability_id}/versions",
+		bodyContentType: "application/json",
+		why: "The multipart Skill package variant is published from the Web Console."
+	}
+];
+// src/generated/derive.ts
+const API_PREFIX = "/api/v1/";
+const METHODS = [
+	"GET",
+	"PUT",
+	"POST",
+	"PATCH",
+	"DELETE"
+];
+const METHOD_KEY = {
+	GET: "get",
+	PUT: "put",
+	POST: "post",
+	PATCH: "patch",
+	DELETE: "delete"
+};
+/**
+* Command words the mechanical rules cannot decide. Everything here is
+* deterministic and test-covered; see overrides.ts for the reviewable table.
+*/
+function deriveCommands(doc) {
+	const excluded = new Set(EXCLUDED_PATHS);
+	const overrides = new Map(COMMAND_OVERRIDES.map((item) => [overrideKey(item), item]));
+	const commands = [];
+	for (const [path, pathItem] of Object.entries(doc.paths)) {
+		if (excluded.has(path)) continue;
+		for (const method of METHODS) {
+			const operation = pathItem[METHOD_KEY[method]];
+			if (!operation) continue;
+			commands.push(deriveCommand(doc, path, pathItem, method, operation, overrides));
+		}
+	}
+	return commands;
+}
+function overrideKey(override) {
+	return `${override.method} ${override.path}`;
+}
+function deriveCommand(doc, path, pathItem, method, operation, overrides) {
+	const override = overrides.get(`${method} ${path}`);
+	const name = override?.command ?? deriveName(path, method);
+	const segments = pathSegments(path);
+	const last = segments.at(-1) ?? "";
+	const lastIsParam = isParam(last);
+	const isAction = !lastIsParam && !SUBGROUP_SEGMENTS.has(last) && segments.length > 1 && isParam(segments[segments.length - 2] ?? "");
+	const isCollection = !lastIsParam && !isAction;
+	const parameters = resolveOperationParameters(doc, pathItem, operation);
+	const pathParams = pathParameters(path, parameters);
+	const queryParams = parameters.filter((parameter) => parameter.in === "query" && parameter.name).map(toParameterSpec);
+	const headerParams = parameters.filter((parameter) => parameter.in === "header" && parameter.name).map(toParameterSpec);
+	const body = buildBody(doc, operation, override);
+	const paginated = isCollection && isPaginated(doc, operation, queryParams);
+	const flags = buildFlags(queryParams, headerParams, body, paginated);
+	const args = pathParams.map((parameter) => ({
+		name: parameter.name,
+		required: true,
+		description: parameter.description
+	}));
+	return {
+		name,
+		group: name.split(" ")[0] ?? name,
+		method,
+		path,
+		operationId: operation.operationId ?? name.replaceAll(" ", "_"),
+		summary: operation.summary ?? name,
+		args,
+		flags,
+		pathParams,
+		queryParams,
+		headerParams,
+		body,
+		paginated,
+		destructive: method === "DELETE" || isAction && isDestructiveAction(last),
+		registeredExternally: override?.registeredExternally === true
+	};
+}
+/** The root noun + subgroup + leaf-verb naming rules. Pure and independently testable. */
+function deriveName(path, method) {
+	const segments = pathSegments(path);
+	const last = segments.at(-1) ?? "";
+	let verb;
+	let groupSegments;
+	if (isParam(last)) {
+		groupSegments = segments.slice(0, -1);
+		verb = itemVerb(method);
+	} else if (SUBGROUP_SEGMENTS.has(last)) {
+		groupSegments = segments;
+		verb = collectionVerb(method);
+	} else if (segments.length > 1 && isParam(segments[segments.length - 2] ?? "")) {
+		groupSegments = segments.slice(0, -1);
+		verb = last;
+	} else {
+		groupSegments = segments;
+		verb = collectionVerb(method);
+	}
+	return [...groupSegments.filter((segment) => !isParam(segment)), verb].join(" ");
+}
+function itemVerb(method) {
+	switch (method) {
+		case "GET": return "get";
+		case "PATCH":
+		case "PUT": return "update";
+		case "DELETE": return "delete";
+		case "POST": return "create";
+	}
+}
+function collectionVerb(method) {
+	switch (method) {
+		case "GET": return "list";
+		case "POST": return "create";
+		case "DELETE": return "delete";
+		case "PATCH":
+		case "PUT": return "update";
+	}
+}
+function isDestructiveAction(verb) {
+	return verb === "disable" || verb === "password" || verb === "role";
+}
+function pathSegments(path) {
+	return (path.startsWith(API_PREFIX) ? path.slice(8) : path.replace(/^\//, "")).split("/").filter((segment) => segment !== "");
+}
+function isParam(segment) {
+	return segment.startsWith("{") && segment.endsWith("}");
+}
+function paramName(segment) {
+	return segment.slice(1, -1);
+}
+function pathParameters(path, parameters) {
+	const declared = /* @__PURE__ */ new Map();
+	for (const parameter of parameters) if (parameter.in === "path" && parameter.name) declared.set(parameter.name, parameter);
+	return pathSegments(path).filter(isParam).map((segment) => {
+		const name = paramName(segment);
+		const parameter = declared.get(name);
+		return parameter ? toParameterSpec(parameter) : {
+			name,
+			flag: kebabCase(name),
+			required: true,
+			type: "string"
+		};
+	});
+}
+function toParameterSpec(parameter) {
+	const name = parameter.name ?? "";
+	return {
+		name,
+		flag: kebabCase(name),
+		required: parameter.in === "path" || parameter.required === true,
+		type: parameterType(parameter.schema),
+		description: parameter.description
+	};
+}
+function buildFlags(queryParams, headerParams, body, paginated) {
+	const flags = [];
+	for (const parameter of queryParams) flags.push({
+		name: parameter.flag,
+		type: parameter.type,
+		description: parameter.description,
+		source: "query",
+		target: parameter.name
+	});
+	for (const parameter of headerParams) flags.push({
+		name: parameter.flag,
+		type: parameter.type,
+		description: parameter.description,
+		source: "header",
+		target: parameter.name
+	});
+	for (const field of body?.fields ?? []) flags.push({
+		name: field.flag,
+		type: field.type,
+		description: field.description,
+		source: "body",
+		target: field.name
+	});
+	if (paginated) flags.push({
+		name: "all",
+		type: "boolean",
+		description: "Follow next_cursor to the end and print one merged list",
+		source: "query",
+		target: "all"
+	});
+	if (body) flags.push({
+		name: "body",
+		type: "string",
+		description: "JSON request body, or @file.json",
+		source: "body",
+		target: "body"
+	});
+	return dedupeFlags(flags);
+}
+function dedupeFlags(flags) {
+	const seen = /* @__PURE__ */ new Set();
+	return flags.filter((flag) => {
+		if (seen.has(flag.name)) return false;
+		seen.add(flag.name);
+		return true;
+	});
+}
+function buildBody(doc, operation, override) {
+	const requestBody = resolveRequestBody(doc, operation.requestBody);
+	if (!requestBody?.content) return null;
+	const chosen = chooseContent(requestBody, override?.bodyContentType);
+	if (!chosen) return null;
+	const schema = resolveSchema(doc, chosen.media.schema ?? {});
+	const requiredFields = (schema.required ?? []).filter((field) => typeof field === "string");
+	const required = new Set(requiredFields);
+	const fields = [];
+	for (const [name, property] of Object.entries(schema.properties ?? {})) {
+		const resolved = resolveSchema(doc, property);
+		if (!isPrimitiveSchema(resolved)) continue;
+		fields.push({
+			name,
+			flag: kebabCase(name),
+			required: required.has(name),
+			type: parameterType(resolved),
+			description: resolved.description
+		});
+	}
+	return {
+		contentType: chosen.contentType === "multipart/form-data" ? "multipart/form-data" : "application/json",
+		required: requestBody.required === true,
+		requiredFields,
+		fields,
+		schema
+	};
+}
+function chooseContent(requestBody, preferred) {
+	const content = requestBody.content;
+	if (!content) return;
+	const order = preferred ? [
+		preferred,
+		"application/json",
+		...Object.keys(content)
+	] : ["application/json", ...Object.keys(content)];
+	for (const contentType of order) {
+		const media = content[contentType];
+		if (media) return {
+			contentType,
+			media
+		};
+	}
+}
+function isPaginated(doc, operation, queryParams) {
+	if (queryParams.some((parameter) => parameter.name === "cursor")) return true;
+	for (const status of ["200", "201"]) {
+		const media = resolveResponse(doc, operation.responses?.[status])?.content?.["application/json"];
+		if (!media?.schema) continue;
+		if (resolveSchema(doc, media.schema).properties?.next_cursor !== void 0) return true;
+	}
+	return false;
+}
+function parameterType(schema) {
+	for (const type of schemaTypes(schema)) {
+		if (type === "integer" || type === "number") return "number";
+		if (type === "boolean") return "boolean";
+	}
+	return "string";
+}
+function isPrimitiveSchema(schema) {
+	const types = schemaTypes(schema);
+	if (types.length === 0) return Array.isArray(schema.enum);
+	return types.some((type) => type === "string" || type === "number" || type === "integer" || type === "boolean") && !types.includes("array") && !types.includes("object");
+}
+function schemaTypes(schema) {
+	if (!schema) return [];
+	return (typeof schema.type === "string" ? [schema.type] : Array.isArray(schema.type) ? schema.type.filter((type) => typeof type === "string") : []).filter((type) => type !== "null");
+}
+function resolveOperationParameters(doc, pathItem, operation) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const raw of [...pathItem.parameters ?? [], ...operation.parameters ?? []]) {
+		const parameter = resolveParameter(doc, raw);
+		if (!parameter.name || !parameter.in) continue;
+		merged.set(`${parameter.in}:${parameter.name}`, parameter);
+	}
+	return [...merged.values()];
+}
+function resolveParameter(doc, parameter) {
+	let current = parameter;
+	const seen = /* @__PURE__ */ new Set();
+	for (;;) {
+		const ref = refOf(current);
+		if (!ref) return current;
+		if (seen.has(ref)) throw new Error(`Circular $ref: ${ref}`);
+		seen.add(ref);
+		current = resolvePointer(doc, ref);
+	}
+}
+function resolveRequestBody(doc, raw) {
+	if (!raw) return;
+	const ref = refOf(raw);
+	return ref ? resolvePointer(doc, ref) : raw;
+}
+function resolveResponse(doc, raw) {
+	if (!raw) return;
+	const ref = refOf(raw);
+	return ref ? resolvePointer(doc, ref) : raw;
+}
+/** Dereferences a schema for `hngr schema`; a cycle keeps its `$ref`. */
+function resolveSchema(doc, schema, seen = /* @__PURE__ */ new Set()) {
+	const ref = refOf(schema);
+	if (ref) {
+		if (seen.has(ref)) return { $ref: ref };
+		const next = new Set(seen);
+		next.add(ref);
+		return resolveSchema(doc, resolvePointer(doc, ref), next);
+	}
+	const { $ref: _ignored, ...rest } = schema;
+	const resolved = { ...rest };
+	if (schema.properties) resolved.properties = Object.fromEntries(Object.entries(schema.properties).map(([name, property]) => [name, resolveSchema(doc, property, seen)]));
+	if (schema.items) resolved.items = resolveSchema(doc, schema.items, seen);
+	if (schema.additionalProperties && typeof schema.additionalProperties === "object") resolved.additionalProperties = resolveSchema(doc, schema.additionalProperties, seen);
+	return resolved;
+}
+function refOf(value) {
+	if (value === null || typeof value !== "object") return;
+	const ref = value.$ref;
+	return typeof ref === "string" ? ref : void 0;
+}
+function resolvePointer(doc, ref) {
+	if (!ref.startsWith("#/")) throw new Error(`Only local $ref values are supported: ${ref}`);
+	let current = doc;
+	for (const raw of ref.slice(2).split("/")) {
+		const key = raw.replaceAll("~1", "/").replaceAll("~0", "~");
+		if (current === null || typeof current !== "object" || !(key in current)) throw new Error(`Unresolvable $ref: ${ref}`);
+		current = current[key];
+	}
+	return current;
+}
+/** camelCase, snake_case and hyphenated OpenAPI names all become kebab-case flags. */
+function kebabCase(name) {
+	return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replaceAll("_", "-").toLowerCase();
+}
+/** The command tree derived from the snapshot at module load. */
+const COMMANDS = deriveCommands({
+	openapi: "3.1.0",
+	info: {
+		"title": "Hangar Management API",
+		"version": "v1",
+		"description": "Management API contract for Hangar's `/api/v1`. The contract describes HTTP\nshape, media types, status codes, headers, and authentication declarations\nonly; permissions, business validation, transactions, ZIP safety, and\nstorage consistency are implemented by the domain and infrastructure layers.\n"
+	},
+	servers: [{ "url": "/" }],
+	paths: {
+		"/api/v1/login": { "post": {
+			"operationId": "login",
+			"summary": "Sign in with a username and password and receive a Session cookie.",
+			"description": "Every credential failure returns the same 401 problem, whether the\nusername is unknown, the password is wrong, or the Principal is\ndisabled. Attempts are rate-limited per client address and username\nbefore the password is verified.\n",
+			"security": [],
+			"requestBody": {
+				"required": true,
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }
+			},
+			"responses": {
+				"204": {
+					"description": "Signed in. The Session lasts 12 hours and never slides.",
+					"headers": { "Set-Cookie": {
+						"description": "`hangar_session=<value>; Path=/; HttpOnly; Secure; SameSite=Lax`",
+						"schema": { "type": "string" }
+					} }
+				},
+				"400": { "$ref": "#/components/responses/Problem" },
+				"401": { "$ref": "#/components/responses/Problem" },
+				"403": { "$ref": "#/components/responses/Problem" },
+				"413": { "$ref": "#/components/responses/Problem" },
+				"429": { "$ref": "#/components/responses/Problem" },
+				"default": { "$ref": "#/components/responses/Problem" }
+			}
+		} },
+		"/api/v1/auth/methods": { "get": {
+			"operationId": "lookupAuthMethods",
+			"summary": "Report the login methods this deployment enables.",
+			"description": "Anonymous, so the console can choose which login controls to render\nbefore a Session exists. The password method has no switch and is\nalways enabled. `oidc.display_name` is the issuer host, or null when\nOIDC is disabled.\n",
+			"security": [],
+			"responses": {
+				"200": {
+					"description": "The enabled login methods.",
+					"headers": { "Cache-Control": {
+						"description": "Always `no-store`; deployment configuration may change the answer.",
+						"schema": { "type": "string" }
+					} },
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMethods" } } }
+				},
+				"default": { "$ref": "#/components/responses/Problem" }
+			}
+		} },
+		"/api/v1/auth/oidc/login": { "get": {
+			"operationId": "startOidcLogin",
+			"summary": "Start an OpenID Connect login and redirect to the identity provider.",
+			"description": "Validates `return_to` to a local absolute path, falling back to `/`.\nAn already authenticated caller is redirected to `return_to` without\ncontacting the identity provider. Otherwise the response sets the\nsigned `hangar_oidc_state` cookie and redirects to the authorization\nendpoint. When OIDC is disabled the route answers 404; when discovery\nfails it redirects to `/login?oidc_error=provider_unavailable`.\n",
+			"security": [],
+			"parameters": [{
+				"name": "return_to",
+				"in": "query",
+				"required": false,
+				"description": "Local absolute path to return to after login; invalid values mean `/`.",
+				"schema": {
+					"type": "string",
+					"maxLength": 2048
+				}
+			}],
+			"responses": {
+				"302": {
+					"description": "Redirect to the identity provider, to `return_to` when already\nsigned in, or to `/login?oidc_error=<slug>` when discovery fails.\n",
+					"headers": {
+						"Location": {
+							"description": "The redirect target.",
+							"schema": { "type": "string" }
+						},
+						"Set-Cookie": {
+							"description": "`hangar_oidc_state=<value>; Path=/api/v1/auth/oidc; HttpOnly; SameSite=Lax; Max-Age=600`,\nwith `Secure` added only outside `development`; or an expired value that clears a stale one.\n",
+							"schema": { "type": "string" }
+						}
+					}
+				},
+				"404": { "$ref": "#/components/responses/Problem" },
+				"default": { "$ref": "#/components/responses/Problem" }
+			}
+		} },
+		"/api/v1/auth/oidc/callback": { "get": {
+			"operationId": "completeOidcLogin",
+			"summary": "Complete an OpenID Connect login and create a Session.",
+			"description": "Always answers 302 once OIDC is enabled, never a problem body: success\nredirects to `return_to` or `/` with a `hangar_session` cookie, and\nevery failure redirects to `/login?oidc_error=<slug>` and clears the\nstate cookie. Identity-provider error text is never returned. When\nOIDC is disabled the route answers 404.\n",
+			"security": [],
+			"parameters": [
+				{
+					"name": "code",
+					"in": "query",
+					"required": false,
+					"description": "The authorization code from the identity provider.",
+					"schema": { "type": "string" }
+				},
+				{
+					"name": "state",
+					"in": "query",
+					"required": false,
+					"description": "The state echoed by the identity provider; must match the state cookie.",
+					"schema": { "type": "string" }
+				},
+				{
+					"name": "error",
+					"in": "query",
+					"required": false,
+					"description": "The identity provider's error code, when it declined the request.",
+					"schema": { "type": "string" }
+				}
+			],
+			"responses": {
+				"302": {
+					"description": "Redirect to `return_to` or `/` on success, or to\n`/login?oidc_error=<slug>` on failure.\n",
+					"headers": {
+						"Location": {
+							"description": "The redirect target; never carries identity-provider text.",
+							"schema": { "type": "string" }
+						},
+						"Set-Cookie": {
+							"description": "On success, `hangar_session=<value>` plus an expired\n`hangar_oidc_state`; on failure, only the expired state cookie.\n",
+							"schema": { "type": "string" }
+						}
+					}
+				},
+				"404": { "$ref": "#/components/responses/Problem" },
+				"default": { "$ref": "#/components/responses/Problem" }
+			}
+		} },
+		"/api/v1/logout": { "post": {
+			"operationId": "logout",
+			"summary": "Revoke the current Session and clear its cookie.",
+			"security": [{ "sessionCookie": [] }],
+			"responses": {
+				"204": {
+					"description": "Signed out.",
+					"headers": { "Set-Cookie": {
+						"description": "An expired `hangar_session` cookie that clears the browser value.",
+						"schema": { "type": "string" }
+					} }
+				},
+				"401": { "$ref": "#/components/responses/Problem" },
+				"403": { "$ref": "#/components/responses/Problem" },
+				"default": { "$ref": "#/components/responses/Problem" }
+			}
+		} },
+		"/api/v1/me": {
+			"get": {
+				"operationId": "lookupMe",
+				"summary": "Return the authenticated Principal.",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"responses": {
+					"200": {
+						"description": "The authenticated Principal.",
+						"headers": { "ETag": { "$ref": "#/components/headers/ETag" } },
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			},
+			"patch": {
+				"operationId": "updateMe",
+				"summary": "Update the authenticated Principal's profile.",
+				"description": "Omitted fields are left unchanged and an empty string clears a field.\nCredentials, the username and the platform role are not part of the\nprofile. Agents may change only their display name.\n\n`If-Match` must carry the current strong `ETag` of `GET /me`: a missing\nvalue answers 428 and a stale one 412.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"parameters": [{ "$ref": "#/components/parameters/IfMatch" }],
+				"requestBody": {
+					"required": true,
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileUpdate" } } }
+				},
+				"responses": {
+					"200": {
+						"description": "The updated Principal.",
+						"headers": { "ETag": { "$ref": "#/components/headers/ETag" } },
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"412": { "$ref": "#/components/responses/Problem" },
+					"413": { "$ref": "#/components/responses/Problem" },
+					"428": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/me/password": { "put": {
+			"operationId": "changeMyPassword",
+			"summary": "Replace the authenticated User's password.",
+			"description": "Requires the current password, which shares the login rate limit. A\nsuccessful change revokes every Session of the User, including the\ncurrent one, and leaves Access Tokens valid.\n",
+			"security": [{ "sessionCookie": [] }],
+			"requestBody": {
+				"required": true,
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordChange" } } }
+			},
+			"responses": {
+				"204": {
+					"description": "Password changed and every Session revoked.",
+					"headers": { "Set-Cookie": {
+						"description": "An expired `hangar_session` cookie that clears the browser value.",
+						"schema": { "type": "string" }
+					} }
+				},
+				"400": { "$ref": "#/components/responses/Problem" },
+				"401": { "$ref": "#/components/responses/Problem" },
+				"403": { "$ref": "#/components/responses/Problem" },
+				"413": { "$ref": "#/components/responses/Problem" },
+				"429": { "$ref": "#/components/responses/Problem" },
+				"default": { "$ref": "#/components/responses/Problem" }
+			}
+		} },
+		"/api/v1/me/sessions": {
+			"get": {
+				"operationId": "listMySessions",
+				"summary": "List the authenticated User's active Sessions, newest first.",
+				"description": "Active Sessions are neither revoked nor expired. The list is ordered by\n`created_at` then `id`, both descending. A Session lives 12 hours, so\nthe list is returned whole rather than paginated.\n",
+				"security": [{ "sessionCookie": [] }],
+				"responses": {
+					"200": {
+						"description": "The active Sessions.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionList" } } }
+					},
+					"401": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			},
+			"delete": {
+				"operationId": "revokeMySessions",
+				"summary": "Revoke every active Session of the authenticated User, including the current one.",
+				"security": [{ "sessionCookie": [] }],
+				"responses": {
+					"204": {
+						"description": "Every Session revoked.",
+						"headers": { "Set-Cookie": {
+							"description": "An expired `hangar_session` cookie that clears the browser value.",
+							"schema": { "type": "string" }
+						} }
+					},
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/me/sessions/{id}": { "delete": {
+			"operationId": "revokeMySession",
+			"summary": "Revoke one active Session of the authenticated User.",
+			"description": "Sessions of other Principals, and revoked or expired Sessions, answer\n404. Revoking the current Session also clears its cookie.\n",
+			"security": [{ "sessionCookie": [] }],
+			"parameters": [{
+				"name": "id",
+				"in": "path",
+				"required": true,
+				"schema": {
+					"type": "string",
+					"format": "uuid"
+				}
+			}],
+			"responses": {
+				"204": {
+					"description": "Session revoked.",
+					"headers": { "Set-Cookie": {
+						"description": "Present only when the current Session was revoked: an expired\n`hangar_session` cookie that clears the browser value.\n",
+						"schema": { "type": "string" }
+					} }
+				},
+				"400": { "$ref": "#/components/responses/Problem" },
+				"401": { "$ref": "#/components/responses/Problem" },
+				"403": { "$ref": "#/components/responses/Problem" },
+				"404": { "$ref": "#/components/responses/Problem" },
+				"default": { "$ref": "#/components/responses/Problem" }
+			}
+		} },
+		"/api/v1/me/tokens": {
+			"get": {
+				"operationId": "listMyAccessTokens",
+				"summary": "List the authenticated Principal's unrevoked Access Tokens.",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"responses": {
+					"200": { "$ref": "#/components/responses/AccessTokenList" },
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			},
+			"post": {
+				"operationId": "createMyAccessToken",
+				"summary": "Create an Access Token for the authenticated Principal.",
+				"description": "A replay under `Idempotency-Key` answers 200 without the token value.",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
+				"requestBody": { "$ref": "#/components/requestBodies/CreateAccessToken" },
+				"responses": {
+					"200": { "$ref": "#/components/responses/ReplayedAccessToken" },
+					"201": { "$ref": "#/components/responses/CreatedAccessToken" },
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"409": { "$ref": "#/components/responses/Problem" },
+					"413": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/me/tokens/{token_id}": { "delete": {
+			"operationId": "revokeMyAccessToken",
+			"summary": "Revoke one of the authenticated Principal's Access Tokens.",
+			"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+			"parameters": [{ "$ref": "#/components/parameters/TokenID" }],
+			"responses": {
+				"204": { "description": "Revoked. The token stops authenticating immediately." },
+				"400": { "$ref": "#/components/responses/Problem" },
+				"401": { "$ref": "#/components/responses/Problem" },
+				"403": { "$ref": "#/components/responses/Problem" },
+				"404": { "$ref": "#/components/responses/Problem" },
+				"default": { "$ref": "#/components/responses/Problem" }
+			}
+		} },
+		"/api/v1/principals/{principal_id}/tokens": {
+			"parameters": [{ "$ref": "#/components/parameters/PrincipalID" }],
+			"get": {
+				"operationId": "listPrincipalAccessTokens",
+				"summary": "List a Principal's unrevoked Access Tokens.",
+				"description": "Allowed for the Principal itself, and for a Platform Admin when the Principal is an Agent.",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"responses": {
+					"200": { "$ref": "#/components/responses/AccessTokenList" },
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			},
+			"post": {
+				"operationId": "createPrincipalAccessToken",
+				"summary": "Create an Access Token for a Principal.",
+				"description": "Allowed for the Principal itself, and for a Platform Admin when the\nPrincipal is an Agent. A replay under `Idempotency-Key` answers 200\nwithout the token value.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
+				"requestBody": { "$ref": "#/components/requestBodies/CreateAccessToken" },
+				"responses": {
+					"200": { "$ref": "#/components/responses/ReplayedAccessToken" },
+					"201": { "$ref": "#/components/responses/CreatedAccessToken" },
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"409": { "$ref": "#/components/responses/Problem" },
+					"413": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/principals/{principal_id}/tokens/{token_id}": {
+			"parameters": [{ "$ref": "#/components/parameters/PrincipalID" }, { "$ref": "#/components/parameters/TokenID" }],
+			"delete": {
+				"operationId": "revokePrincipalAccessToken",
+				"summary": "Revoke one of a Principal's Access Tokens.",
+				"description": "Allowed for the Principal itself, and for a Platform Admin when the Principal is an Agent.",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"responses": {
+					"204": { "description": "Revoked. The token stops authenticating immediately." },
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/principals": {
+			"get": {
+				"operationId": "listPrincipals",
+				"summary": "List the Platform's Principals, newest first.",
+				"description": "Only a Platform Admin may list Principals; every other authenticated\ncaller answers 403. Deleted Principals never appear; disabled\nPrincipals do, with `disabled_at` set, so the Platform Admin can\ninspect them before enabling them. Filters combine with AND. The list\nis ordered by `created_at` then `id`, both descending, and paged by\ncursor without a total.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"parameters": [
+					{
+						"name": "kind",
+						"in": "query",
+						"schema": {
+							"type": "string",
+							"enum": ["user", "agent"]
+						}
+					},
+					{
+						"name": "q",
+						"in": "query",
+						"description": "Case-insensitive text found in the username or the display name. Empty means no filter.",
+						"schema": {
+							"type": "string",
+							"maxLength": 200
+						}
+					},
+					{
+						"name": "status",
+						"in": "query",
+						"schema": {
+							"type": "string",
+							"enum": ["enabled", "disabled"]
+						}
+					},
+					{ "$ref": "#/components/parameters/Cursor" },
+					{ "$ref": "#/components/parameters/Limit" }
+				],
+				"responses": {
+					"200": {
+						"description": "One page of Principals.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrincipalList" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			},
+			"post": {
+				"operationId": "createPrincipal",
+				"summary": "Create a User or an Agent together with its Namespace.",
+				"description": "Only a Platform Admin may create Principals. A User is created with\nits password credential; an Agent has neither a password nor a\nplatform role and authenticates with Access Tokens. A username held\nby a live Namespace, including `system`, returns 409.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"requestBody": {
+					"required": true,
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrincipalRequest" } } }
+				},
+				"responses": {
+					"201": {
+						"description": "The created Principal.",
+						"headers": { "Location": {
+							"description": "`/api/v1/principals/{id}`",
+							"schema": { "type": "string" }
+						} },
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"409": { "$ref": "#/components/responses/Problem" },
+					"413": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/principals/{principal_id}": {
+			"parameters": [{ "$ref": "#/components/parameters/PrincipalID" }],
+			"get": {
+				"operationId": "lookupPrincipal",
+				"summary": "Return one Principal.",
+				"description": "Only a Platform Admin may look up Principals; every other authenticated\ncaller answers 403. Disabled Principals stay readable so the Platform\nAdmin can inspect them before enabling them. A deleted Principal\nanswers 404. The caller keeps using `/me` for its own profile.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"responses": {
+					"200": {
+						"description": "The Principal.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			},
+			"delete": {
+				"operationId": "deletePrincipal",
+				"summary": "Irreversibly delete a Principal.",
+				"description": "Only a Platform Admin may delete Principals. Deletion revokes every\nSession and Access Token, releases the username and makes the\nPrincipal's Capabilities unavailable; nothing can restore it. Deleting\nthe last effective Platform Admin returns 409.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"responses": {
+					"204": { "description": "Deleted." },
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"409": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/principals/{principal_id}/disable": {
+			"parameters": [{ "$ref": "#/components/parameters/PrincipalID" }],
+			"post": {
+				"operationId": "disablePrincipal",
+				"summary": "Disable a Principal and revoke its credentials.",
+				"description": "Only a Platform Admin may disable Principals. Every Session and Access\nToken of the Principal is revoked and authentication is refused until\nit is enabled again. Disabling a disabled Principal changes nothing.\nDisabling the last effective Platform Admin returns 409.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"responses": {
+					"204": { "description": "Disabled." },
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"409": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/principals/{principal_id}/enable": {
+			"parameters": [{ "$ref": "#/components/parameters/PrincipalID" }],
+			"post": {
+				"operationId": "enablePrincipal",
+				"summary": "Enable a disabled Principal.",
+				"description": "Only a Platform Admin may enable Principals. Credentials revoked by\ndisabling stay revoked: the Principal signs in or is issued a token\nagain. Enabling an enabled Principal changes nothing.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"responses": {
+					"204": { "description": "Enabled." },
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/principals/{principal_id}/password": {
+			"parameters": [{ "$ref": "#/components/parameters/PrincipalID" }],
+			"put": {
+				"operationId": "resetPrincipalPassword",
+				"summary": "Reset a User's password.",
+				"description": "Only a Platform Admin may reset passwords, and only Users have one. The\nreset revokes every Session of the User and leaves Access Tokens\nvalid.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"requestBody": {
+					"required": true,
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordReset" } } }
+				},
+				"responses": {
+					"204": { "description": "Password reset and every Session of the User revoked." },
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"413": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/principals/{principal_id}/role": {
+			"parameters": [{ "$ref": "#/components/parameters/PrincipalID" }],
+			"put": {
+				"operationId": "updatePrincipalRole",
+				"summary": "Set a User's platform role.",
+				"description": "Only a Platform Admin may change platform roles, and only Users have\none. Demoting the last effective Platform Admin returns 409.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"requestBody": {
+					"required": true,
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleUpdate" } } }
+				},
+				"responses": {
+					"204": { "description": "Role set." },
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"409": { "$ref": "#/components/responses/Problem" },
+					"413": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/capabilities": {
+			"get": {
+				"operationId": "listCapabilities",
+				"summary": "List the Capabilities the caller can read, newest first.",
+				"description": "Reads follow the rules of `lookupCapability`. Filters combine with\nAND. The list is ordered by `created_at` then `id`, both descending,\nand paged by cursor without a total.\n",
+				"security": [
+					{},
+					{ "sessionCookie": [] },
+					{ "bearerToken": [] }
+				],
+				"parameters": [
+					{
+						"name": "kind",
+						"in": "query",
+						"schema": {
+							"type": "string",
+							"enum": ["skill", "mcp"]
+						}
+					},
+					{
+						"name": "namespace",
+						"in": "query",
+						"description": "The name of the owning Namespace.",
+						"schema": { "$ref": "#/components/schemas/Name" }
+					},
+					{
+						"name": "visibility",
+						"in": "query",
+						"schema": { "$ref": "#/components/schemas/Visibility" }
+					},
+					{
+						"name": "q",
+						"in": "query",
+						"description": "Case-insensitive text found in the name or the description. Empty means no filter.",
+						"schema": {
+							"type": "string",
+							"maxLength": 200
+						}
+					},
+					{
+						"name": "tag",
+						"in": "query",
+						"description": "One or more normalized tags separated by commas. A Capability\nmatches when at least one of the tags is in its set; tag matches\ncombine with every other filter using AND. Tags cannot contain\ncommas, so the separator is unambiguous.\n",
+						"schema": {
+							"type": "string",
+							"maxLength": 263
+						}
+					},
+					{ "$ref": "#/components/parameters/Cursor" },
+					{ "$ref": "#/components/parameters/Limit" }
+				],
+				"responses": {
+					"200": {
+						"description": "One page of Capabilities.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityList" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			},
+			"post": {
+				"operationId": "createCapability",
+				"summary": "Create a Capability together with its first Version.",
+				"description": "An `application/json` body creates an MCP Capability; a\n`multipart/form-data` body creates a Skill Capability from its\nCapability Package. The Capability, its first Version and the Audit\nEvent are committed in one transaction. A rejected package returns 400\nwith a `detail` that names what to fix. The caller must manage the\ntarget Namespace: a Platform Admin for system, a member User of the Team for a Team Namespace, and\nthe owner for a principal Namespace. A live Capability with the same\nkind and name in the Namespace returns 409.\n",
+				"security": [{ "sessionCookie": [] }],
+				"parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": { "schema": { "$ref": "#/components/schemas/CreateMCPCapabilityRequest" } },
+						"multipart/form-data": {
+							"schema": { "$ref": "#/components/schemas/CreateSkillCapabilityRequest" },
+							"encoding": { "package": { "contentType": "application/zip" } }
+						}
+					}
+				},
+				"responses": {
+					"201": {
+						"description": "The created Capability.",
+						"headers": { "Location": {
+							"description": "`/api/v1/capabilities/{id}`",
+							"schema": { "type": "string" }
+						} },
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capability" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"409": { "$ref": "#/components/responses/Problem" },
+					"413": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/capabilities/{capability_id}": {
+			"parameters": [{ "$ref": "#/components/parameters/CapabilityID" }],
+			"get": {
+				"operationId": "lookupCapability",
+				"summary": "Return a Capability the caller can read.",
+				"description": "Anonymous callers read public Capabilities, authenticated Principals\nalso read internal ones, and the managers of the owning Namespace and\nPlatform Admins also read private ones. A Capability that is deleted,\nunavailable, owned by a disabled Team or Principal, or not readable by\nthe caller answers 404.\n\nThe `ETag` header covers management metadata only: it excludes\n`download_count` and any caller-relative field, so a download never\ninvalidates an editor's `If-Match`.\n",
+				"security": [
+					{},
+					{ "sessionCookie": [] },
+					{ "bearerToken": [] }
+				],
+				"responses": {
+					"200": {
+						"description": "The Capability.",
+						"headers": { "ETag": { "$ref": "#/components/headers/ETag" } },
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capability" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			},
+			"patch": {
+				"operationId": "updateCapability",
+				"summary": "Change a Capability's description or visibility.",
+				"description": "Omitted fields are left unchanged. The change applies to every Version\nat once and publishes none. `kind`, `namespace` and `name` are\nimmutable, so sending any of them returns 400.\n\nThe caller must manage the Capability's Namespace, under the same\nrules as `createCapability`. A deleted or unavailable Capability, one\nin an unusable Namespace, and a private one the caller does not manage\nreturn 404; those checks come before the precondition. `If-Match`\nmust then carry the current strong `ETag` of `lookupCapability`: a\nmissing value answers 428 and a stale one 412. That `ETag` covers\nmanagement metadata only, excluding `download_count` and\ncaller-relative fields, so downloads do not cause spurious 412s.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"parameters": [{ "$ref": "#/components/parameters/IfMatch" }],
+				"requestBody": {
+					"required": true,
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityUpdate" } } }
+				},
+				"responses": {
+					"200": {
+						"description": "The updated Capability.",
+						"headers": { "ETag": { "$ref": "#/components/headers/ETag" } },
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capability" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"412": { "$ref": "#/components/responses/Problem" },
+					"413": { "$ref": "#/components/responses/Problem" },
+					"428": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			},
+			"delete": {
+				"operationId": "deleteCapability",
+				"summary": "Soft-delete a Capability.",
+				"description": "The Capability and all its Versions and Content disappear from every\nbusiness API, for Platform Admins too, and its Path becomes free for a\nnew, unrelated Capability. Deletion cannot be undone through the API.\nThe caller must manage the Capability's Namespace; the lifecycle and\nvisibility rules of `updateCapability` decide between 403 and 404.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"responses": {
+					"204": { "description": "The Capability is deleted." },
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/capabilities/{capability_id}/versions": {
+			"parameters": [{ "$ref": "#/components/parameters/CapabilityID" }],
+			"get": {
+				"operationId": "listCapabilityVersions",
+				"summary": "List a readable Capability's Versions, newest first.",
+				"description": "Versions follow the visibility and lifecycle of their Capability: one\nthe caller cannot look up answers 404. The list is ordered by\n`created_at` then `id`, both descending, and paged by cursor without a\ntotal. READMEs are left to `lookupCapabilityVersion`.\n",
+				"security": [
+					{},
+					{ "sessionCookie": [] },
+					{ "bearerToken": [] }
+				],
+				"parameters": [{ "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }],
+				"responses": {
+					"200": {
+						"description": "One page of Versions.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionList" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			},
+			"post": {
+				"operationId": "publishCapabilityVersion",
+				"summary": "Publish a new Version of a Capability and make it current.",
+				"description": "The media type must match the Capability's kind: `application/json`\nfor MCP and `multipart/form-data` for Skill; the other one returns\n400. The Version, the new current version and the Audit Event are\ncommitted in one transaction, and concurrent publishes each receive\ntheir own CalVer. The caller must manage the Capability's Namespace,\nunder the same rules as `createCapability`. A deleted or unavailable\nCapability, one in an unusable Namespace, and a private one the\ncaller does not manage return 404.\n",
+				"security": [{ "sessionCookie": [] }],
+				"parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": { "schema": { "$ref": "#/components/schemas/PublishMCPVersionRequest" } },
+						"multipart/form-data": {
+							"schema": { "$ref": "#/components/schemas/PublishSkillVersionRequest" },
+							"encoding": { "package": { "contentType": "application/zip" } }
+						}
+					}
+				},
+				"responses": {
+					"201": {
+						"description": "The Capability with its new current version.",
+						"headers": { "Location": {
+							"description": "`/api/v1/capabilities/{capability_id}/versions/{version}`",
+							"schema": { "type": "string" }
+						} },
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capability" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"409": { "$ref": "#/components/responses/Problem" },
+					"413": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/capabilities/{capability_id}/versions/{version}": {
+			"parameters": [{ "$ref": "#/components/parameters/CapabilityID" }, {
+				"name": "version",
+				"in": "path",
+				"required": true,
+				"schema": { "$ref": "#/components/schemas/CalVer" }
+			}],
+			"get": {
+				"operationId": "lookupCapabilityVersion",
+				"summary": "Return one Version of a readable Capability by its CalVer.",
+				"description": "A Capability the caller cannot look up, or a CalVer it never\npublished, answers 404.\n",
+				"security": [
+					{},
+					{ "sessionCookie": [] },
+					{ "bearerToken": [] }
+				],
+				"responses": {
+					"200": {
+						"description": "The Version.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/capabilities/{capability_id}/versions/{version}/content": { "get": {
+			"operationId": "lookupCapabilityContent",
+			"summary": "Return the Content of one Version of a Capability.",
+			"description": "An MCP Version's Content is its config in the RFC 8785 canonical form,\nexcept that integers keep their original digits, so values beyond\n±2^53 are not rounded. A Skill Version's Content is its package, the\nuploaded ZIP byte for byte, as `application/zip`. The strong `ETag` is\nthe quoted hex sha256 of the returned bytes. Range requests are not\nsupported; a `Range` header is ignored. A Skill package missing from\nstorage fails with 500 before any content is sent.\n\nAnonymous callers read public Capabilities, authenticated Principals\nalso internal ones, and private ones are read by the managers of the\nowning Namespace. A Capability the caller cannot read, a deleted or\nunavailable Capability, or one whose Namespace, Team or Principal is\ndisabled or deleted answers 404. These checks run before `If-None-Match`.\n",
+			"security": [
+				{},
+				{ "sessionCookie": [] },
+				{ "bearerToken": [] }
+			],
+			"parameters": [
+				{ "$ref": "#/components/parameters/CapabilityID" },
+				{
+					"name": "version",
+					"in": "path",
+					"required": true,
+					"schema": { "$ref": "#/components/schemas/CalVer" }
+				},
+				{
+					"name": "If-None-Match",
+					"in": "header",
+					"description": "Entity tags the caller holds. A match, or `*`, answers 304.",
+					"required": false,
+					"schema": { "type": "string" }
+				}
+			],
+			"responses": {
+				"200": {
+					"description": "The Content.",
+					"headers": {
+						"ETag": { "$ref": "#/components/headers/ETag" },
+						"Cache-Control": { "$ref": "#/components/headers/ContentCacheControl" }
+					},
+					"content": {
+						"application/json": { "schema": { "$ref": "#/components/schemas/MCPConfig" } },
+						"application/zip": { "schema": { "type": "string" } }
+					}
+				},
+				"304": {
+					"description": "The caller's copy is current. No body.",
+					"headers": { "ETag": { "$ref": "#/components/headers/ETag" } }
+				},
+				"400": { "$ref": "#/components/responses/Problem" },
+				"401": { "$ref": "#/components/responses/Problem" },
+				"404": { "$ref": "#/components/responses/Problem" },
+				"default": { "$ref": "#/components/responses/Problem" }
+			}
+		} },
+		"/api/v1/tags": { "get": {
+			"operationId": "listTags",
+			"summary": "List the tags of the Capabilities the caller can read, with counts.",
+			"description": "Counts only the live Capabilities the caller may read, under the same\nvisibility rules as `lookupCapability`; an anonymous caller counts\npublic Capabilities only. Tags are normalized, then ordered by count\ndescending and name ascending. The response is not paginated: tag\ncounts change with edits, so `truncated` reports that more tags exist\nthan `limit` instead of offering a cursor.\n",
+			"security": [
+				{},
+				{ "sessionCookie": [] },
+				{ "bearerToken": [] }
+			],
+			"parameters": [{
+				"name": "q",
+				"in": "query",
+				"description": "Case-insensitive text found in the tag name. Empty means no filter.",
+				"schema": {
+					"type": "string",
+					"maxLength": 200
+				}
+			}, {
+				"name": "limit",
+				"in": "query",
+				"description": "The most tags the response holds.",
+				"schema": {
+					"type": "integer",
+					"minimum": 1,
+					"maximum": 200,
+					"default": 100
+				}
+			}],
+			"responses": {
+				"200": {
+					"description": "The readable tags and their counts.",
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagList" } } }
+				},
+				"400": { "$ref": "#/components/responses/Problem" },
+				"default": { "$ref": "#/components/responses/Problem" }
+			}
+		} },
+		"/api/v1/audit-events": { "get": {
+			"operationId": "listAuditEvents",
+			"summary": "List the Platform's Audit Events, newest first.",
+			"description": "Only a Platform Admin may read Audit Events; anonymous callers answer\n401 and every other authenticated caller 403. Filters combine with\nAND. `from` is inclusive and `to` is exclusive, both RFC 3339; a\n`from` later than `to` answers 400. An event whose `actor` is null is\na system event, and a deleted actor's username and display name are\nstill returned, so historical facts keep their attribution. Reading\nAudit Events writes no Audit Event. The list is ordered by\n`created_at` then `id`, both descending, and paged by cursor without\na total.\n",
+			"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+			"parameters": [
+				{
+					"name": "actor_principal_id",
+					"in": "query",
+					"schema": {
+						"type": "string",
+						"format": "uuid"
+					}
+				},
+				{
+					"name": "action",
+					"in": "query",
+					"description": "One action from the controlled vocabulary.",
+					"schema": {
+						"type": "string",
+						"enum": [
+							"access_token.created",
+							"access_token.revoked",
+							"capability.created",
+							"capability.updated",
+							"capability.deleted",
+							"capability.version_published",
+							"principal.created",
+							"principal.disabled",
+							"principal.enabled",
+							"principal.deleted",
+							"principal.profile_updated",
+							"principal.password_changed",
+							"principal.password_reset",
+							"principal.role_changed",
+							"oidc.identity_linked",
+							"oidc.profile_synced",
+							"session.revoked",
+							"team.created",
+							"team.disabled",
+							"team.enabled",
+							"team.deleted",
+							"team.member_added",
+							"team.member_role_changed",
+							"team.member_removed"
+						]
+					}
+				},
+				{
+					"name": "resource_type",
+					"in": "query",
+					"schema": {
+						"type": "string",
+						"enum": [
+							"access_token",
+							"capability",
+							"principal",
+							"session",
+							"team"
+						]
+					}
+				},
+				{
+					"name": "resource_id",
+					"in": "query",
+					"schema": {
+						"type": "string",
+						"format": "uuid"
+					}
+				},
+				{
+					"name": "from",
+					"in": "query",
+					"description": "The inclusive start of the time range, as RFC 3339.",
+					"schema": {
+						"type": "string",
+						"format": "date-time"
+					}
+				},
+				{
+					"name": "to",
+					"in": "query",
+					"description": "The exclusive end of the time range, as RFC 3339.",
+					"schema": {
+						"type": "string",
+						"format": "date-time"
+					}
+				},
+				{ "$ref": "#/components/parameters/Cursor" },
+				{ "$ref": "#/components/parameters/Limit" }
+			],
+			"responses": {
+				"200": {
+					"description": "One page of Audit Events.",
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventList" } } }
+				},
+				"400": { "$ref": "#/components/responses/Problem" },
+				"401": { "$ref": "#/components/responses/Problem" },
+				"403": { "$ref": "#/components/responses/Problem" },
+				"default": { "$ref": "#/components/responses/Problem" }
+			}
+		} },
+		"/api/v1/namespaces": { "get": {
+			"operationId": "listNamespaces",
+			"summary": "List the Namespaces the caller can create Capabilities in, newest first.",
+			"description": "A Platform Admin uses every Namespace; other Users use their own and\nthose of their Teams; Agents use only their own. Deleted Namespaces and\nthose of disabled Teams or Principals are never listed. The list is\nordered by `created_at` then `id`, both descending, and paged by cursor\nwithout a total.\n",
+			"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+			"parameters": [{ "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }],
+			"responses": {
+				"200": {
+					"description": "One page of Namespaces.",
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/NamespaceList" } } }
+				},
+				"400": { "$ref": "#/components/responses/Problem" },
+				"401": { "$ref": "#/components/responses/Problem" },
+				"default": { "$ref": "#/components/responses/Problem" }
+			}
+		} },
+		"/api/v1/teams": {
+			"get": {
+				"operationId": "listTeams",
+				"summary": "List the live Teams the caller may see, newest first.",
+				"description": "A Platform Admin sees every live Team; every other Principal sees only\nthe Teams it is a member of, including as an Agent. Disabled Teams stay\nvisible; deleted Teams never appear. `q` matches the Team's name or\ndisplay name case-insensitively, and `status` narrows the list to\nenabled or disabled Teams. The list is ordered by `created_at` then\n`id`, both descending, and paged by cursor without a total.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"parameters": [
+					{
+						"name": "q",
+						"in": "query",
+						"description": "A case-insensitive substring of the name or display name. Empty does not filter.",
+						"schema": {
+							"type": "string",
+							"maxLength": 200
+						}
+					},
+					{
+						"name": "status",
+						"in": "query",
+						"description": "Only Teams in this lifecycle state; omit for both.",
+						"schema": {
+							"type": "string",
+							"enum": ["enabled", "disabled"]
+						}
+					},
+					{ "$ref": "#/components/parameters/Cursor" },
+					{ "$ref": "#/components/parameters/Limit" }
+				],
+				"responses": {
+					"200": {
+						"description": "One page of Teams.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamList" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			},
+			"post": {
+				"operationId": "createTeam",
+				"summary": "Create a Team with its Namespace and first Team Admins.",
+				"description": "Only a Platform Admin may create a Team. The Team, its Namespace and\nthe admin memberships are committed in one transaction. Every listed\nadmin must be an enabled User: an unknown or deleted Principal answers\n404, an Agent 400 and a disabled User 409. A Namespace name already\nheld by a live Namespace, or `system`, answers 409.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"requestBody": {
+					"required": true,
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamRequest" } } }
+				},
+				"responses": {
+					"201": {
+						"description": "The created Team.",
+						"headers": { "Location": {
+							"description": "`/api/v1/teams/{id}`",
+							"schema": { "type": "string" }
+						} },
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"409": { "$ref": "#/components/responses/Problem" },
+					"413": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/teams/{team_id}": {
+			"parameters": [{ "$ref": "#/components/parameters/TeamID" }],
+			"get": {
+				"operationId": "lookupTeam",
+				"summary": "Read a live Team the caller may see.",
+				"description": "A Platform Admin may read any live Team; every other Principal only a\nTeam it is a member of. A disabled Team remains readable. A deleted\nTeam, or one the caller cannot see, answers 404 without revealing\nwhether it exists.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"responses": {
+					"200": {
+						"description": "The Team.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			},
+			"delete": {
+				"operationId": "deleteTeam",
+				"summary": "Delete a Team irreversibly.",
+				"description": "Allowed for an effective Team Admin of an enabled Team and for a\nPlatform Admin; a Team Admin of a disabled Team answers 409. The Team\nand its Namespace are soft-deleted, the Namespace name is released and\nthe Team's Capabilities become unavailable. A deleted Team answers 404\neverywhere.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"responses": {
+					"204": { "description": "The Team is deleted." },
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"409": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/teams/{team_id}/members": {
+			"parameters": [{ "$ref": "#/components/parameters/TeamID" }],
+			"get": {
+				"operationId": "listTeamMembers",
+				"summary": "List a Team's roster, newest membership first.",
+				"description": "Allowed for any member of the Team — a User or an Agent, a Team Admin\nor a member — and for any Platform Admin. A caller that is not a member\nanswers 404 without revealing whether the Team exists, as does a\ndeleted Team. A disabled Team stays readable: disabling freezes writes,\nnot reads. Deleted Principals are excluded; disabled Principals stay\nlisted with `disabled_at`. `role` narrows the roster. The list is\nordered by the membership's `created_at` then `principal_id`, both\ndescending, and paged by cursor without a total.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"parameters": [
+					{
+						"name": "role",
+						"in": "query",
+						"description": "Only memberships with this Team role; omit for both.",
+						"schema": {
+							"type": "string",
+							"enum": ["admin", "member"]
+						}
+					},
+					{ "$ref": "#/components/parameters/Cursor" },
+					{ "$ref": "#/components/parameters/Limit" }
+				],
+				"responses": {
+					"200": {
+						"description": "One page of Team members.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMemberList" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/teams/{team_id}/member-candidates": {
+			"parameters": [{ "$ref": "#/components/parameters/TeamID" }],
+			"get": {
+				"operationId": "listTeamMemberCandidates",
+				"summary": "Search for Principals that could join a Team.",
+				"description": "Allowed for an effective Team Admin and for a Platform Admin. A caller\nthat is not a member answers 404 without revealing whether the Team\nexists, as does a deleted Team; a member that is not an effective Team\nAdmin answers 403. `q` is required and must be 2–200 characters after\ntrimming; it matches the username or the display name\ncase-insensitively. This is a deliberate limit on the directory a Team\nAdmin may enumerate. Deleted Principals and existing members are\nexcluded; disabled Principals stay candidates. The list is ordered by\nthe Principal's `created_at` then `id`, both descending, and paged by\ncursor without a total.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"parameters": [
+					{
+						"name": "q",
+						"in": "query",
+						"required": true,
+						"description": "A case-insensitive substring of the username or display name; 2–200 characters after trimming.",
+						"schema": {
+							"type": "string",
+							"minLength": 2,
+							"maxLength": 200
+						}
+					},
+					{ "$ref": "#/components/parameters/Cursor" },
+					{ "$ref": "#/components/parameters/Limit" }
+				],
+				"responses": {
+					"200": {
+						"description": "One page of candidates.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMemberCandidateList" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/teams/{team_id}/disable": {
+			"parameters": [{ "$ref": "#/components/parameters/TeamID" }],
+			"post": {
+				"operationId": "disableTeam",
+				"summary": "Disable a Team.",
+				"description": "Allowed for an effective Team Admin and for a Platform Admin.\nDisabling freezes membership and the Team's Capabilities until the\nTeam is enabled again. Disabling a disabled Team changes nothing.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"responses": {
+					"204": { "description": "The Team is disabled." },
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/teams/{team_id}/enable": {
+			"parameters": [{ "$ref": "#/components/parameters/TeamID" }],
+			"post": {
+				"operationId": "enableTeam",
+				"summary": "Enable a disabled Team.",
+				"description": "Allowed for an effective Team Admin and for a Platform Admin. The Team\nmust have an effective Team Admin, or the request answers 409. Enabling\nrestores the original memberships and the Team's undeleted\nCapabilities. Enabling an enabled Team changes nothing.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"responses": {
+					"204": { "description": "The Team is enabled." },
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"409": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		},
+		"/api/v1/teams/{team_id}/members/{principal_id}": {
+			"parameters": [{ "$ref": "#/components/parameters/TeamID" }, { "$ref": "#/components/parameters/PrincipalID" }],
+			"put": {
+				"operationId": "putTeamMember",
+				"summary": "Add a Principal to a Team or change its Team role.",
+				"description": "Allowed for an effective Team Admin of an enabled Team and for a\nPlatform Admin, who may also change a disabled Team so it has an\neffective Team Admin before it is enabled again. Only a User can be a\nTeam Admin; an Agent may be a member. Demoting the last effective Team\nAdmin of an enabled Team answers 409, and so does any change by a Team\nAdmin while the Team is disabled. An unknown or deleted Team or\nPrincipal answers 404.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"requestBody": {
+					"required": true,
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMemberRole" } } }
+				},
+				"responses": {
+					"200": {
+						"description": "The role was set on an existing membership.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } }
+					},
+					"201": {
+						"description": "The Principal was added to the Team.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } }
+					},
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"409": { "$ref": "#/components/responses/Problem" },
+					"413": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			},
+			"delete": {
+				"operationId": "removeTeamMember",
+				"summary": "Remove a Principal from a Team.",
+				"description": "Allowed for the same callers as `putTeamMember`. Removing the last\neffective Team Admin of an enabled Team answers 409, and so does any\nremoval by a Team Admin while the Team is disabled. A Principal that\nis not a member answers 404.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"responses": {
+					"204": { "description": "The Principal is no longer a member." },
+					"400": { "$ref": "#/components/responses/Problem" },
+					"401": { "$ref": "#/components/responses/Problem" },
+					"403": { "$ref": "#/components/responses/Problem" },
+					"404": { "$ref": "#/components/responses/Problem" },
+					"409": { "$ref": "#/components/responses/Problem" },
+					"default": { "$ref": "#/components/responses/Problem" }
+				}
+			}
+		}
+	},
+	components: {
+		"parameters": {
+			"CapabilityID": {
+				"name": "capability_id",
+				"in": "path",
+				"required": true,
+				"schema": {
+					"type": "string",
+					"format": "uuid"
+				}
+			},
+			"IdempotencyKey": {
+				"name": "Idempotency-Key",
+				"in": "header",
+				"description": "Optional client key, 1–255 visible ASCII characters, that makes a\nretried create safe. For 24 hours, a request from the same Principal\nto the same operation with the same key and the same request replays\nthe first successful response's safe metadata instead of creating\nagain; the same key with a different request answers 409, and so does\na retry while the first request is still in progress\n(`/problems/in-progress`, retryable). Failed requests are not\nrecorded.\n",
+				"required": false,
+				"schema": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 255,
+					"pattern": "^[!-~]+$"
+				}
+			},
+			"Cursor": {
+				"name": "cursor",
+				"in": "query",
+				"description": "The `next_cursor` of the previous page; omit it for the first page. A\ncursor is opaque and stays valid while the list changes: items created\nlater never appear on following pages and none is skipped or repeated.\n",
+				"schema": {
+					"type": "string",
+					"maxLength": 512
+				}
+			},
+			"Limit": {
+				"name": "limit",
+				"in": "query",
+				"description": "The most items a page holds.",
+				"schema": {
+					"type": "integer",
+					"minimum": 1,
+					"maximum": 100,
+					"default": 20
+				}
+			},
+			"IfMatch": {
+				"name": "If-Match",
+				"in": "header",
+				"description": "The current strong `ETag` of the resource. Not required by the schema because a missing value answers 428, not 400.",
+				"required": false,
+				"schema": { "type": "string" }
+			},
+			"PrincipalID": {
+				"name": "principal_id",
+				"in": "path",
+				"required": true,
+				"schema": {
+					"type": "string",
+					"format": "uuid"
+				}
+			},
+			"TeamID": {
+				"name": "team_id",
+				"in": "path",
+				"required": true,
+				"schema": {
+					"type": "string",
+					"format": "uuid"
+				}
+			},
+			"TokenID": {
+				"name": "token_id",
+				"in": "path",
+				"required": true,
+				"schema": {
+					"type": "string",
+					"format": "uuid"
+				}
+			}
+		},
+		"requestBodies": { "CreateAccessToken": {
+			"required": true,
+			"content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessTokenRequest" } } }
+		} },
+		"headers": {
+			"ETag": {
+				"description": "A strong entity tag of the resource's management metadata: the fields\nthat describe how the resource is governed, such as a Capability's\ntags, excluding mutable counters like a Capability's `download_count`\nand any caller-relative field. A download therefore never invalidates\nan editor's `If-Match`, and every caller sees the same tag.\n",
+				"required": true,
+				"schema": { "type": "string" }
+			},
+			"ContentCacheControl": {
+				"description": "`private, no-store` when the Content is not public to anonymous\nreaders; absent for public Content.\n",
+				"required": false,
+				"schema": { "type": "string" }
+			}
+		},
+		"responses": {
+			"Problem": {
+				"description": "An RFC 9457 problem detail.",
+				"content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }
+			},
+			"AccessTokenList": {
+				"description": "Unrevoked Access Tokens, newest first. Token values are never listed.",
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessTokenList" } } }
+			},
+			"CreatedAccessToken": {
+				"description": "The created Access Token. `token` is the only time the full value is returned.",
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedAccessToken" } } }
+			},
+			"ReplayedAccessToken": {
+				"description": "A replayed creation under `Idempotency-Key`: the first created Access Token's metadata, never its value.",
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayedAccessToken" } } }
+			}
+		},
+		"schemas": {
+			"CreateAccessTokenRequest": {
+				"type": "object",
+				"required": ["name"],
+				"properties": { "name": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 64
+				} },
+				"additionalProperties": false
+			},
+			"AccessToken": {
+				"type": "object",
+				"required": [
+					"id",
+					"name",
+					"token_prefix",
+					"created_at",
+					"last_used_at"
+				],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"name": { "type": "string" },
+					"token_prefix": {
+						"type": "string",
+						"description": "The first 8 characters after `hng_`, for recognising a token. Not a credential."
+					},
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"last_used_at": {
+						"type": ["string", "null"],
+						"format": "date-time",
+						"description": "Recorded at most once every 5 minutes; null until first use."
+					}
+				}
+			},
+			"AccessTokenList": {
+				"type": "object",
+				"required": ["items"],
+				"properties": { "items": {
+					"type": "array",
+					"items": { "$ref": "#/components/schemas/AccessToken" }
+				} }
+			},
+			"CreatedAccessToken": {
+				"type": "object",
+				"required": [
+					"id",
+					"name",
+					"token_prefix",
+					"token",
+					"created_at"
+				],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"name": { "type": "string" },
+					"token_prefix": { "type": "string" },
+					"token": {
+						"type": "string",
+						"description": "The full `hng_<value>` token. Use it as `Authorization: Bearer <token>`."
+					},
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					}
+				}
+			},
+			"ReplayedAccessToken": {
+				"type": "object",
+				"required": [
+					"id",
+					"name",
+					"token_prefix",
+					"created_at"
+				],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"name": { "type": "string" },
+					"token_prefix": { "type": "string" },
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					}
+				}
+			},
+			"AuthMethods": {
+				"type": "object",
+				"required": ["password", "oidc"],
+				"properties": {
+					"password": {
+						"type": "object",
+						"required": ["enabled"],
+						"properties": { "enabled": {
+							"type": "boolean",
+							"description": "Always true; the password method has no switch."
+						} }
+					},
+					"oidc": {
+						"type": "object",
+						"required": ["enabled", "display_name"],
+						"properties": {
+							"enabled": { "type": "boolean" },
+							"display_name": {
+								"type": ["string", "null"],
+								"description": "The identity provider's issuer host, or null when OIDC is disabled."
+							}
+						}
+					}
+				}
+			},
+			"LoginRequest": {
+				"type": "object",
+				"required": ["username", "password"],
+				"properties": {
+					"username": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 64
+					},
+					"password": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 1024
+					}
+				},
+				"additionalProperties": false
+			},
+			"Principal": {
+				"type": "object",
+				"required": [
+					"id",
+					"kind",
+					"username",
+					"display_name",
+					"disabled_at",
+					"created_at",
+					"has_password"
+				],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"kind": {
+						"type": "string",
+						"enum": ["user", "agent"]
+					},
+					"username": {
+						"type": "string",
+						"description": "The name of the Principal's own Namespace."
+					},
+					"display_name": { "type": ["string", "null"] },
+					"role": {
+						"type": "string",
+						"enum": ["admin", "normal"],
+						"description": "The platform role. Present only for User Principals."
+					},
+					"email": {
+						"type": "string",
+						"description": "Omitted when unset and for Agent Principals."
+					},
+					"phone_number": {
+						"type": "string",
+						"description": "Omitted when unset and for Agent Principals."
+					},
+					"avatar": {
+						"type": "string",
+						"description": "Avatar URL. Omitted when unset and for Agent Principals."
+					},
+					"disabled_at": {
+						"type": ["string", "null"],
+						"format": "date-time",
+						"description": "When the Principal was disabled; null while it is enabled."
+					},
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"has_password": {
+						"type": "boolean",
+						"description": "Whether the Principal has a password credential. Always false for Agents."
+					}
+				}
+			},
+			"AuditEventList": {
+				"type": "object",
+				"required": ["items", "next_cursor"],
+				"properties": {
+					"items": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/AuditEvent" }
+					},
+					"next_cursor": { "$ref": "#/components/schemas/NextCursor" }
+				}
+			},
+			"AuditEvent": {
+				"type": "object",
+				"required": [
+					"id",
+					"actor",
+					"action",
+					"resource_type",
+					"resource_id",
+					"metadata",
+					"created_at"
+				],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"actor": {
+						"oneOf": [{ "$ref": "#/components/schemas/AuditActor" }, { "type": "null" }],
+						"description": "The actor that performed the operation; null for a system event."
+					},
+					"action": {
+						"type": "string",
+						"description": "The controlled name of the audited operation. It is not an enum in\nthe response so a client can still show an action it does not yet\nknow instead of hiding the event.\n"
+					},
+					"resource_type": {
+						"type": "string",
+						"enum": [
+							"access_token",
+							"capability",
+							"principal",
+							"session",
+							"team"
+						]
+					},
+					"resource_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"metadata": {
+						"type": "object",
+						"description": "The non-sensitive fields defined for the action, verbatim.",
+						"additionalProperties": { "type": "string" }
+					},
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					}
+				},
+				"additionalProperties": false
+			},
+			"AuditActor": {
+				"type": "object",
+				"description": "The Principal that performed an audited operation. A deleted Principal\nand its deleted Namespace still resolve, so historical events keep\ntheir actor facts.\n",
+				"required": [
+					"principal_id",
+					"kind",
+					"username",
+					"display_name"
+				],
+				"properties": {
+					"principal_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"kind": {
+						"type": "string",
+						"enum": ["user", "agent"]
+					},
+					"username": {
+						"type": "string",
+						"description": "The name of the actor's own Namespace."
+					},
+					"display_name": { "type": ["string", "null"] },
+					"avatar": {
+						"type": "string",
+						"description": "Avatar URL. Omitted when unset and for Agent Principals."
+					}
+				},
+				"additionalProperties": false
+			},
+			"PrincipalList": {
+				"type": "object",
+				"required": ["items", "next_cursor"],
+				"properties": {
+					"items": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/Principal" }
+					},
+					"next_cursor": { "$ref": "#/components/schemas/NextCursor" }
+				}
+			},
+			"PasswordChange": {
+				"type": "object",
+				"required": ["new_password"],
+				"properties": {
+					"current_password": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 1024,
+						"description": "Required when the caller already has a password; ignored when it has\nnone, which sets the initial password.\n"
+					},
+					"new_password": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 1024,
+						"description": "Must differ from the current password."
+					}
+				},
+				"additionalProperties": false
+			},
+			"CreatePrincipalRequest": {
+				"type": "object",
+				"required": ["kind", "username"],
+				"properties": {
+					"kind": {
+						"type": "string",
+						"enum": ["user", "agent"]
+					},
+					"username": {
+						"$ref": "#/components/schemas/Name",
+						"description": "The name of the Principal's own Namespace. It never changes."
+					},
+					"display_name": {
+						"type": "string",
+						"maxLength": 128,
+						"description": "Omitted or empty means no display name."
+					},
+					"password": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 1024,
+						"description": "Required for a User; an Agent has no password."
+					},
+					"role": {
+						"type": "string",
+						"enum": ["admin", "normal"],
+						"description": "The platform role of a User, `normal` when omitted. An Agent has no role."
+					}
+				},
+				"additionalProperties": false
+			},
+			"PasswordReset": {
+				"type": "object",
+				"required": ["new_password"],
+				"properties": { "new_password": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 1024
+				} },
+				"additionalProperties": false
+			},
+			"RoleUpdate": {
+				"type": "object",
+				"required": ["role"],
+				"properties": { "role": {
+					"type": "string",
+					"enum": ["admin", "normal"]
+				} },
+				"additionalProperties": false
+			},
+			"Session": {
+				"type": "object",
+				"required": [
+					"id",
+					"current",
+					"created_at",
+					"last_seen_at",
+					"expires_at"
+				],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"current": {
+						"type": "boolean",
+						"description": "Whether this is the Session the request was made with."
+					},
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"last_seen_at": {
+						"type": "string",
+						"format": "date-time",
+						"description": "Recorded at most once every 5 minutes."
+					},
+					"expires_at": {
+						"type": "string",
+						"format": "date-time"
+					}
+				}
+			},
+			"SessionList": {
+				"type": "object",
+				"required": ["items"],
+				"properties": { "items": {
+					"type": "array",
+					"items": { "$ref": "#/components/schemas/Session" }
+				} }
+			},
+			"ProfileUpdate": {
+				"type": "object",
+				"properties": {
+					"display_name": {
+						"type": "string",
+						"maxLength": 128
+					},
+					"email": {
+						"type": "string",
+						"maxLength": 254,
+						"description": "A User-only field; Agents cannot set it."
+					},
+					"phone_number": {
+						"type": "string",
+						"maxLength": 32,
+						"description": "A User-only field; Agents cannot set it."
+					},
+					"avatar": {
+						"type": "string",
+						"maxLength": 2048,
+						"description": "An absolute `http` or `https` URL. A User-only field; Agents cannot set it."
+					}
+				},
+				"additionalProperties": false
+			},
+			"Name": {
+				"type": "string",
+				"description": "1–64 lowercase letters, digits and hyphens; no leading, trailing or\ndoubled hyphen.\n",
+				"minLength": 1,
+				"maxLength": 64,
+				"pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+			},
+			"Visibility": {
+				"type": "string",
+				"enum": [
+					"public",
+					"internal",
+					"private"
+				]
+			},
+			"Description": {
+				"type": "string",
+				"description": "Required, at most 2,000 Unicode characters.",
+				"minLength": 1,
+				"maxLength": 2e3
+			},
+			"Readme": {
+				"type": ["string", "null"],
+				"description": "Markdown, at most 1 MiB of UTF-8. Omitted or null means no README; an\nempty string is kept as an empty README.\n"
+			},
+			"MCPConfig": {
+				"type": "object",
+				"description": "The MCP config. The top level must be a JSON object; duplicate member\nnames and invalid UTF-8 are rejected.\n",
+				"additionalProperties": true,
+				"x-go-type": "json.RawMessage"
+			},
+			"Tag": {
+				"type": "string",
+				"description": "A normalized tag: 1–32 Unicode characters after trimming, collapsing\ninternal whitespace and case-folding to lowercase. It cannot contain a\ncomma or a control character. Writers and readers normalize the same\nway, so a tag compares and filters by its normalized form.\n",
+				"minLength": 1,
+				"maxLength": 32,
+				"pattern": "^[^,\\x00-\\x1F\\x7F]+$"
+			},
+			"CreateMCPCapabilityRequest": {
+				"type": "object",
+				"required": [
+					"namespace",
+					"name",
+					"description",
+					"visibility",
+					"config"
+				],
+				"properties": {
+					"namespace": {
+						"$ref": "#/components/schemas/Name",
+						"description": "The name of the target Namespace."
+					},
+					"name": { "$ref": "#/components/schemas/Name" },
+					"description": { "$ref": "#/components/schemas/Description" },
+					"visibility": { "$ref": "#/components/schemas/Visibility" },
+					"readme": { "$ref": "#/components/schemas/Readme" },
+					"tags": {
+						"type": "array",
+						"description": "The Capability's tags. Omitted or empty means no tags. The server\nnormalizes, deduplicates and sorts them, and rejects more than\neight.\n",
+						"maxItems": 8,
+						"items": { "$ref": "#/components/schemas/Tag" }
+					},
+					"config": { "$ref": "#/components/schemas/MCPConfig" }
+				},
+				"additionalProperties": false
+			},
+			"CreateSkillCapabilityRequest": {
+				"type": "object",
+				"description": "Each field is sent once, and `package` must be the last part. The\npackage is a ZIP of at most 16 MiB with at most 2,000 entries, each\nentry at most 16 MiB unpacked, at most 128 MiB unpacked in total and a\ncompression ratio of at most 100:1. Entries must be regular files or\ndirectories with clean relative paths. Exactly one `SKILL.md` is\nallowed, at the package root or directly inside the single top-level\ndirectory that holds every entry.\n",
+				"required": [
+					"namespace",
+					"name",
+					"description",
+					"visibility",
+					"package"
+				],
+				"properties": {
+					"namespace": {
+						"$ref": "#/components/schemas/Name",
+						"description": "The name of the target Namespace."
+					},
+					"name": { "$ref": "#/components/schemas/Name" },
+					"description": { "$ref": "#/components/schemas/Description" },
+					"visibility": { "$ref": "#/components/schemas/Visibility" },
+					"readme": {
+						"type": "string",
+						"description": "Markdown, at most 1 MiB of UTF-8. Omitted means no README."
+					},
+					"tags": {
+						"type": "string",
+						"description": "The Capability's tags as one comma-separated field, because a\nmultipart form cannot carry a JSON array. Tags themselves cannot\ncontain commas. Omitted or empty means no tags; the server\nnormalizes, deduplicates and sorts them, and rejects more than\neight.\n",
+						"maxLength": 512
+					},
+					"package": {
+						"type": "string",
+						"description": "The Capability Package, sent as `application/zip`."
+					}
+				},
+				"additionalProperties": false
+			},
+			"CapabilityUpdate": {
+				"type": "object",
+				"properties": {
+					"description": { "$ref": "#/components/schemas/Description" },
+					"visibility": { "$ref": "#/components/schemas/Visibility" },
+					"tags": {
+						"type": "array",
+						"description": "When present, replaces the whole tag set. Omitted leaves it\nunchanged. Normalization and limits are those of create.\n",
+						"maxItems": 8,
+						"items": { "$ref": "#/components/schemas/Tag" }
+					},
+					"kind": {
+						"description": "Immutable; any value returns 400.",
+						"x-go-type": "json.RawMessage",
+						"x-go-type-skip-optional-pointer": true
+					},
+					"namespace": {
+						"description": "Immutable; any value returns 400.",
+						"x-go-type": "json.RawMessage",
+						"x-go-type-skip-optional-pointer": true
+					},
+					"name": {
+						"description": "Immutable; any value returns 400.",
+						"x-go-type": "json.RawMessage",
+						"x-go-type-skip-optional-pointer": true
+					}
+				},
+				"additionalProperties": false
+			},
+			"PublishMCPVersionRequest": {
+				"type": "object",
+				"required": ["config"],
+				"properties": {
+					"readme": { "$ref": "#/components/schemas/Readme" },
+					"config": { "$ref": "#/components/schemas/MCPConfig" }
+				},
+				"additionalProperties": false
+			},
+			"PublishSkillVersionRequest": {
+				"type": "object",
+				"description": "Each field is sent once, and `package` must be the last part. The\npackage follows the rules of `CreateSkillCapabilityRequest`.\n",
+				"required": ["package"],
+				"properties": {
+					"readme": {
+						"type": "string",
+						"description": "Markdown, at most 1 MiB of UTF-8. Omitted means no README."
+					},
+					"package": {
+						"type": "string",
+						"description": "The Capability Package, sent as `application/zip`."
+					}
+				},
+				"additionalProperties": false
+			},
+			"Capability": {
+				"type": "object",
+				"required": [
+					"id",
+					"kind",
+					"namespace",
+					"namespace_kind",
+					"namespace_display_name",
+					"name",
+					"path",
+					"visibility",
+					"description",
+					"tags",
+					"download_count",
+					"current_version",
+					"created_at",
+					"updated_at"
+				],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"kind": {
+						"type": "string",
+						"enum": ["skill", "mcp"]
+					},
+					"namespace": {
+						"$ref": "#/components/schemas/Name",
+						"description": "The name of the owning Namespace."
+					},
+					"namespace_kind": {
+						"$ref": "#/components/schemas/NamespaceKind",
+						"description": "The kind of the owning Namespace."
+					},
+					"namespace_display_name": {
+						"type": ["string", "null"],
+						"description": "The display name of the owning Team or Principal, when one is set."
+					},
+					"name": { "$ref": "#/components/schemas/Name" },
+					"path": {
+						"type": "string",
+						"description": "Derived address: `/<skills|mcp>/<name>` for system,\n`/<skills|mcp>/<namespace>/<name>` otherwise. Not a permanent\nidentity.\n"
+					},
+					"visibility": { "$ref": "#/components/schemas/Visibility" },
+					"description": { "$ref": "#/components/schemas/Description" },
+					"tags": {
+						"type": "array",
+						"description": "Normalized tags, sorted lexicographically; empty, never null.",
+						"maxItems": 8,
+						"items": { "$ref": "#/components/schemas/Tag" }
+					},
+					"download_count": {
+						"type": "integer",
+						"format": "int64",
+						"minimum": 0,
+						"description": "The number of successful Content GETs, advisory and aggregate. It\ncounts neither HEAD, 304 nor failed requests, and is not part of\nthe `ETag` or the Audit Event vocabulary.\n"
+					},
+					"current_version": { "$ref": "#/components/schemas/CalVer" },
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"updated_at": {
+						"type": "string",
+						"format": "date-time"
+					}
+				}
+			},
+			"TagCount": {
+				"type": "object",
+				"required": ["name", "count"],
+				"properties": {
+					"name": { "$ref": "#/components/schemas/Tag" },
+					"count": {
+						"type": "integer",
+						"format": "int64",
+						"minimum": 0
+					}
+				}
+			},
+			"TagList": {
+				"type": "object",
+				"required": ["items", "truncated"],
+				"properties": {
+					"items": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/TagCount" }
+					},
+					"truncated": {
+						"type": "boolean",
+						"description": "More tags exist than the requested `limit`."
+					}
+				}
+			},
+			"CapabilityList": {
+				"type": "object",
+				"required": ["items", "next_cursor"],
+				"properties": {
+					"items": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/Capability" }
+					},
+					"next_cursor": { "$ref": "#/components/schemas/NextCursor" }
+				}
+			},
+			"VersionSummary": {
+				"type": "object",
+				"required": [
+					"id",
+					"version",
+					"created_at"
+				],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"version": { "$ref": "#/components/schemas/CalVer" },
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					}
+				}
+			},
+			"Version": {
+				"type": "object",
+				"required": [
+					"id",
+					"version",
+					"readme",
+					"created_at"
+				],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"version": { "$ref": "#/components/schemas/CalVer" },
+					"readme": {
+						"type": ["string", "null"],
+						"description": "The Version's Markdown README, or null when it has none."
+					},
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"published_by": {
+						"oneOf": [{ "$ref": "#/components/schemas/VersionPublisher" }, { "type": "null" }],
+						"description": "The Principal that published this Version, or null when the\nVersion has no recorded publisher. The publisher's Namespace name\nis returned even after the Principal or its Namespace is deleted,\nso historical Versions keep their attribution.\n"
+					},
+					"content": { "$ref": "#/components/schemas/VersionContent" },
+					"config": {
+						"type": ["object", "null"],
+						"description": "The parsed MCP config for an MCP Version; null for a Skill Version.\nReading it does not count as a Content download.\n",
+						"additionalProperties": true
+					}
+				}
+			},
+			"VersionPublisher": {
+				"type": "object",
+				"description": "The Principal that published a Version. A deleted Principal and its\ndeleted Namespace still resolve, so historical attribution survives.\n",
+				"properties": {
+					"principal_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"username": {
+						"type": "string",
+						"description": "The name of the publisher's own Namespace."
+					},
+					"display_name": { "type": ["string", "null"] },
+					"avatar": {
+						"type": "string",
+						"description": "Avatar URL. Omitted when unset and for Agent Principals."
+					}
+				},
+				"required": [
+					"principal_id",
+					"username",
+					"display_name"
+				],
+				"additionalProperties": false
+			},
+			"VersionContent": {
+				"type": "object",
+				"description": "The stored form of a Version's Content. `sha256` is the hex digest of\nthe same bytes the Content endpoint serves, so it equals the hex\ninside that endpoint's strong `ETag`.\n",
+				"properties": {
+					"media_type": {
+						"type": "string",
+						"enum": ["application/zip", "application/json"]
+					},
+					"size": {
+						"type": "integer",
+						"format": "int64",
+						"description": "The Content's size in bytes."
+					},
+					"sha256": {
+						"type": "string",
+						"pattern": "^[0-9a-f]{64}$",
+						"description": "Lowercase hex sha256 of the Content bytes."
+					}
+				},
+				"required": [
+					"media_type",
+					"size",
+					"sha256"
+				],
+				"additionalProperties": false
+			},
+			"VersionList": {
+				"type": "object",
+				"required": ["items", "next_cursor"],
+				"properties": {
+					"items": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/VersionSummary" }
+					},
+					"next_cursor": { "$ref": "#/components/schemas/NextCursor" }
+				}
+			},
+			"Namespace": {
+				"type": "object",
+				"required": [
+					"id",
+					"kind",
+					"name",
+					"namespace_display_name",
+					"created_at"
+				],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"kind": { "$ref": "#/components/schemas/NamespaceKind" },
+					"name": { "$ref": "#/components/schemas/Name" },
+					"namespace_display_name": {
+						"type": ["string", "null"],
+						"description": "The display name of the owning Team or Principal, when one is set."
+					},
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					}
+				}
+			},
+			"NamespaceKind": {
+				"type": "string",
+				"description": "The kind of owner a Namespace belongs to.",
+				"enum": [
+					"system",
+					"team",
+					"principal"
+				]
+			},
+			"NamespaceList": {
+				"type": "object",
+				"required": ["items", "next_cursor"],
+				"properties": {
+					"items": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/Namespace" }
+					},
+					"next_cursor": { "$ref": "#/components/schemas/NextCursor" }
+				}
+			},
+			"NextCursor": {
+				"type": ["string", "null"],
+				"description": "Send as `cursor` to read the next page; null on the last page."
+			},
+			"CreateTeamRequest": {
+				"type": "object",
+				"required": ["name", "admins"],
+				"properties": {
+					"name": {
+						"$ref": "#/components/schemas/Name",
+						"description": "The name of the Team's Namespace."
+					},
+					"display_name": {
+						"type": "string",
+						"maxLength": 128
+					},
+					"admins": {
+						"type": "array",
+						"description": "The first Team Admins. Each must be an enabled User.",
+						"minItems": 1,
+						"uniqueItems": true,
+						"items": {
+							"type": "string",
+							"format": "uuid"
+						}
+					}
+				},
+				"additionalProperties": false
+			},
+			"Team": {
+				"type": "object",
+				"required": [
+					"id",
+					"name",
+					"display_name",
+					"disabled_at",
+					"created_at"
+				],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"name": {
+						"$ref": "#/components/schemas/Name",
+						"description": "The name of the Team's Namespace."
+					},
+					"display_name": { "type": ["string", "null"] },
+					"disabled_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					},
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					}
+				}
+			},
+			"TeamList": {
+				"type": "object",
+				"required": ["items", "next_cursor"],
+				"properties": {
+					"items": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/Team" }
+					},
+					"next_cursor": { "$ref": "#/components/schemas/NextCursor" }
+				}
+			},
+			"TeamRole": {
+				"type": "string",
+				"enum": ["admin", "member"],
+				"description": "A Team Admin is also a member and alone governs the Team."
+			},
+			"TeamMemberRole": {
+				"type": "object",
+				"required": ["role"],
+				"properties": { "role": { "$ref": "#/components/schemas/TeamRole" } },
+				"additionalProperties": false
+			},
+			"TeamMember": {
+				"type": "object",
+				"required": [
+					"principal_id",
+					"kind",
+					"username",
+					"display_name",
+					"disabled_at",
+					"role"
+				],
+				"properties": {
+					"principal_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"kind": {
+						"type": "string",
+						"enum": ["user", "agent"]
+					},
+					"username": {
+						"type": "string",
+						"description": "The name of the Principal's own Namespace."
+					},
+					"display_name": { "type": ["string", "null"] },
+					"disabled_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					},
+					"role": { "$ref": "#/components/schemas/TeamRole" },
+					"avatar": {
+						"type": "string",
+						"description": "Avatar URL. Omitted when unset and for Agent Principals."
+					}
+				}
+			},
+			"TeamMemberList": {
+				"type": "object",
+				"required": ["items", "next_cursor"],
+				"properties": {
+					"items": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/TeamMember" }
+					},
+					"next_cursor": { "$ref": "#/components/schemas/NextCursor" }
+				}
+			},
+			"TeamMemberCandidate": {
+				"type": "object",
+				"description": "A Principal that is not a member of the Team and matches the required\nquery. Deleted Principals never appear; disabled ones do.\n",
+				"required": [
+					"id",
+					"kind",
+					"username",
+					"display_name",
+					"disabled_at"
+				],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"kind": {
+						"type": "string",
+						"enum": ["user", "agent"]
+					},
+					"username": {
+						"type": "string",
+						"description": "The name of the Principal's own Namespace."
+					},
+					"display_name": { "type": ["string", "null"] },
+					"disabled_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					},
+					"avatar": {
+						"type": "string",
+						"description": "Avatar URL. Omitted when unset and for Agent Principals."
+					}
+				}
+			},
+			"TeamMemberCandidateList": {
+				"type": "object",
+				"required": ["items", "next_cursor"],
+				"properties": {
+					"items": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/TeamMemberCandidate" }
+					},
+					"next_cursor": { "$ref": "#/components/schemas/NextCursor" }
+				}
+			},
+			"CalVer": {
+				"type": "string",
+				"description": "`YYYY.MM.DD.N` in UTC; N counts from 0 per Capability per day.",
+				"pattern": "^[0-9]{4}\\.[0-9]{2}\\.[0-9]{2}\\.(0|[1-9][0-9]*)$"
+			},
+			"ProblemDetails": {
+				"type": "object",
+				"description": "RFC 9457 problem detail, served as `application/problem+json`. `type`\nis a relative reference under `/problems/` (for example\n`/problems/unauthenticated`), or `about:blank` for unclassified errors.\n",
+				"required": [
+					"type",
+					"title",
+					"status"
+				],
+				"properties": {
+					"type": {
+						"type": "string",
+						"format": "uri-reference"
+					},
+					"title": { "type": "string" },
+					"status": {
+						"type": "integer",
+						"minimum": 100,
+						"maximum": 599
+					},
+					"detail": { "type": "string" },
+					"instance": {
+						"type": "string",
+						"format": "uri-reference"
+					}
+				},
+				"additionalProperties": true
+			}
+		},
+		"securitySchemes": {
+			"sessionCookie": {
+				"type": "apiKey",
+				"in": "cookie",
+				"name": "hangar_session"
+			},
+			"bearerToken": {
+				"type": "http",
+				"scheme": "bearer"
+			}
+		}
+	}
+});
+/** Collapses `schema   capabilities   list` into the catalog's single-space form. */
+function normalizeCommandName(raw) {
+	return raw.trim().split(/\s+/).join(" ");
+}
+/** Rewrites a root alias to its canonical noun: `caps list` -> `capabilities list`. */
+function canonicalCommandName(raw) {
+	const name = normalizeCommandName(raw);
+	const [first = "", ...rest] = name.split(" ");
+	const canonical = Object.entries(COMMAND_ALIASES).find(([, aliases]) => aliases.includes(first))?.[0];
+	return canonical ? [canonical, ...rest].join(" ") : name;
+}
+function findCommand(raw) {
+	const name = canonicalCommandName(raw);
+	return COMMANDS.find((spec) => spec.name === name);
+}
+// src/catalog.ts
+/**
+* Stable machine-readable catalog of the workflow commands. OpenAPI-derived
+* commands are merged into the same shape by `commandCatalog`.
+*/
+function workflowCatalog() {
+	return [
+		{
+			name: "auth",
+			summary: "Manage credentials (login, logout, status, token, whoami)",
+			group: "auth",
+			args: [],
+			flags: [],
+			destructive: false,
+			dryRun: false
+		},
+		{
+			name: "auth login",
+			summary: "Log in with username and password and mint an access token",
+			group: "auth",
+			args: [],
+			flags: [{
+				name: "token",
+				type: "boolean",
+				description: "Read a token from stdin"
+			}],
+			destructive: false,
+			dryRun: false
+		},
+		{
+			name: "auth logout",
+			summary: "Revoke the stored token and delete the local config",
+			group: "auth",
+			args: [],
+			flags: [],
+			destructive: true,
+			dryRun: false
+		},
+		{
+			name: "auth status",
+			summary: "Show credential source, server, principal and token prefix",
+			group: "auth",
+			args: [],
+			flags: [{
+				name: "offline",
+				type: "boolean",
+				description: "Skip the GET /me check"
+			}],
+			destructive: false,
+			dryRun: false
+		},
+		{
+			name: "auth token",
+			summary: "Print the access token to stdout and nothing else",
+			group: "auth",
+			args: [],
+			flags: [],
+			destructive: false,
+			dryRun: false
+		},
+		{
+			name: "auth whoami",
+			summary: "Print the GET /me payload",
+			group: "auth",
+			args: [],
+			flags: [],
+			destructive: false,
+			dryRun: false
+		},
+		{
+			name: "skills add",
+			summary: "Install skills from the catalog into agent targets",
+			group: "skills",
+			args: [{
+				name: "path",
+				required: true,
+				variadic: true,
+				description: "<name> or <namespace>/<name>, optionally @<version>"
+			}],
+			flags: [
+				{
+					name: "agent",
+					type: "string",
+					repeatable: true,
+					description: "Agent target id"
+				},
+				{
+					name: "all",
+					type: "boolean",
+					description: "Install to all known agents"
+				},
+				{
+					name: "global",
+					type: "boolean",
+					description: "Install globally instead of project"
+				},
+				{
+					name: "dir",
+					type: "string",
+					description: "Copy into this directory instead"
+				},
+				{
+					name: "as",
+					type: "string",
+					description: "Override the target directory name"
+				},
+				{
+					name: "copy",
+					type: "boolean",
+					description: "Copy instead of canonical + symlink"
+				}
+			],
+			destructive: false,
+			dryRun: true
+		},
+		{
+			name: "skills publish",
+			summary: "Publish a local skill directory as a capability or a new version",
+			group: "skills",
+			args: [{
+				name: "dir",
+				required: true,
+				variadic: true,
+				description: "Local directory containing SKILL.md"
+			}],
+			flags: [
+				{
+					name: "namespace",
+					type: "string",
+					description: "Target namespace (default: system)"
+				},
+				{
+					name: "name",
+					type: "string",
+					description: "Capability name (default: directory name)"
+				},
+				{
+					name: "description",
+					type: "string",
+					description: "Required when creating"
+				},
+				{
+					name: "visibility",
+					type: "string",
+					description: "public | internal | private (default: private)"
+				},
+				{
+					name: "readme",
+					type: "string",
+					description: "Markdown file to attach"
+				},
+				{
+					name: "tag",
+					type: "string",
+					repeatable: true,
+					description: "Capability tag"
+				},
+				{
+					name: "new",
+					type: "boolean",
+					description: "Fail when the capability already exists"
+				}
+			],
+			destructive: false,
+			dryRun: true
+		},
+		{
+			name: "mcp add",
+			summary: "Merge MCP server entries from the catalog into agent configs",
+			group: "mcp",
+			args: [{
+				name: "path",
+				required: true,
+				variadic: true,
+				description: "<name> or <namespace>/<name>, optionally @<version>"
+			}],
+			flags: [
+				{
+					name: "agent",
+					type: "string",
+					repeatable: true,
+					description: "Agent target id"
+				},
+				{
+					name: "all",
+					type: "boolean",
+					description: "Install to all known agents"
+				},
+				{
+					name: "global",
+					type: "boolean",
+					description: "Install globally instead of project"
+				}
+			],
+			destructive: false,
+			dryRun: true
+		},
+		{
+			name: "mcp publish",
+			summary: "Publish an MCP snapshot as a capability or a new version",
+			group: "mcp",
+			args: [{
+				name: "file",
+				required: true,
+				variadic: true,
+				description: "Local JSON snapshot containing mcpServers"
+			}],
+			flags: [
+				{
+					name: "namespace",
+					type: "string",
+					description: "Target namespace (default: system)"
+				},
+				{
+					name: "name",
+					type: "string",
+					description: "Capability name (default: file name without .json)"
+				},
+				{
+					name: "description",
+					type: "string",
+					description: "Required when creating"
+				},
+				{
+					name: "visibility",
+					type: "string",
+					description: "public | internal | private (default: private)"
+				},
+				{
+					name: "readme",
+					type: "string",
+					description: "Markdown file to attach"
+				},
+				{
+					name: "tag",
+					type: "string",
+					repeatable: true,
+					description: "Capability tag"
+				},
+				{
+					name: "new",
+					type: "boolean",
+					description: "Fail when the capability already exists"
+				}
+			],
+			destructive: false,
+			dryRun: true
+		},
+		{
+			name: "commands",
+			summary: "Print the command catalog",
+			group: "discovery",
+			args: [],
+			flags: [],
+			destructive: false,
+			dryRun: false
+		},
+		{
+			name: "schema",
+			summary: "Print the method, path, params and body schema of a command",
+			group: "discovery",
+			args: [{
+				name: "command",
+				required: true,
+				description: "Command name, e.g. 'skills add'"
+			}],
+			flags: [],
+			destructive: false,
+			dryRun: false
+		},
+		{
+			name: "completion",
+			summary: "Print a shell completion script",
+			group: "discovery",
+			args: [{
+				name: "shell",
+				required: true,
+				description: "bash | zsh | fish"
+			}],
+			flags: [],
+			destructive: false,
+			dryRun: false
+		}
+	];
+}
+/**
+* The full catalog: workflow commands first, then OpenAPI-derived commands.
+* A derived command whose name a workflow command already owns appears once,
+* in the workflow group. Ordering is stable and deterministic so
+* `commands --json` diffing is safe.
+*/
+function commandCatalog(generated = COMMANDS.map(generatedEntry)) {
+	const workflow = workflowCatalog();
+	const workflowNames = new Set(workflow.map((entry) => entry.name));
+	return [...workflow, ...generated.filter((entry) => !workflowNames.has(entry.name))];
+}
+export { kebabCase as a, normalizeCommandName as i, COMMANDS as n, COMMAND_ALIASES as o, findCommand as r, commandCatalog as t };