docs(api): sync API reference with the b3 router

[ArnobKumarSaha]

Adds tooling to diff the b3 API server against docs/platform/api, and applies the drift the first run found.

Tooling

hack/api-doc-sync/, driven by the /api-docs-sync slash command (.claude/commands/api-docs-sync.md). Python 3 stdlib only, except refresh_reference.py which needs PyYAML.

Script	Purpose
extract_routes.py	Parses b3's macaron registrations into a flat route table. Walks the call graph from RegisterRoutes / RegisterMarketplaceServiceRoutes, so a helper called inside m.Group("/user", …) gets the /user prefix. Handles group nesting + group middlewares, gofmt-wrapped m.Combo(…).Get().Post() chains, bound payload types, inline comments. Currently 547 routes.
compare.py	Three-way diff: routes ↔ md pages ↔ openapi.yaml. Resolves the heading conventions these pages use — page-declared roots, PUT · PATCH /x, | POST/GET/DELETE |, /api/v1-prefixed table cells, and abbreviated .../kubeDb/views/x headings.
refresh_reference.py	Re-inlines openapi.yaml as JSON into reference/api.html (window.__SPEC__) and updates its paths/operations subtitle. That file was hand-maintained with no generator.

Corrections

• billing-dashboard/user-dashboard.md had every path wrong. It documented /dashboard/clusters/*, but registerBillingDashboardUserAPIs is called from inside the /user group (routers/api/v1/user.go:66-68) while registering /dashboard/clusters (dashboard.go:70), so the served prefix is /user/dashboard/clusters. Renamed the 10 headings and the 9 matching openapi.yaml paths.
• The same endpoints require view:licensed_clusters, not view:contracts; the two /events routes additionally require view:event_resources.
• /healthz and /.well-known/openid-configuration were documented at the host root. Both are registered on the accounts router (routers/routes/routes.go:227-231), which is mounted at /accounts (cmd/api.go:125, AccountsSubURL = "/accounts"). The page's own "Verified 200" note recorded the console SPA catch-all, so it never proved the handler existed. Also replaced the OIDC discovery example with the actual template output.

Newly documented (md + openapi.yaml)

• GET/POST/PUT/DELETE /orgs/{orgname}/auth-source — the org SSO auth source
• GET/POST/DELETE /orgs/{orgname}/subscription
• GET /user/login-method (public), GET /user/orgs, GET /user/inbox/subscriptions
• POST /user/deploy/orders plus its render/manifest, render/resources, helm3, yaml routes — replacing a placeholder that deferred to the source
• GET /clusters/{owner}/{cluster}/namespaces/{namespace}/resources
• the ui.kubedb.com databaseconfigurations raw passthrough
• GET /dashboard/monthly-summary/{resourceType}

8 new schemas, 13 new spec paths. subscriptions.md also gained the per-verb authorization checks it was missing (subscribe:cluster|namespace|resource, editor vs. viewer).

Verification

• compare.py end state: code→md 1, code→openapi 1, openapi→code 0. The single entry both times is ANY /*, the /api/v1 catch-all 404 handler — not an endpoint.
• openapi.yaml parses and every $ref resolves; 456 paths / 544 operations; reference/api.html regenerated to match.
• liche -p -h -l -s clean on every changed page.
• The remaining advisory md→code entries are all page-relative overview-table cells, curl examples with concrete values, or {history,status}-style cells — no genuine staleness.

Request/response shapes were derived from the handlers and bound payload types, not guessed. No > **Verified:** notes were added, since nothing here was exercised against a live deployment.

[github-actions]

Visit the preview URL for this PR (updated for commit 9e6bcde):

https://kubedb-v2-hugo--pr153-arnob-api-docs-rik4xa4n.web.app

_{(expires Thu, 10 Sep 2026 10:29:30 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: 0f29ae8ae0bd54a99bf2b223b6833be47acd5943}