Document research parameter applicability; add series parameter

[ochlocracy]

summary

Encodes cross-parameter dependency rules for GET /research/{ticker}/{metric} directly in the OpenAPI spec via custom extensions (Option A from the proposal), so clients such as the interactive URL builder can grey out inapplicable controls. Applicability was derived from the API implementation's actual request routing, not the original proposal text (several of its claimed rules were inaccurate).

extensions added

• x-applicable_views (parameter level) — allowlist of views (skew/term/surface) where the parameter takes effect; omitted = all views.
• x-chart_only (parameter level) — parameter has no effect when format is json or csv.
• x-dedicated_metrics (operation level) — metrics (max_pain, parity, put_call_parity, gamma_flip) that render a fixed chart, ignore view, and support only a listed subset of parameters.

Semantics and the full applicability matrix are documented in docs/research-parameter-applicability.md.

other changes

• Added the missing series query parameter (term-view series grouping: moneyness, strikes, deltas) to the spec and README.
• Added descriptions and server defaults to all research query parameters.
• Validation fix: /{ticker}/orderflow/{category} referenced #/components/schemas/category_orderflow directly in its parameters list (invalid — parameter objects require name/in). Replaced with a new orderflow_category_in_path component parameter following the existing *_category_in_path convention. The spec now passes OpenAPI 3.0.1 validation; previously it did not.
• Regenerated latest/gexbot.spec3.json from the YAML. This also picks up a previously unsynced websocket example value (state_greeks_zero -> state_greeks for the SOXL_state_gamma_20260717 example).

behavior note

The API silently ignores inapplicable or invalid optional parameters and applies defaults — it does not return 400 for bad combinations. The new operation description states this explicitly.

flagged, intentionally not changed

• volatility_trigger in the research_metric enum is rejected by the API (the metric map only accepts gamma_flip / vol_trigger); requests with it 400. Needs an owner decision: remove it from the enum or add the alias server-side.
• moneyness_filter also accepts undocumented delta-based values (d10/d15/d20/d25); left out of the public spec deliberately, consistent with the earlier removal of chart_type/plotly.

🤖 Generated with Claude Code