v2.5.0 — Kelvin white balance (color_temperature)

Highlights

color_temperature(kelvin, intensity?, groups?) — agents and operators can now speak in the white-balance terms studio video, photography, and theatre actually use. "Set the key to 3200K tungsten." "Fill at 5600K daylight." "Candlelit mood at 1900K."

The control server resolves Kelvin to the right channel mix automatically based on which color roles each fixture exposes. MCP tool catalog grows from 31 → 32.

Closes #6.

Strategy per fixture type

Dispatch is driven by the existing .qxf role parser — no manual configuration.

WWA / tungsten fixtures (warm + cool, optional amber)

• Linear mix between warm and cool channels by Kelvin position
• Below 2700K we taper warm → amber so candle-warm (~1800K) reads correctly on fixtures with an amber channel
• Anchors: 2700K = pure warm, 6500K = pure cool

RGB / RGBA / RGBW fixtures

• Tanner Helland's CCT-to-RGB approximation drives r/g/b channels
• RGBW additionally pushes the white channel at full intensity so cool whites don't read as blue
• RGBA reinforces amber below ~3500K to handle the warm range without a dedicated warm channel

White-only and dimmer-only fixtures

• Can't express CCT — driven at intensity only, with a per-fixture note in the response explaining why

Kelvin range: clamped to 1800–10000K (candle → overcast sky).

Reference points

Kelvin	Reference	Approx tint
1800K	Candle / firelight	#ff7e00
2700K	Incandescent bulb	#ffa757
3200K	Tungsten studio key	#ffb87b
4000K	Cool-white fluorescent	#ffceA6
5600K	Daylight	#ffefe1
6500K	Pure white	#fffefa
7500K	Overcast / north-window	#dde6ff
10000K	Open sky	#cadaff

Composability

• With batch_action: create_group + color_temperature in one round trip
• Sets up palette (#7) — that becomes a thin batch dispatcher over mixed color_temperature + adjust_color calls

Response shape

{
  "success": true,
  "kelvin": 3200.0,
  "rgb": [255, 184, 123],
  "fixtures": [
    {
      "id": 0,
      "name": "SlimPAR Pro W",
      "strategy": "wwa",
      "applied": { "warm": 220, "cool": 35, "amber": 0 }
    },
    {
      "id": 3,
      "name": "SlimPAR 56",
      "strategy": "rgb",
      "applied": { "red": 255, "green": 184, "blue": 123 }
    }
  ]
}

Per-fixture strategy + applied channel values come back in the response so agents can introspect what actually happened.

Upgrade

git pull
./lightsctl.sh control-restart   # picks up the new action
./lightsctl.sh mcp-restart       # picks up the new MCP tool

No package dependency changes.

Compatibility

• No breaking changes. Every existing endpoint and MCP tool continues to behave identically.
• color_temperature is a new dispatcher arm in execute_lighting_action, reachable via the existing POST /api/action endpoint and the new MCP tool.

Documentation

• docs/MCP_SERVER.md — color_temperature added to the action table
• docs/CONTROL_SERVER_ARCHITECTURE.md — valid actions list updated
• mcp-server/README.md + root README.md — tool lists refreshed
• Wiki MCP-Server.md updated
• Marketing site: CueSheet cues 002/003 now demonstrate 3200K tungsten / 5600K daylight, AiConversation opens with a compound create_group + color_temperature(3200) exchange, new FAQ entry on Kelvin control

Follow-up

Remaining Tier 2: #4 (chases), #5 (strobe), #7 (palette).
Remaining Tier 3: #8 (scheduling), #10 (SSE event stream), #11 (multi-workspace), #12 (audio-reactive).