From 5b4ccffcb80f5f29262acc9eaa750916fad7026f Mon Sep 17 00:00:00 2001
From: btwshivam <shivam200446@gmail.com>
Date: Fri, 29 May 2026 07:47:44 +0530
Subject: [PATCH] docs(openapi): add /v1/onboarding/health to spec
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Backend PR optiqor/optiqor#41 adds the funnel-position + blockers
endpoint. Without the spec entry the openapi-parity gate fails on
that PR — CI requires every Go route to appear in the spec.

Schema is intentionally `additionalProperties: true` for now; the
blockers + service-health hints fields will tighten once they
stabilise post-design-partner.

Signed-off-by: btwshivam <shivam200446@gmail.com>
---
 docs/api/openapi.yaml | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
index 7dba760..922858f 100644
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -412,6 +412,28 @@ paths:
         "401": { description: tenant context missing }
         "413": { description: body exceeds 4 KiB cap }
 
+  /v1/onboarding/health:
+    get:
+      tags: [onboarding]
+      summary: Per-tenant onboarding funnel position plus actionable blockers.
+      description: |
+        Shareable with the customer. Returns the current Stage + reached
+        timestamps + a `blockers[]` list of next actions, plus surface
+        hints (agent online, GitHub App installed, Prometheus reachable)
+        the CSM team and the in-app banner consume to nudge the right
+        step. PR #41.
+      security:
+        - tenantHeader: []
+        - bearerAuth: []
+        - sessionCookie: []
+      responses:
+        "200":
+          description: onboarding health envelope
+          content:
+            application/json:
+              schema: { type: object, additionalProperties: true }
+        "401": { description: tenant context missing }
+
   /v1/onboarding/preflight:
     post:
       tags: [onboarding]