hue

Philips Hue

Use this skill for Philips Hue Bridge lighting inspection and guarded control. The primary path is local HTTPS to the Hue Bridge CLIP v2 API. Use the Hue Remote API only when the operator explicitly needs off-LAN control or local bridge access is unavailable.

Safety Rules

1. Use skills/hue/hue.cjs for every supported Hue request shape. Do not handcraft CLIP v2 URLs or JSON bodies when the helper supports the action.
2. Read current light, room, zone, and scene state before changing lights.
3. Treat local reads as green, local light/group/scene/behavior changes as amber, off-LAN Remote API calls as amber, and bridge configuration writes as red.
4. For amber/red operations, use the helper to build the request shape, explain the target and expected effect, and stop for explicit operator approval before sending the emitted httpRequest through the gateway.
5. Include the target light, grouped light, room, scene, behavior, bridge id, action, and expected physical effect in approval text.
6. Never paste the Hue application key, OAuth client secret, or remote token into chat. The helper emits secretHeaders or <secret:...> placeholders for gateway-side resolution.
7. Hue Bridge certificates are self-signed by default. The helper marks local bridge HTTPS requests with a scoped allowSelfSignedTls flag for the gateway http_request proxy. Do not use a blanket insecure TLS bypass.
8. If a live call returns 401 or unauthorized_user, stop after that first failed call and re-link the bridge with the link-button flow.
9. In chat sessions, do not diagnose Hue runtime config by running hybridclaw env list, hybridclaw secret list, or other local CLI commands from bash; those commands can inspect the wrong runtime or fail because of the host Node version. Use gateway http_request errors and any /env show or /secret list output the operator provides.
10. If HUE_BRIDGE_HOST is configured and HUE_APPLICATION_KEY is missing, say only that the application key is missing. Do not ask the operator to find the bridge IP again. Ask them to press the physical link button, then build node skills/hue/hue.cjs --format json bridge link --app-name hybridclaw --instance-name lab, send the emitted httpRequest, and store the returned Hue credential secret through the helper-emitted captureResponseFields.
11. When linking after the operator presses the bridge button, run bridge status first. If the live status result reports linkbutton: true, immediately run bridge link without --host. If it reports linkbutton: false, tell the operator that the configured bridge did not report an active button press and ask them to press and release the physical link button once, then retry immediately. If linkbutton is absent, do not treat that as proof the button is inactive; modern bridge config responses can omit the field.
12. When running the link request itself, do not pass --host unless the operator explicitly provides a new override URL in the same turn. The default link request must use <env:HUE_BRIDGE_HOST> so the gateway resolves the env-store value.
13. If the operator shows /env show HUE_BRIDGE_HOST, treat that value as the current configured bridge URL. If a failed request used any other host, report that the helper was called with the wrong host and retry the same operation with no --host override.
14. If HUE_BRIDGE_HOST is missing, first reuse an exact Hue Bridge URL from current context or workspace memory when one is present. Ask the operator to find the bridge IP only when no exact URL is available.
15. If a gateway http_request error says Stored secret HUE_APPLICATION_KEY is not set, treat HUE_BRIDGE_HOST as already resolved for that request. Do not say the bridge host may be missing, do not tell the operator to run hybridclaw env set, and do not repeat the same read calls. Switch directly to the link-button setup path in rule 10.
16. If a private-host or gateway policy denial blocks a local bridge request, first inspect the current workspace network policy. Managed read-only LAN access already allows GET reads to RFC1918 hosts, and managed read-write LAN access allows the supported methods. If either managed LAN mode covers the attempted Hue request, report that mismatch as a gateway policy-evaluation bug instead of adding another rule. Do not edit policy by hand, do not add broad bridge rules, and do not tell the operator a gateway restart is required; workspace network policy is read per request.
17. If a local Hue request fails with a certificate verification or self-signed TLS error, do not ask for HUE_BRIDGE_HOST again, do not suggest plain HTTP on port 80, and do not invent a URL auth route or workspace policy setting for TLS. Re-run the exact helper-emitted httpRequest with allowSelfSignedTls: true; if that field is absent, rebuild the request with skills/hue/hue.cjs.