docs(openapi): declare spec endpoint management auth (#11299)

Validated on a 3-PR combined board: openapi-security-tiers 1/1 within the board's 20/20, typecheck:core clean, gates within baseline. Declares GET /api/openapi/spec's real ManagementSessionAuth contract (conditional on requireLogin) — no runtime behavior change, just the doc catching up. Closes #10851. Thank you @RaviTharuma!

changelog.d/fixes/10851-openapi-spec-auth-contract.md

@@ -0,0 +1 @@
+- Document the conditional management authentication and 401/403 responses for `GET /api/openapi/spec`.

docs/openapi.yaml

@@ -6866,7 +6866,11 @@ paths:
         Returns a structured JSON catalog parsed from this `openapi.yaml`,
         including info, servers, tags, schemas, and a flat list of endpoints
         (method, path, tags, summary, security, parameters, responses).
-        Used by the in-app API explorer.
+        Used by the in-app API explorer. When `requireLogin` is enabled, this
+        management endpoint requires an authenticated dashboard session;
+        otherwise it is available without authentication.
+      security:
+        - ManagementSessionAuth: []
       responses:
         "200":
           description: Parsed OpenAPI catalog
@@ -6920,6 +6924,10 @@ paths:
                       type: string
         "404":
           description: openapi.yaml file not found on disk
+        "401":
+          $ref: "#/components/responses/ManagementAuthenticationRequired"
+        "403":
+          $ref: "#/components/responses/ManagementInvalidToken"
         "500":
           description: Failed to parse OpenAPI spec
 

skills/cli-mcp/SKILL.md

@@ -75,76 +75,3 @@ omniroute mcp call <tool> [argsJson]
 ```bash
 omniroute mcp scopes
 ```
-
-### `mcp tools`
-
-**Example:**
-
-```bash
-omniroute mcp tools
-```
-
-### `mcp list`
-
-**Flags:**
-
-- `--scope <s>`
-
-**Example:**
-
-```bash
-omniroute mcp list
-```
-
-### `mcp info <name>`
-
-**Example:**
-
-```bash
-omniroute mcp info <name>
-```
-
-### `mcp schema <name>`
-
-**Flags:**
-
-- `--io <kind>`
-
-**Example:**
-
-```bash
-omniroute mcp schema <name>
-```
-
-### `mcp audit`
-
-**Example:**
-
-```bash
-omniroute mcp audit
-```
-
-### `mcp tail`
-
-**Flags:**
-
-- `--follow`
-- `--limit <n>`
-
-**Example:**
-
-```bash
-omniroute mcp tail
-```
-
-### `mcp stats`
-
-**Flags:**
-
-- `--period <p>`
-
-**Example:**
-
-```bash
-omniroute mcp stats
-```

tests/unit/openapi-security-tiers.test.ts

@@ -34,6 +34,21 @@ test("every x-loopback-only path matches a LOCAL_ONLY prefix in routeGuard.ts",
   }
 });
 
+test("GET /api/openapi/spec documents its conditional management auth contract", () => {
+  const operation = paths["/api/openapi/spec"]?.get;
+
+  assert.deepEqual(operation?.security, [{ ManagementSessionAuth: [] }]);
+  assert.match(operation?.description ?? "", /When `requireLogin` is enabled/);
+  assert.equal(
+    operation?.responses?.["401"]?.$ref,
+    "#/components/responses/ManagementAuthenticationRequired"
+  );
+  assert.equal(
+    operation?.responses?.["403"]?.$ref,
+    "#/components/responses/ManagementInvalidToken"
+  );
+});
+
 test("every x-always-protected path matches ALWAYS_PROTECTED_API_PATHS in routeGuard.ts", () => {
   for (const [pathStr, methods] of Object.entries(paths)) {
     if (!methods || typeof methods !== "object") continue;