hngr 0.2.0 → 0.4.0

package/dist/{catalog-jU0-wzh3.mjs → catalog-Bv304SXJ.mjs}

@@ -28,7 +28,11 @@ function catalogFlagType(flag) {
 * 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. */
+/**
+* Endpoints that never appear in the command tree. An entry excludes that path
+* and everything below it, so a subtree needs one line rather than one line
+* per operation.
+*/
 const EXCLUDED_PATHS = [
 	"/api/v1/login",
 	"/api/v1/logout",
@@ -36,9 +40,36 @@ const EXCLUDED_PATHS = [
 	"/api/v1/me/sessions",
 	"/api/v1/me/sessions/{id}",
 	"/api/v1/capabilities/{capability_id}/versions/{version}/content",
+	"/api/v1/capabilities/{capability_id}/versions/{version}/files",
+	"/api/v1/capabilities/{capability_id}/versions/{version}/file",
 	"/api/v1/auth/methods",
 	"/api/v1/auth/oidc/login",
-	"/api/v1/auth/oidc/callback"
+	"/api/v1/auth/oidc/callback",
+	"/api/v1/auth/device/code",
+	"/api/v1/auth/device/token",
+	"/api/v1/auth/device/lookup",
+	"/api/v1/auth/device/approve",
+	"/api/v1/auth/device/deny",
+	"/api/v1/oauth"
+];
+/**
+* Single operations whose path still generates other commands. Category
+* curation lives in the Web console in v1, so `categories list` stays while
+* create, rename and delete are hidden.
+*/
+const EXCLUDED_OPERATIONS = [
+	{
+		method: "POST",
+		path: "/api/v1/categories"
+	},
+	{
+		method: "PATCH",
+		path: "/api/v1/categories/{category_id}"
+	},
+	{
+		method: "DELETE",
+		path: "/api/v1/categories/{category_id}"
+	}
 ];
 /**
 * Root-noun aliases. Aliases only affect parsing: help annotates the canonical
@@ -124,13 +155,15 @@ const METHOD_KEY = {
 */
 function deriveCommands(doc) {
 	const excluded = new Set(EXCLUDED_PATHS);
+	const excludedSubtrees = EXCLUDED_PATHS.map((path) => `${path}/`);
+	const excludedOperations = new Set(EXCLUDED_OPERATIONS.map((operation) => `${operation.method} ${operation.path}`));
 	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;
+		if (excluded.has(path) || excludedSubtrees.some((prefix) => path.startsWith(prefix))) continue;
 		for (const method of METHODS) {
 			const operation = pathItem[METHOD_KEY[method]];
-			if (!operation) continue;
+			if (!operation || excludedOperations.has(`${method} ${path}`)) continue;
 			commands.push(deriveCommand(doc, path, pathItem, method, operation, overrides));
 		}
 	}
@@ -564,6 +597,111 @@ const COMMANDS = deriveCommands({
 				"default": { "$ref": "#/components/responses/Problem" }
 			}
 		} },
+		"/api/v1/auth/device/code": { "post": {
+			"operationId": "createDeviceAuthorization",
+			"summary": "Request a Device Authorization for the CLI.",
+			"description": "Anonymous, and rate-limited to 10 requests per client address in any\n15-minute window. The device code is a credential: it is returned once\nand stored only as a keyed digest. The user code is a short public\nidentifier shown on the verification page; it is 8 Crockford Base32\ncharacters displayed as `XXXX-XXXX`, and case, hyphens and spaces are\nignored on input with `I` read as `1` and `O` as `0`. Expired,\nunconsumed requests are cleared by the next successful create.\n",
+			"security": [],
+			"requestBody": {
+				"required": true,
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeviceAuthorizationRequest" } } }
+			},
+			"responses": {
+				"200": {
+					"description": "The new Device Authorization request.",
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorizationCode" } } }
+				},
+				"400": { "$ref": "#/components/responses/Problem" },
+				"413": { "$ref": "#/components/responses/Problem" },
+				"429": { "$ref": "#/components/responses/Problem" },
+				"default": { "$ref": "#/components/responses/Problem" }
+			}
+		} },
+		"/api/v1/auth/device/lookup": { "post": {
+			"operationId": "lookupDeviceAuthorization",
+			"summary": "Look up a Device Authorization by user code.",
+			"description": "Session-only; a Bearer Access Token is refused even though it\nauthenticates elsewhere. The code travels in the body, never in the\npath or query. Input is normalized like creation input. Denied and\nconsumed requests stay readable so a reload shows their resulting\nstate; unknown, expired and invalidated codes answer 404.\n",
+			"security": [{ "sessionCookie": [] }],
+			"requestBody": {
+				"required": true,
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupDeviceAuthorizationRequest" } } }
+			},
+			"responses": {
+				"200": {
+					"description": "The request, in whatever state it reached.",
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorization" } } }
+				},
+				"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/auth/device/token": { "post": {
+			"operationId": "pollDeviceAuthorization",
+			"summary": "Poll a Device Authorization for its Access Token.",
+			"description": "Anonymous; the device code travels in the body. A pending request\nanswers 400 with the `authorization-pending` problem type, and a poll\ninside the advertised interval answers `slow-down`. A denied request\nanswers `access-denied`; an expired, invalidated, consumed or unknown\none answers `expired-token`. Approval mints nothing: the Access Token\nis created on the poll that observes the approval and its value is\nreturned exactly once. Unknown device codes are rate-limited per client\naddress.\n",
+			"security": [],
+			"requestBody": {
+				"required": true,
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/PollDeviceAuthorizationRequest" } } }
+			},
+			"responses": {
+				"200": {
+					"description": "The minted Access Token and its Principal.",
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorizationToken" } } }
+				},
+				"400": { "$ref": "#/components/responses/Problem" },
+				"413": { "$ref": "#/components/responses/Problem" },
+				"429": { "$ref": "#/components/responses/Problem" },
+				"default": { "$ref": "#/components/responses/Problem" }
+			}
+		} },
+		"/api/v1/auth/device/approve": { "post": {
+			"operationId": "approveDeviceAuthorization",
+			"summary": "Approve a Device Authorization.",
+			"description": "Session-only; a Bearer Access Token is refused. Records the approving\nPrincipal and the approval time and mints nothing. The Access Token is\ncreated only when the waiting CLI polls. A code that exists but is no\nlonger actionable counts as one failed attempt; at five attempts the\ncode is invalid for every operation and answers 404.\n",
+			"security": [{ "sessionCookie": [] }],
+			"requestBody": {
+				"required": true,
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveDeviceAuthorizationRequest" } } }
+			},
+			"responses": {
+				"200": {
+					"description": "The request in its approved state.",
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorization" } } }
+				},
+				"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/auth/device/deny": { "post": {
+			"operationId": "denyDeviceAuthorization",
+			"summary": "Deny a Device Authorization.",
+			"description": "Session-only; a Bearer Access Token is refused. Records the denial and\nmints nothing. The waiting CLI's next poll answers `access-denied`. A\ncode that exists but is no longer actionable counts as one failed\nattempt; at five attempts the code is invalid for every operation and\nanswers 404.\n",
+			"security": [{ "sessionCookie": [] }],
+			"requestBody": {
+				"required": true,
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/DenyDeviceAuthorizationRequest" } } }
+			},
+			"responses": {
+				"200": {
+					"description": "The request in its denied state.",
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorization" } } }
+				},
+				"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/logout": { "post": {
 			"operationId": "logout",
 			"summary": "Revoke the current Session and clear its cookie.",
@@ -744,10 +882,11 @@ const COMMANDS = deriveCommands({
 		"/api/v1/me/tokens/{token_id}": { "delete": {
 			"operationId": "revokeMyAccessToken",
 			"summary": "Revoke one of the authenticated Principal's Access Tokens.",
+			"description": "When the token belongs to an OAuth grant, every access token and\nrefresh token sharing its `grant_id` is revoked in the same\ntransaction.\n",
 			"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
 			"parameters": [{ "$ref": "#/components/parameters/TokenID" }],
 			"responses": {
-				"204": { "description": "Revoked. The token stops authenticating immediately." },
+				"204": { "description": "Revoked. The token and, when it belongs to a grant, its siblings stop authenticating immediately." },
 				"400": { "$ref": "#/components/responses/Problem" },
 				"401": { "$ref": "#/components/responses/Problem" },
 				"403": { "$ref": "#/components/responses/Problem" },
@@ -755,6 +894,106 @@ const COMMANDS = deriveCommands({
 				"default": { "$ref": "#/components/responses/Problem" }
 			}
 		} },
+		"/api/v1/oauth/register": { "post": {
+			"operationId": "registerOAuthClient",
+			"summary": "Register a public OAuth client through Dynamic Client Registration.",
+			"description": "Anonymous. Implements RFC 7591 registration for the public native\nclients that connect to Native MCP: no client secret is issued, and\npossession of the `client_id` plus an exactly matching redirect URI is\nthe whole identity. `client_name` is 1–100 characters and\n`redirect_uris` holds 1–10 absolute URIs without a fragment: `https`\nanywhere, `http` only on localhost, 127.0.0.1 or [::1]. Exact\nduplicates are removed. Registration failures are RFC 6749 error\nbodies, not problem details.\n",
+			"security": [],
+			"requestBody": {
+				"required": true,
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientRegistrationRequest" } } }
+			},
+			"responses": {
+				"201": {
+					"description": "The registered client. Hangar never issues a client secret.",
+					"headers": { "Cache-Control": {
+						"description": "Always `no-store`.",
+						"schema": { "type": "string" }
+					} },
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientRegistration" } } }
+				},
+				"400": { "$ref": "#/components/responses/OAuthError" },
+				"413": { "$ref": "#/components/responses/OAuthProblem" },
+				"default": { "$ref": "#/components/responses/OAuthProblem" }
+			}
+		} },
+		"/api/v1/oauth/token": { "post": {
+			"operationId": "exchangeOAuthToken",
+			"summary": "Exchange an authorization code or refresh token for an MCP token pair.",
+			"description": "Anonymous and form-encoded. `grant_type=authorization_code` requires\n`code`, `redirect_uri`, `client_id` and `code_verifier`; the code is\nsingle use and the PKCE challenge must be S256.\n`grant_type=refresh_token` requires `refresh_token` and `client_id` and\nrotates the refresh token. Presenting an already rotated refresh token\nrevokes the whole grant. Every failure is an RFC 6749 error body with\nstatus 400.\n",
+			"security": [],
+			"requestBody": {
+				"required": true,
+				"content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ExchangeOAuthTokenRequest" } } }
+			},
+			"responses": {
+				"200": {
+					"description": "A fresh MCP access token and a refresh token.",
+					"headers": { "Cache-Control": {
+						"description": "Always `no-store`.",
+						"schema": { "type": "string" }
+					} },
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthToken" } } }
+				},
+				"400": { "$ref": "#/components/responses/OAuthError" },
+				"413": { "$ref": "#/components/responses/OAuthProblem" },
+				"default": { "$ref": "#/components/responses/OAuthProblem" }
+			}
+		} },
+		"/api/v1/oauth/authorization-request": {
+			"get": {
+				"operationId": "lookupOAuthAuthorizationRequest",
+				"summary": "Read the consent page preview of an authorization request.",
+				"description": "Session-only. Validates `response_type=code`, the registered client,\nthe exact `redirect_uri` and `code_challenge_method=S256` before\nreturning anything displayable. An invalid request answers 400 and\nnever redirects, so an unknown client cannot be used for an open\nredirect. The preview never includes the redirect URI itself.\n",
+				"security": [{ "sessionCookie": [] }],
+				"parameters": [
+					{ "$ref": "#/components/parameters/OAuthResponseType" },
+					{ "$ref": "#/components/parameters/OAuthClientID" },
+					{ "$ref": "#/components/parameters/OAuthRedirectURI" },
+					{ "$ref": "#/components/parameters/OAuthState" },
+					{ "$ref": "#/components/parameters/OAuthCodeChallenge" },
+					{ "$ref": "#/components/parameters/OAuthCodeChallengeMethod" }
+				],
+				"responses": {
+					"200": {
+						"description": "The client name and callback host shown on the consent page.",
+						"headers": { "Cache-Control": {
+							"description": "Always `no-store`.",
+							"schema": { "type": "string" }
+						} },
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthAuthorizationPreview" } } }
+					},
+					"400": { "$ref": "#/components/responses/OAuthProblem" },
+					"401": { "$ref": "#/components/responses/OAuthProblem" },
+					"default": { "$ref": "#/components/responses/OAuthProblem" }
+				}
+			},
+			"post": {
+				"operationId": "decideOAuthAuthorizationRequest",
+				"summary": "Approve or deny an authorization request.",
+				"description": "Session-only and CSRF protected. Repeats the authorization request's\nparameters plus `decision`. Approval issues a single-use ten-minute\ncode and answers with the client redirect carrying `code` and `state`;\ndenial answers with `error=access_denied` and `state`. The redirect\npreserves any query already present on the registered redirect URI.\nAn invalid request answers 400 and never redirects.\n",
+				"security": [{ "sessionCookie": [] }],
+				"requestBody": {
+					"required": true,
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideOAuthAuthorizationRequest" } } }
+				},
+				"responses": {
+					"200": {
+						"description": "The URL the consent page navigates to.",
+						"headers": { "Cache-Control": {
+							"description": "Always `no-store`.",
+							"schema": { "type": "string" }
+						} },
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthAuthorizationDecision" } } }
+					},
+					"400": { "$ref": "#/components/responses/OAuthProblem" },
+					"401": { "$ref": "#/components/responses/OAuthProblem" },
+					"403": { "$ref": "#/components/responses/OAuthProblem" },
+					"413": { "$ref": "#/components/responses/OAuthProblem" },
+					"default": { "$ref": "#/components/responses/OAuthProblem" }
+				}
+			}
+		},
 		"/api/v1/principals/{principal_id}/tokens": {
 			"parameters": [{ "$ref": "#/components/parameters/PrincipalID" }],
 			"get": {
@@ -796,10 +1035,10 @@ const COMMANDS = deriveCommands({
 			"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.",
+				"description": "Allowed for the Principal itself, and for a Platform Admin when the\nPrincipal is an Agent. When the token belongs to an OAuth grant, every\naccess token and refresh token sharing its `grant_id` is revoked in\nthe same transaction.\n",
 				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
 				"responses": {
-					"204": { "description": "Revoked. The token stops authenticating immediately." },
+					"204": { "description": "Revoked. The token and, when it belongs to a grant, its siblings stop authenticating immediately." },
 					"400": { "$ref": "#/components/responses/Problem" },
 					"401": { "$ref": "#/components/responses/Problem" },
 					"403": { "$ref": "#/components/responses/Problem" },
@@ -1036,12 +1275,12 @@ const COMMANDS = deriveCommands({
 						}
 					},
 					{
-						"name": "tag",
+						"name": "category",
 						"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",
+						"description": "A Category reference: `slug` for the system Namespace, otherwise\n`namespace/slug`. A Capability matches when it carries that\nCategory; the match combines with every other filter using AND.\nA syntactically invalid reference answers 400; a well-formed but\nunknown one matches nothing.\n",
 						"schema": {
 							"type": "string",
-							"maxLength": 263
+							"maxLength": 129
 						}
 					},
 					{ "$ref": "#/components/parameters/Cursor" },
@@ -1060,7 +1299,7 @@ const COMMANDS = deriveCommands({
 				"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": [] }],
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
 				"parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
 				"requestBody": {
 					"required": true,
@@ -1096,7 +1335,7 @@ const COMMANDS = deriveCommands({
 			"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",
+				"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 includes the\nassigned Category's id, name and slug, and excludes `download_count`\nand any caller-relative field, so a download never invalidates an\neditor's `If-Match`.\n",
 				"security": [
 					{},
 					{ "sessionCookie": [] },
@@ -1115,8 +1354,8 @@ const COMMANDS = deriveCommands({
 			},
 			"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",
+				"summary": "Change a Capability's description, visibility or Category.",
+				"description": "Omitted fields are left unchanged. `category` is three-state: omitted\nleaves the Category unchanged, `null` clears it, and a slug replaces it\nwith a live Category of the Capability's own Namespace. The change\napplies to every Version at once and publishes none. `kind`,\n`namespace` and `name` are immutable, so sending any of them returns\n400.\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, including the assigned Category's id, name\nand slug, and excluding `download_count` and caller-relative fields,\nso downloads do not cause spurious 412s.\n",
 				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
 				"parameters": [{ "$ref": "#/components/parameters/IfMatch" }],
 				"requestBody": {
@@ -1180,7 +1419,7 @@ const COMMANDS = deriveCommands({
 				"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": [] }],
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
 				"parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
 				"requestBody": {
 					"required": true,
@@ -1285,78 +1524,289 @@ const COMMANDS = deriveCommands({
 				"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",
+		"/api/v1/categories": {
+			"get": {
+				"operationId": "listCategories",
+				"summary": "List Categories as a usage view or one Namespace's full taxonomy.",
+				"description": "The usage view lists only Categories carrying at least one Capability\nthe caller may read, with `count` set to those readable Capabilities. It\nis readable anonymously, under the same visibility rules as\n`listCapabilities`; `view=usage` with `namespace` scopes it to that\nNamespace without requiring any management fact. The taxonomy view lists\none live Namespace's full taxonomy, including Categories with\n`count: 0`, and requires `can_create_in_namespace` there or Platform\nAdmin: an unknown or non-live Namespace answers 404, an anonymous\ncaller 401 and a caller with neither fact 403. A Platform Admin may read\na team or principal taxonomy to assign a Category, but `can_manage`\nstays the `can_manage_category` fact, so it is `false` there. Omit\n`view` to keep the namespace-inferred behavior: `namespace` asks for the\ntaxonomy, no `namespace` for the usage view. `q` is a case-insensitive\nsubstring of the name or slug.\nUsage rows are ordered by `count` descending, then Namespace name, then\nname; taxonomy rows by name. The response is not paginated: counts\nchange with Capability edits, so `truncated` reports that more\nCategories exist than `limit` instead of offering a cursor.\n`can_manage` reports whether the caller may create, rename or delete\nCategories of that Namespace: it is the server's `can_manage_category`\nfact in the taxonomy view, and always `false` in the usage view, where\nno single Namespace is governed.\n",
+				"security": [
+					{},
+					{ "sessionCookie": [] },
+					{ "bearerToken": [] }
+				],
+				"parameters": [
+					{
+						"name": "view",
+						"in": "query",
+						"description": "`usage` lists Categories carrying at least one readable Capability,\noptionally scoped by `namespace`. `taxonomy` lists one Namespace's\nfull taxonomy and requires `namespace`. Omitted, a `namespace`\nselects the taxonomy and no `namespace` selects the usage view.\n",
+						"schema": {
+							"type": "string",
+							"enum": ["usage", "taxonomy"]
+						}
+					},
+					{
+						"name": "namespace",
+						"in": "query",
+						"description": "With the taxonomy view, the live Namespace whose full taxonomy to\nlist. With the usage view, the Namespace its counts are scoped to.\n",
+						"schema": { "$ref": "#/components/schemas/Name" }
+					},
+					{
+						"name": "q",
+						"in": "query",
+						"description": "Case-insensitive text found in the name or slug. Empty means no filter.",
+						"schema": {
+							"type": "string",
+							"maxLength": 200
+						}
+					},
+					{
+						"name": "limit",
+						"in": "query",
+						"description": "The most Categories the response holds.",
+						"schema": {
+							"type": "integer",
+							"minimum": 1,
+							"maximum": 200,
+							"default": 100
+						}
+					}
+				],
+				"responses": {
+					"200": {
+						"description": "The matching Categories and their readable counts.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryList" } } }
+					},
+					"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": "createCategory",
+				"summary": "Create a Category in a Namespace the caller owns.",
+				"description": "Allowed for the Namespace owner: a Platform Admin for `system`, an\nEffective Team Admin for a Team's Namespace and the owning Principal for\na principal Namespace. The name is normalized and must be 1–32\ncharacters without a comma or a control character. `slug` is optional;\nwhen omitted the server derives it from the normalized name and answers\n400 if the name cannot form a valid slug. Both name and slug are unique\nwithin the Namespace, and a duplicate answers 409.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"requestBody": {
+					"required": true,
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCategoryRequest" } } }
+				},
+				"responses": {
+					"201": {
+						"description": "The created Category.",
+						"headers": { "Location": {
+							"description": "`/api/v1/categories/{id}`",
+							"schema": { "type": "string" }
+						} },
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } }
+					},
+					"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/capabilities/{capability_id}/versions/{version}/files": { "get": {
+			"operationId": "listCapabilityVersionFiles",
+			"summary": "List the entries of one Skill Version's package.",
+			"description": "The entries come from the package's ZIP central directory; no entry is\ndecompressed. They are returned as stored, including `__MACOSX/` and\n`.DS_Store` entries, and missing ancestor directories are synthesized\nwith `size` 0, `mode` `\"0755\"` and `is_dir` true. `mode` is the\nfour-digit octal permission bits the archive declares, `\"0644\"` for\nfiles and `\"0755\"` for directories when it declares none. Entries are\nsorted by `path` in byte order and the list is not paginated.\n\nAn MCP Version, a Version the caller cannot read, or a Capability with\nno such Version answers 404. A Skill package missing from storage or\nunreadable answers 500. Listing is not a download and leaves the\nCapability's `download_count` unchanged.\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
-				}
+			"parameters": [{ "$ref": "#/components/parameters/CapabilityID" }, {
+				"name": "version",
+				"in": "path",
+				"required": true,
+				"schema": { "$ref": "#/components/schemas/CalVer" }
 			}],
 			"responses": {
 				"200": {
-					"description": "The readable tags and their counts.",
-					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagList" } } }
+					"description": "Every entry of the package.",
+					"headers": { "Cache-Control": { "$ref": "#/components/headers/ContentCacheControl" } },
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageEntryList" } } }
 				},
 				"400": { "$ref": "#/components/responses/Problem" },
+				"401": { "$ref": "#/components/responses/Problem" },
+				"404": { "$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": [] }],
+		"/api/v1/capabilities/{capability_id}/versions/{version}/file": { "get": {
+			"operationId": "lookupCapabilityVersionFile",
+			"summary": "Return one entry of a Skill Version's package.",
+			"description": "`path` must equal an entry path exactly. It is never interpreted as a\nfilesystem path: a `..` segment, an absolute path, a backslash, a NUL\nbyte, a directory and an unknown name all answer 404. Nothing is\nextracted to disk.\n\n`Content-Length` is the size the central directory declares. The strong\n`ETag` is the quoted hex sha256 of the package digest, a NUL byte and\nthe entry path, so it is known before decompression and every package\nchange invalidates every entry; `If-None-Match` answers 304 with the\nsame tag. PNG, JPEG, GIF and WebP entries are served with their image\nmedia type, text-like entries (Markdown and common extensionless files\nsuch as `Dockerfile` and `LICENSE` included) as\n`text/plain; charset=utf-8`, and everything else, including SVG, HTML,\nXML, JavaScript and CSS, as `application/octet-stream` with\n`Content-Disposition: attachment`. Every response, including 304,\ncarries `X-Content-Type-Options: nosniff`.\n\nAn MCP Version, a Version the caller cannot read, or a Capability with\nno such Version answers 404. A Skill package missing from storage or\nunreadable answers 500. Reading one entry is not a download and leaves\nthe Capability's `download_count` unchanged.\n",
+			"security": [
+				{},
+				{ "sessionCookie": [] },
+				{ "bearerToken": [] }
+			],
 			"parameters": [
+				{ "$ref": "#/components/parameters/CapabilityID" },
 				{
-					"name": "actor_principal_id",
-					"in": "query",
-					"schema": {
-						"type": "string",
-						"format": "uuid"
-					}
+					"name": "version",
+					"in": "path",
+					"required": true,
+					"schema": { "$ref": "#/components/schemas/CalVer" }
 				},
 				{
-					"name": "action",
+					"name": "path",
 					"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",
+					"description": "An entry path exactly as listed by the files endpoint.",
+					"required": true,
+					"schema": { "type": "string" }
+				},
+				{
+					"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 entry's bytes.",
+					"headers": {
+						"ETag": { "$ref": "#/components/headers/ETag" },
+						"Cache-Control": { "$ref": "#/components/headers/ContentCacheControl" },
+						"Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" },
+						"X-Content-Type-Options": { "$ref": "#/components/headers/XContentTypeOptions" }
+					},
+					"content": {
+						"application/octet-stream": { "schema": {
+							"type": "string",
+							"format": "binary"
+						} },
+						"image/png": { "schema": {
+							"type": "string",
+							"format": "binary"
+						} },
+						"image/jpeg": { "schema": {
+							"type": "string",
+							"format": "binary"
+						} },
+						"image/gif": { "schema": {
+							"type": "string",
+							"format": "binary"
+						} },
+						"image/webp": { "schema": {
+							"type": "string",
+							"format": "binary"
+						} },
+						"text/plain": { "schema": {
+							"type": "string",
+							"format": "binary"
+						} }
+					}
+				},
+				"304": {
+					"description": "The caller's copy is current. No body.",
+					"headers": {
+						"ETag": { "$ref": "#/components/headers/ETag" },
+						"Cache-Control": { "$ref": "#/components/headers/ContentCacheControl" },
+						"X-Content-Type-Options": { "$ref": "#/components/headers/XContentTypeOptions" }
+					}
+				},
+				"400": { "$ref": "#/components/responses/Problem" },
+				"401": { "$ref": "#/components/responses/Problem" },
+				"404": { "$ref": "#/components/responses/Problem" },
+				"default": { "$ref": "#/components/responses/Problem" }
+			}
+		} },
+		"/api/v1/categories/{category_id}": {
+			"parameters": [{
+				"name": "category_id",
+				"in": "path",
+				"required": true,
+				"schema": {
+					"type": "string",
+					"format": "uuid"
+				}
+			}],
+			"patch": {
+				"operationId": "renameCategory",
+				"summary": "Rename a Category, keeping its immutable slug.",
+				"description": "Allowed for the same callers as `createCategory`. Only the display name\nchanges; the slug is immutable, so sending `slug` answers 400. A\nduplicate name in the same Namespace answers 409.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"requestBody": {
+					"required": true,
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameCategoryRequest" } } }
+				},
+				"responses": {
+					"200": {
+						"description": "The renamed Category.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } }
+					},
+					"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" }
+				}
+			},
+			"delete": {
+				"operationId": "deleteCategory",
+				"summary": "Delete an unused Category.",
+				"description": "Allowed for the same callers as `createCategory`. Deletion is physical.\nA Category referenced by a live Capability answers 409 with the in-use\ncount; references held by soft-deleted Capabilities are nulled by the\nforeign key and do not block.\n",
+				"security": [{ "sessionCookie": [] }, { "bearerToken": [] }],
+				"responses": {
+					"204": { "description": "The Category 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/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",
+							"category.created",
+							"category.renamed",
+							"category.deleted",
+							"cli.device_authorized",
+							"cli.device_denied",
+							"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",
@@ -1378,6 +1828,8 @@ const COMMANDS = deriveCommands({
 						"enum": [
 							"access_token",
 							"capability",
+							"category",
+							"device_authorization",
 							"principal",
 							"session",
 							"team"
@@ -1764,6 +2216,55 @@ const COMMANDS = deriveCommands({
 					"type": "string",
 					"format": "uuid"
 				}
+			},
+			"OAuthResponseType": {
+				"name": "response_type",
+				"in": "query",
+				"required": true,
+				"description": "Must be `code`.",
+				"schema": {
+					"type": "string",
+					"enum": ["code"]
+				}
+			},
+			"OAuthClientID": {
+				"name": "client_id",
+				"in": "query",
+				"required": true,
+				"schema": { "type": "string" }
+			},
+			"OAuthRedirectURI": {
+				"name": "redirect_uri",
+				"in": "query",
+				"required": true,
+				"description": "Must exactly match a URI registered for the client.",
+				"schema": {
+					"type": "string",
+					"format": "uri"
+				}
+			},
+			"OAuthState": {
+				"name": "state",
+				"in": "query",
+				"required": false,
+				"description": "Opaque value echoed on the client redirect.",
+				"schema": { "type": "string" }
+			},
+			"OAuthCodeChallenge": {
+				"name": "code_challenge",
+				"in": "query",
+				"required": true,
+				"schema": { "type": "string" }
+			},
+			"OAuthCodeChallengeMethod": {
+				"name": "code_challenge_method",
+				"in": "query",
+				"required": true,
+				"description": "Must be `S256`.",
+				"schema": {
+					"type": "string",
+					"enum": ["S256"]
+				}
 			}
 		},
 		"requestBodies": { "CreateAccessToken": {
@@ -1772,7 +2273,7 @@ const COMMANDS = deriveCommands({
 		} },
 		"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",
+				"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\nassigned Category's id, name and slug, excluding mutable counters like\na Capability's `download_count` and any caller-relative field. A\ndownload therefore never invalidates an editor's `If-Match`, and every\ncaller sees the same tag.\n",
 				"required": true,
 				"schema": { "type": "string" }
 			},
@@ -1780,6 +2281,16 @@ const COMMANDS = deriveCommands({
 				"description": "`private, no-store` when the Content is not public to anonymous\nreaders; absent for public Content.\n",
 				"required": false,
 				"schema": { "type": "string" }
+			},
+			"ContentDisposition": {
+				"description": "`attachment` carrying the entry's file name for types served as\n`application/octet-stream`; absent when the entry is served inline.\n",
+				"required": false,
+				"schema": { "type": "string" }
+			},
+			"XContentTypeOptions": {
+				"description": "Always `nosniff`.",
+				"required": false,
+				"schema": { "type": "string" }
 			}
 		},
 		"responses": {
@@ -1798,27 +2309,59 @@ const COMMANDS = deriveCommands({
 			"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" } } }
+			},
+			"OAuthError": {
+				"description": "An RFC 6749 error. `Cache-Control` is always `no-store`.",
+				"headers": { "Cache-Control": {
+					"description": "Always `no-store`.",
+					"schema": { "type": "string" }
+				} },
+				"content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } }
+			},
+			"OAuthProblem": {
+				"description": "An RFC 9457 problem detail. `Cache-Control` is always `no-store`.",
+				"headers": { "Cache-Control": {
+					"description": "Always `no-store`.",
+					"schema": { "type": "string" }
+				} },
+				"content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }
 			}
 		},
 		"schemas": {
 			"CreateAccessTokenRequest": {
 				"type": "object",
 				"required": ["name"],
-				"properties": { "name": {
-					"type": "string",
-					"minLength": 1,
-					"maxLength": 64
-				} },
+				"properties": {
+					"name": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 64
+					},
+					"audience": {
+						"type": "string",
+						"enum": ["management", "mcp"],
+						"default": "management",
+						"description": "The surface the token may authenticate. `management` (the default)\nworks against `/api/v1`; `mcp` works against Native MCP and is\nrejected by every `/api/v1` operation.\n"
+					}
+				},
 				"additionalProperties": false
 			},
+			"AccessTokenAudience": {
+				"type": "string",
+				"enum": ["management", "mcp"],
+				"description": "The surface the token authenticates. Each surface rejects the other's\ntokens.\n"
+			},
 			"AccessToken": {
 				"type": "object",
 				"required": [
 					"id",
 					"name",
 					"token_prefix",
+					"audience",
 					"created_at",
-					"last_used_at"
+					"last_used_at",
+					"expires_at",
+					"client_name"
 				],
 				"properties": {
 					"id": {
@@ -1830,6 +2373,7 @@ const COMMANDS = deriveCommands({
 						"type": "string",
 						"description": "The first 8 characters after `hng_`, for recognising a token. Not a credential."
 					},
+					"audience": { "$ref": "#/components/schemas/AccessTokenAudience" },
 					"created_at": {
 						"type": "string",
 						"format": "date-time"
@@ -1838,6 +2382,15 @@ const COMMANDS = deriveCommands({
 						"type": ["string", "null"],
 						"format": "date-time",
 						"description": "Recorded at most once every 5 minutes; null until first use."
+					},
+					"expires_at": {
+						"type": ["string", "null"],
+						"format": "date-time",
+						"description": "Null for static tokens, which never expire and are revoked instead."
+					},
+					"client_name": {
+						"type": ["string", "null"],
+						"description": "The OAuth client that obtained the token; null for static tokens."
 					}
 				}
 			},
@@ -1849,6 +2402,192 @@ const COMMANDS = deriveCommands({
 					"items": { "$ref": "#/components/schemas/AccessToken" }
 				} }
 			},
+			"OAuthClientRegistrationRequest": {
+				"type": "object",
+				"required": ["client_name", "redirect_uris"],
+				"properties": {
+					"client_name": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 100
+					},
+					"redirect_uris": {
+						"type": "array",
+						"minItems": 1,
+						"maxItems": 10,
+						"items": {
+							"type": "string",
+							"maxLength": 2048
+						}
+					},
+					"token_endpoint_auth_method": {
+						"type": "string",
+						"enum": ["none"],
+						"default": "none",
+						"description": "The only accepted value; omitted means `none`."
+					},
+					"grant_types": {
+						"type": "array",
+						"items": {
+							"type": "string",
+							"enum": ["authorization_code", "refresh_token"]
+						},
+						"default": ["authorization_code"],
+						"description": "Omitted means `[\"authorization_code\"]`; `refresh_token` may accompany it."
+					},
+					"response_types": {
+						"type": "array",
+						"items": {
+							"type": "string",
+							"enum": ["code"]
+						},
+						"default": ["code"],
+						"description": "Omitted means `[\"code\"]`."
+					}
+				},
+				"additionalProperties": false
+			},
+			"OAuthClientRegistration": {
+				"type": "object",
+				"required": [
+					"client_id",
+					"client_id_issued_at",
+					"client_name",
+					"redirect_uris",
+					"token_endpoint_auth_method",
+					"grant_types",
+					"response_types"
+				],
+				"properties": {
+					"client_id": {
+						"type": "string",
+						"description": "`hngc_` plus at least 20 characters."
+					},
+					"client_id_issued_at": {
+						"type": "integer",
+						"description": "Unix time in seconds."
+					},
+					"client_name": { "type": "string" },
+					"redirect_uris": {
+						"type": "array",
+						"items": { "type": "string" }
+					},
+					"token_endpoint_auth_method": {
+						"type": "string",
+						"enum": ["none"]
+					},
+					"grant_types": {
+						"type": "array",
+						"items": { "type": "string" }
+					},
+					"response_types": {
+						"type": "array",
+						"items": { "type": "string" }
+					}
+				}
+			},
+			"ExchangeOAuthTokenRequest": {
+				"type": "object",
+				"properties": {
+					"grant_type": {
+						"type": "string",
+						"enum": ["authorization_code", "refresh_token"]
+					},
+					"code": { "type": "string" },
+					"redirect_uri": { "type": "string" },
+					"client_id": { "type": "string" },
+					"code_verifier": { "type": "string" },
+					"refresh_token": { "type": "string" }
+				}
+			},
+			"OAuthToken": {
+				"type": "object",
+				"required": [
+					"access_token",
+					"token_type",
+					"expires_in",
+					"refresh_token"
+				],
+				"properties": {
+					"access_token": {
+						"type": "string",
+						"description": "An `hng_<value>` MCP token. Use it as `Authorization: Bearer <token>`."
+					},
+					"token_type": {
+						"type": "string",
+						"enum": ["Bearer"]
+					},
+					"expires_in": {
+						"type": "integer",
+						"description": "Access token lifetime in seconds."
+					},
+					"refresh_token": { "type": "string" }
+				}
+			},
+			"OAuthError": {
+				"type": "object",
+				"required": ["error", "error_description"],
+				"properties": {
+					"error": {
+						"type": "string",
+						"enum": [
+							"invalid_request",
+							"invalid_grant",
+							"unsupported_grant_type"
+						]
+					},
+					"error_description": { "type": "string" }
+				}
+			},
+			"OAuthAuthorizationPreview": {
+				"type": "object",
+				"required": ["client_name", "redirect_host"],
+				"properties": {
+					"client_name": { "type": "string" },
+					"redirect_host": {
+						"type": "string",
+						"description": "The host of the registered redirect URI; the URI itself is never exposed."
+					}
+				}
+			},
+			"OAuthAuthorizationDecision": {
+				"type": "object",
+				"required": ["redirect_to"],
+				"properties": { "redirect_to": {
+					"type": "string",
+					"description": "The client redirect carrying `code` or `error=access_denied`, plus `state`."
+				} }
+			},
+			"DecideOAuthAuthorizationRequest": {
+				"type": "object",
+				"required": [
+					"response_type",
+					"client_id",
+					"redirect_uri",
+					"code_challenge",
+					"code_challenge_method",
+					"decision"
+				],
+				"properties": {
+					"response_type": {
+						"type": "string",
+						"enum": ["code"]
+					},
+					"client_id": { "type": "string" },
+					"redirect_uri": { "type": "string" },
+					"state": { "type": "string" },
+					"code_challenge": { "type": "string" },
+					"code_challenge_method": {
+						"type": "string",
+						"enum": ["S256"]
+					},
+					"decision": {
+						"type": "string",
+						"enum": ["approve", "deny"]
+					}
+				},
+				"additionalProperties": false
+			},
 			"CreatedAccessToken": {
 				"type": "object",
 				"required": [
@@ -1938,6 +2677,168 @@ const COMMANDS = deriveCommands({
 				},
 				"additionalProperties": false
 			},
+			"CreateDeviceAuthorizationRequest": {
+				"type": "object",
+				"required": ["device_name", "token_name"],
+				"properties": {
+					"device_name": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 128,
+						"description": "The device name the CLI reports, shown to the approver."
+					},
+					"token_name": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 64,
+						"description": "The name of the Access Token approval would create."
+					}
+				},
+				"additionalProperties": false
+			},
+			"DeviceAuthorizationCode": {
+				"type": "object",
+				"required": [
+					"device_code",
+					"user_code",
+					"verification_uri",
+					"verification_uri_complete",
+					"expires_in",
+					"interval"
+				],
+				"properties": {
+					"device_code": {
+						"type": "string",
+						"description": "The credential the CLI polls with. Returned only here and stored as\na keyed digest.\n"
+					},
+					"user_code": {
+						"type": "string",
+						"description": "The short public code displayed as `XXXX-XXXX`."
+					},
+					"verification_uri": {
+						"type": "string",
+						"description": "Where the user approves the request."
+					},
+					"verification_uri_complete": {
+						"type": "string",
+						"description": "The verification URI with the user code already applied."
+					},
+					"expires_in": {
+						"type": "integer",
+						"description": "Seconds until the request expires. Always 900."
+					},
+					"interval": {
+						"type": "integer",
+						"description": "The minimum seconds between polls. Always 5."
+					}
+				},
+				"additionalProperties": false
+			},
+			"LookupDeviceAuthorizationRequest": {
+				"type": "object",
+				"required": ["user_code"],
+				"properties": { "user_code": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 32
+				} },
+				"additionalProperties": false
+			},
+			"PollDeviceAuthorizationRequest": {
+				"type": "object",
+				"required": ["device_code"],
+				"properties": { "device_code": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 128
+				} },
+				"additionalProperties": false
+			},
+			"ApproveDeviceAuthorizationRequest": {
+				"type": "object",
+				"required": ["user_code"],
+				"properties": { "user_code": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 32
+				} },
+				"additionalProperties": false
+			},
+			"DenyDeviceAuthorizationRequest": {
+				"type": "object",
+				"required": ["user_code"],
+				"properties": { "user_code": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 32
+				} },
+				"additionalProperties": false
+			},
+			"DeviceAuthorization": {
+				"type": "object",
+				"required": [
+					"device_name",
+					"source_ip",
+					"requested_at",
+					"token_name",
+					"expires_at",
+					"state"
+				],
+				"properties": {
+					"device_name": { "type": "string" },
+					"source_ip": { "type": "string" },
+					"requested_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"token_name": { "type": "string" },
+					"expires_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"state": {
+						"type": "string",
+						"enum": [
+							"pending",
+							"approved",
+							"denied",
+							"consumed"
+						],
+						"description": "The request's lifecycle state. Denied and consumed requests stay\nreadable so a reload shows the outcome.\n"
+					}
+				},
+				"additionalProperties": false
+			},
+			"DeviceAuthorizationToken": {
+				"type": "object",
+				"required": [
+					"token",
+					"token_id",
+					"token_prefix",
+					"name",
+					"principal"
+				],
+				"properties": {
+					"token": {
+						"type": "string",
+						"description": "The Access Token value. Returned exactly once, by the poll that\nconsumes the approval.\n"
+					},
+					"token_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"token_prefix": {
+						"type": "string",
+						"description": "The first eight random characters, for display."
+					},
+					"name": {
+						"type": "string",
+						"description": "The token name shown on the verification page."
+					},
+					"principal": { "$ref": "#/components/schemas/Principal" }
+				},
+				"additionalProperties": false
+			},
 			"Principal": {
 				"type": "object",
 				"required": [
@@ -2035,6 +2936,8 @@ const COMMANDS = deriveCommands({
 						"enum": [
 							"access_token",
 							"capability",
+							"category",
+							"device_authorization",
 							"principal",
 							"session",
 							"team"
@@ -2255,7 +3158,7 @@ const COMMANDS = deriveCommands({
 			},
 			"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"
+				"description": "Markdown, at most 1 MiB of UTF-8. Omitted or null means no README was\nattached; an empty string is kept as an empty README. A Skill Version\nwithout one reports its package's `SKILL.md` in place of a README.\n"
 			},
 			"MCPConfig": {
 				"type": "object",
@@ -2263,13 +3166,6 @@ const COMMANDS = deriveCommands({
 				"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": [
@@ -2288,11 +3184,9 @@ const COMMANDS = deriveCommands({
 					"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" }
+					"category": {
+						"type": "string",
+						"description": "A Category slug inside the target Namespace. Omit it or send an\nempty value for uncategorized; an unknown slug, or one owned by\nanother or a non-live Namespace, answers 400.\n"
 					},
 					"config": { "$ref": "#/components/schemas/MCPConfig" }
 				},
@@ -2318,12 +3212,11 @@ const COMMANDS = deriveCommands({
 					"visibility": { "$ref": "#/components/schemas/Visibility" },
 					"readme": {
 						"type": "string",
-						"description": "Markdown, at most 1 MiB of UTF-8. Omitted means no README."
+						"description": "Markdown, at most 1 MiB of UTF-8. Omitted means the package's\n`SKILL.md` is reported as the Version's README.\n"
 					},
-					"tags": {
+					"category": {
 						"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
+						"description": "A Category slug inside the target Namespace, sent as one multipart\nfield. Omit it or send an empty value for uncategorized; an unknown\nslug, or one owned by another or a non-live Namespace, answers 400.\n"
 					},
 					"package": {
 						"type": "string",
@@ -2337,11 +3230,11 @@ const COMMANDS = deriveCommands({
 				"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" }
+					"category": {
+						"description": "Three-state: omitted leaves the Category unchanged, `null` clears\nit, and a slug must name a live Category of this Capability's own\nNamespace. An unknown or foreign slug answers 400.\n",
+						"type": ["string", "null"],
+						"x-go-type": "json.RawMessage",
+						"x-go-type-skip-optional-pointer": true
 					},
 					"kind": {
 						"description": "Immutable; any value returns 400.",
@@ -2377,7 +3270,7 @@ const COMMANDS = deriveCommands({
 				"properties": {
 					"readme": {
 						"type": "string",
-						"description": "Markdown, at most 1 MiB of UTF-8. Omitted means no README."
+						"description": "Markdown, at most 1 MiB of UTF-8. Omitted means the package's\n`SKILL.md` is reported as the Version's README.\n"
 					},
 					"package": {
 						"type": "string",
@@ -2398,7 +3291,7 @@ const COMMANDS = deriveCommands({
 					"path",
 					"visibility",
 					"description",
-					"tags",
+					"category",
 					"download_count",
 					"current_version",
 					"created_at",
@@ -2432,11 +3325,9 @@ const COMMANDS = deriveCommands({
 					},
 					"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" }
+					"category": {
+						"description": "The assigned Category, or null when the Capability is uncategorized.",
+						"oneOf": [{ "$ref": "#/components/schemas/CategoryRef" }, { "type": "null" }]
 					},
 					"download_count": {
 						"type": "integer",
@@ -2455,32 +3346,120 @@ const COMMANDS = deriveCommands({
 					}
 				}
 			},
-			"TagCount": {
+			"CategoryRef": {
+				"type": "object",
+				"required": [
+					"id",
+					"name",
+					"slug"
+				],
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"name": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 32,
+						"description": "The Category's normalized display name."
+					},
+					"slug": {
+						"$ref": "#/components/schemas/Name",
+						"description": "The Category's immutable ASCII reference inside its Namespace."
+					}
+				},
+				"additionalProperties": false
+			},
+			"Category": {
 				"type": "object",
-				"required": ["name", "count"],
+				"required": [
+					"id",
+					"namespace",
+					"namespace_kind",
+					"name",
+					"slug",
+					"count"
+				],
 				"properties": {
-					"name": { "$ref": "#/components/schemas/Tag" },
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"namespace": { "$ref": "#/components/schemas/Name" },
+					"namespace_kind": { "$ref": "#/components/schemas/NamespaceKind" },
+					"name": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 32,
+						"description": "The normalized display name: trimmed and with internal whitespace\ncollapsed, with the caller's case preserved. Chinese names are\nsupported.\n"
+					},
+					"slug": {
+						"$ref": "#/components/schemas/Name",
+						"description": "The immutable ASCII reference of the Category inside its Namespace.\n"
+					},
 					"count": {
 						"type": "integer",
 						"format": "int64",
-						"minimum": 0
+						"minimum": 0,
+						"description": "The number of Capabilities carrying the Category that the caller may\nread. It is 0 in the Namespace taxonomy when no readable Capability\nuses the Category.\n"
 					}
 				}
 			},
-			"TagList": {
+			"CategoryList": {
 				"type": "object",
-				"required": ["items", "truncated"],
+				"required": [
+					"items",
+					"truncated",
+					"can_manage"
+				],
 				"properties": {
 					"items": {
 						"type": "array",
-						"items": { "$ref": "#/components/schemas/TagCount" }
+						"items": { "$ref": "#/components/schemas/Category" }
 					},
 					"truncated": {
 						"type": "boolean",
-						"description": "More tags exist than the requested `limit`."
+						"description": "More Categories exist than the requested `limit`."
+					},
+					"can_manage": {
+						"type": "boolean",
+						"description": "Whether the caller may create, rename or delete Categories of the\nlisted Namespace. It is the authoritative `can_manage_category`\nfact in the Namespace view and always `false` in the usage view,\nwhere no single Namespace is named.\n"
 					}
 				}
 			},
+			"CreateCategoryRequest": {
+				"type": "object",
+				"required": ["namespace", "name"],
+				"properties": {
+					"namespace": {
+						"$ref": "#/components/schemas/Name",
+						"description": "The name of the live Namespace that will own the Category."
+					},
+					"name": {
+						"type": "string",
+						"minLength": 1,
+						"maxLength": 64,
+						"description": "The display name. The server trims it and collapses internal\nwhitespace, preserving case, then requires 1–32 characters without\na comma or a control character.\n"
+					},
+					"slug": {
+						"$ref": "#/components/schemas/Name",
+						"description": "Optional immutable slug. Omitted means derive it from the normalized\nname; a name that cannot form a valid slug then answers 400.\n"
+					}
+				},
+				"additionalProperties": false
+			},
+			"RenameCategoryRequest": {
+				"type": "object",
+				"required": ["name"],
+				"properties": { "name": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 64,
+					"description": "The new display name, normalized like `CreateCategoryRequest.name`.\nSending a `slug` property answers 400: the slug is immutable, and\nthe server rejects the property even though it is not declared.\n"
+				} },
+				"additionalProperties": false
+			},
 			"CapabilityList": {
 				"type": "object",
 				"required": ["items", "next_cursor"],
@@ -2527,7 +3506,11 @@ const COMMANDS = deriveCommands({
 					"version": { "$ref": "#/components/schemas/CalVer" },
 					"readme": {
 						"type": ["string", "null"],
-						"description": "The Version's Markdown README, or null when it has none."
+						"description": "The Version's Markdown README. A Skill Version that was published\nwithout one reports the package's `SKILL.md`, or null when the\nmanifest cannot be read as text within the README limit.\n"
+					},
+					"readme_from_manifest": {
+						"type": "boolean",
+						"description": "True when `readme` was derived from the package's `SKILL.md`\nbecause the Version has no attached README. Omitted otherwise.\n"
 					},
 					"created_at": {
 						"type": "string",
@@ -2596,6 +3579,53 @@ const COMMANDS = deriveCommands({
 				],
 				"additionalProperties": false
 			},
+			"PackageEntry": {
+				"type": "object",
+				"description": "One entry of a Skill package's ZIP central directory.",
+				"properties": {
+					"path": {
+						"type": "string",
+						"description": "The entry path, without a trailing slash."
+					},
+					"size": {
+						"type": "integer",
+						"format": "int64",
+						"minimum": 0,
+						"description": "The declared uncompressed size; 0 for a directory."
+					},
+					"mode": {
+						"type": "string",
+						"pattern": "^[0-7]{4}$",
+						"description": "Four-digit octal permission bits, such as `\"0644\"`."
+					},
+					"is_dir": {
+						"type": "boolean",
+						"description": "Whether the entry is a directory."
+					}
+				},
+				"required": [
+					"path",
+					"size",
+					"mode",
+					"is_dir"
+				],
+				"additionalProperties": false
+			},
+			"PackageEntryList": {
+				"type": "object",
+				"required": ["items"],
+				"properties": {
+					"items": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/PackageEntry" }
+					},
+					"default_path": {
+						"type": "string",
+						"description": "The entry the Package Browser selects by default: `SKILL.md` at the\npackage root or inside its single top-level directory. Omitted when\nthe package has none.\n"
+					}
+				},
+				"additionalProperties": false
+			},
 			"VersionList": {
 				"type": "object",
 				"required": ["items", "next_cursor"],
@@ -2925,7 +3955,7 @@ function workflowCatalog() {
 		},
 		{
 			name: "auth status",
-			summary: "Show credential source, server, principal and token prefix",
+			summary: "Show credential source, server, principal, token prefix and audience",
 			group: "auth",
 			args: [],
 			flags: [{
@@ -2941,7 +3971,11 @@ function workflowCatalog() {
 			summary: "Print the access token to stdout and nothing else",
 			group: "auth",
 			args: [],
-			flags: [],
+			flags: [{
+				name: "audience",
+				type: "string",
+				description: "management prints the stored token; mcp mints a new MCP token that can read and write the catalog content you have access to"
+			}],
 			destructive: false,
 			dryRun: false
 		},
@@ -3037,10 +4071,9 @@ function workflowCatalog() {
 					description: "Markdown file to attach"
 				},
 				{
-					name: "tag",
+					name: "category",
 					type: "string",
-					repeatable: true,
-					description: "Capability tag"
+					description: "Category slug in the target namespace (create only)"
 				},
 				{
 					name: "new",
@@ -3119,10 +4152,9 @@ function workflowCatalog() {
 					description: "Markdown file to attach"
 				},
 				{
-					name: "tag",
+					name: "category",
 					type: "string",
-					repeatable: true,
-					description: "Capability tag"
+					description: "Category slug in the target namespace (create only)"
 				},
 				{
 					name: "new",