/hue

name: hue
description: "Read and control Philips Hue Bridge lighting installations through local CLIP v2 or the Hue Remote API with SecretRef-backed credentials and guarded lighting changes."
user-invocable: true
requires:
  bins:
    - node
config_variables:
  - id: hue-bridge-host
    env: HUE_BRIDGE_HOST
    required: true
    scope: "Local Hue Bridge HTTPS base URL used in gateway http_request URLs"
    how_to_obtain: "Find the bridge IP through the Hue app, router DHCP table, mDNS, or discovery.meethue.com, then store it in chat with `/env set HUE_BRIDGE_HOST \"https://<bridge-ip>\"`."
credentials:
  - id: hue-application-key
    kind: api_key
    required: true
    secret_ref:
      source: store
      id: HUE_APPLICATION_KEY
    scope: "Philips Hue CLIP v2 hue-application-key header"
    how_to_obtain: "Press the bridge link button, build the link request with `node skills/hue/hue.cjs --format json bridge link --app-name hybridclaw --instance-name lab`, and send its `httpRequest` through the gateway. Set the returned `HUE_APPLICATION_KEY` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set HUE_APPLICATION_KEY \"<application-key>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set HUE_APPLICATION_KEY \"<application-key>\"`."
  - id: hue-remote-refresh-token
    kind: bearer
    required: false
    secret_ref:
      source: store
      id: HUE_REMOTE_REFRESH_TOKEN
    scope: "Hue Remote API OAuth token used for off-LAN API calls"
    how_to_obtain: "Create a Hue developer app and complete the Hue Remote API OAuth flow. Set `HUE_REMOTE_REFRESH_TOKEN` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set HUE_REMOTE_REFRESH_TOKEN \"<token>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set HUE_REMOTE_REFRESH_TOKEN \"<token>\"`."
  - id: hue-remote-access-token
    kind: bearer
    required: false
    secret_ref:
      source: store
      id: HUE_REMOTE_ACCESS_TOKEN
    scope: "Hue Remote API short-lived access token used as Authorization bearer"
    how_to_obtain: "Run `node skills/hue/hue.cjs --format json remote oauth-token` after configuring the Remote API client id, client secret, and refresh token; the emitted gateway request captures the access token into `HUE_REMOTE_ACCESS_TOKEN`."
metadata:
  hybridclaw:
    category: home-automation
    short_description: "Philips Hue local CLIP v2 reads plus approval-gated light, group, scene, and automation control."
    tags:
      - hue
      - philips-hue
      - smart-home
      - lighting
      - r21
    related_roadmap:
      - R21.114
      - R48
    issue: 1118
    stakes_tiers:
      green:
        - local-bridge-status
        - local-bridge-list
        - local-device-list
        - local-light-list
        - local-grouped-light-list
        - local-room-list
        - local-zone-list
        - local-scene-list
        - local-motion-list
        - local-temperature-list
        - local-light-level-list
        - local-button-list
        - local-behavior-instance-list
        - local-entertainment-configuration-list
        - local-eventstream
      amber:
        - local-link-button
        - remote-oauth-token
        - remote-bridges
        - remote-light-list
        - local-light-on
        - local-light-off
        - local-light-brightness
        - local-light-color
        - local-group-on
        - local-group-off
        - local-group-brightness
        - local-group-color
        - local-room-on
        - local-room-off
        - local-group-recall-scene
        - local-scene-recall
        - local-behavior-enable
        - local-behavior-disable
        - local-scene-create
        - local-behavior-create
      red:
        - local-bridge-config-timezone
        - local-bridge-config-software-update
    escalation:
      writes: confirm-each
      route: f14
    cost_measurement:
      system: UsageTotals
      sub_limit_key: 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. 1