docs(api): daily audit 2026-09-10 — add Explore query + Prometheus label values, repair catalog accordions

[flashduty]

What this is

Daily api-review run (--mode generate --scope all --auto) for 2026-09-10, against fc-pgy@63afa2fb and flashduty-docs@b1e3f8da (current main).

This supersedes #377, which can no longer merge: main moved under it (mergeStateStatus: DIRTY) when #379 retired the v1 alert-rule endpoints and published the public v2 contract (e3bc1ef), plus #380/#381/#382. #377 had no review comments or reviews; its delta is carried forward here unchanged, rebased onto today's main. #377 will be closed and its branch deleted.

Registry vs spec delta

• public registry rows (auth == "all", path not /event/push/*, module not hidden): 339
• committed spec operations before this PR: 337
• only one module diverged: Monitors

Module	Added	Updated	Removed
Monitors	2	0	0
On-call	0	0	0
Platform	0	0	0
RUM	0	0	0
AI SRE	0	0	0

Added operations

Both rows are Auth: "all" in fc-pgy/logic/api/api_test.go at 63afa2fb:

1. POST /monit/query/explore — monit-read-query-explore, tag Monitors/Diagnostics.
   Registry row logic/api/api_test.go:472 (query:read:explore, Qps:100 AQps:16 AQpm:100). Backend route monit-webapi/router/router.go:39 (exploreHTTPAccess("public")), handler monit-webapi/router/router_explore.go:216 (exploreQuery).
   Request/response shapes verified against monit-webapi/pkg/exploreprotocol/dto.go (HTTPQuery: datasource_id/expr/args/execution; HTTPExecution: kind/from_ms/to_ms/max_data_points/min_step_seconds/step_seconds) and pkg/exploreprotocol/testdata/explore_result_contract_golden.json (format: explore_result.v1; kind ∈ frames/samples/logs; frames[].kind ∈ table/time_series; fields[].type ∈ string/float/time; entries[].timestamp_ns; applied_limit; has_more; execution.effective_step_seconds).
   Permission claim verified: query:read:explore is a factor of permission id 3008 Datasources Read / class Datasources, scope monit (fc-pgy/logic/permission/permission_test.go:1652-1667).

2. GET /monit/prometheus/api/v1/label/{label_name}/values — monit-prometheus-read-label-values, tag Monitors/Data sources.
   Registry row logic/api/api_test.go:466 (prometheus:read:labelValues). Backend route monit-webapi/router/router.go:264 → promProxy (router/router_prom.go:44). Not permission-gated: the factor appears only in api_test.go, never in permission_test.go, so "any valid app_key" is accurate.

Review attention: op 2 is not envelope-shaped

promProxy returns the data source's native Prometheus JSON (router_prom.go:40-44 documents this explicitly: "这个方法是代理的时序库的返回结果，其 response 结构需要遵从时序库的返回结构"), requires an X-DSID header, and returns pre-flight failures as non-200 text/plain bodies. It is documented truthfully (native response schema, required X-DSID header parameter, text/plain 400/500/503). It is the only non-envelope operation in the Monitors specs. If the product decision is that this route should not be in the public reference, drop the second path plus its nav/catalog row — op 1 stands on its own.

Registry inconsistency found (upstream, not fixed here)

The registry spells the path parameter :label_name (api_test.go:466) but the backend gin route is :labelname (router.go:264), and the sibling Loki row uses :labelname (api_test.go:459). The public path is unaffected (the placeholder name is cosmetic mid-segment) and the docs follow the registry per scope rule, but fc-pgy should normalise the row. Flagged, not silently "corrected".

Navigation + catalog reconciliation

Adding an operation is not enough — a path absent from the docs.json pages allow-list never renders:

• docs.json: both paths registered in the zh (诊断分析 / 告警数据源) and en (Diagnostics / Data sources) Monitors groups.
• {en,zh}/openapi/api-catalog.mdx: both rows added; accordion structure repaired — main carried <Accordion title="Monitors (40 endpoints)"> wrapping 64 rows (23 Monitors + 41 RUM) with the RUM accordion missing entirely, and a header total of 339 against 337 real rows. Now: Monitors (25), RUM (41) restored before Facets / RUM 自定义字段, header 339 = 339 rows.

Final counts, all self-consistent: 193 + 25 + 41 + 53 + 27 = 339.

Deliberately not re-added

Eleven rows left the registry since #377's baseline; none of them are in main's specs, so they are already absent from the docs and this PR re-adds nothing:

• POST /monit/query/diagnose, POST /monit/rule/counter/status, POST /monit/store/ruleset/{create,delete,info,list,update} — retired backend-side (monit-webapi/router/router_explore_test.go TestRetiredRoutesReturnNotFound), removed from docs by f1790df.
• POST /monit/rule/{info,create,update}, POST /monit/rule/counter/node — retired and replaced by the v2 contract, already handled on main by e3bc1ef (docs(monit): retire v1 alert rule endpoints, document public v2 contract #379).

Unresolved

• POST /monit/rule/dstypes — was carried from HEAD as an unresolved row on 2026-09-07; main has since dropped it (e3bc1ef). Nothing to carry today.
• mapping.yaml gaps — /status-page/* (registry provider status-page, mapping says statuspage), /calendar/* (registry pgy, mapping event), /route/*, /rum/data|field|resource/*, /monit/query/* have no scope entry. None produced drift today (every such path is already in the specs); the audit classified by path segment to confirm that.
• Monitors/Monitor utilities tag still has 0 operations, leaving an empty "Monitor utilities" / "通用工具" section in both catalogs. Pre-existing, outside this delta, left untouched.

Examples

No dev-API capture was possible in this environment (no credential access), so all new request/response examples are constructed from the Go types and the explore-protocol golden fixtures — realistic data source IDs, expressions, labels, and epoch timestamps, no "string" placeholders. Examples are contract-checked against explore_result_contract_golden.json, not invented.

Validation

• python3 scripts/lint_openapi.py → OK: 12 spec files, no violations
• all four touched spec files parse; paths: monitors 25 (was 23), consolidated 339 (was 337)
• deep compare vs HEAD: every spec section other than paths/components.schemas is byte-identical; paths and schemas show 0 removed, 0 modified — pure addition, no key reordering
• spec diff is 588 +/0 - per file (identical shape to docs(api): daily audit 2026-09-09 — add Explore query + Prometheus label values, fix catalog counts #377's)
• EN/ZH structural parity verified for both new operations and all 10 new schemas (only tags and human text differ)
• every Unix-epoch field description carries Unix/epoch/millisecond (checked mechanically over all 10 new schemas)
• every new leaf property has a description; both operations have requestBody + responses.200 examples
• coverage: 339 spec ops, 0 missing from docs.json, 0 missing from either catalog, 0 extra; every accordion declared count equals its actual row count
• mint broken-links could not be run — no Node/Mintlify CLI in this environment

Process note

The team knowledge pack still lacks runbooks/api-review-daily.md and runbooks/api-review-apply-patches.py, which this automation references (reported since 2026-08-14). The skill's generate_openapi.py therefore carries no baseline-fidelity/key-order patch, so this run did not perform a full regeneration: it rebuilt strictly from git show HEAD:, appended only the delta, and verified byte-level baseline fidelity by deep comparison instead.