feat(tools): philips_hue tool for local Hue Bridge

[theonlyhennygod]

Summary

• Base branch: master
• What changed and why:
  • Adds a philips_hue Tool that drives a local Philips Hue Bridge via the v2 CLIP API. The integration was previously declared with no implementation; this lights up the developer-page card and gives the agent direct control over lights, scenes, rooms, and groups.
  • Read actions (list_*, get_light) gate on ToolOperation::Read; mutations (set_light, recall_scene, set_group) gate on ToolOperation::Act AND a configurable allowed_resource_types allowlist enforced server-side in execute().
  • Wires into the new schema-driven registry (post-refactor(integrations): registry one for-loop, schema-driven #6386) via #[integration(category = "ToolsAutomation", display_name = "Philips Hue", description = "Smart lighting via local Hue Bridge", status_field = "enabled")] on PhilipsHueConfig — no edits to registry.rs needed.
• Scope boundary:
  • v2 CLIP API only (no v1 /api/<user>/lights/... shim).
  • Local bridge only (no api.meethue.com cloud relay).
  • No mDNS auto-discovery — operator supplies bridge_address (IP or <id>.local).
  • Push-button pairing is documented but performed once outside ZeroClaw (curl); the tool consumes the resulting application_key.
  • Home Assistant and 8Sleep are not in this PR ([Feature]: Home Assistant integration tool #6448, [Feature]: 8Sleep integration tool #6450).
• Blast radius: zeroclaw-config (additive [philips_hue] block, default disabled), zeroclaw-tools (new module), zeroclaw-runtime/src/tools/mod.rs (config-gated registration + tool re-export), zeroclaw-runtime/src/integrations/mod.rs (setup-hint arm — registry.rs untouched under the new schema-driven catalog), docs.
• Linked issue(s): Closes [Feature]: Philips Hue integration tool #6449. Sibling tracking issues: [Feature]: Home Assistant integration tool #6448 (HA, in PR feat(tools): home_assistant tool for HA REST API #6464), [Feature]: 8Sleep integration tool #6450 (8Sleep).

Validation Evidence (required)

cargo fmt --all -- --check
cargo clippy -p zeroclaw-config -p zeroclaw-tools -p zeroclaw-runtime --all-targets -- -D warnings
cargo test -p zeroclaw-config -p zeroclaw-tools -p zeroclaw-runtime

• Commands run and tail output:
  • cargo fmt --all -- --check → clean (no diff after cargo fmt --all).
  • cargo clippy ... → Finished dev profile [unoptimized + debuginfo] target(s) in 38.47s. No warnings.
  • cargo test -p zeroclaw-config -p zeroclaw-tools -p zeroclaw-runtime →
    • test result: ok. 620 passed; 0 failed; 0 ignored (zeroclaw-config)
    • test result: ok. 1630 passed; 0 failed; 1 ignored (zeroclaw-tools)
    • test result: ok. 1162 passed; 0 failed; 0 ignored (zeroclaw-runtime)
    • Total: 3,413 passed, 0 failed.
  • New tool: 18 tests under philips_hue::tests::* — name, schema shape (action enum), URL/base normalization, allowlist trimming, build_light_state body shape (omits unset fields, emits all when set), missing-action / unknown-action / missing-id (get/set/recall) / no-state-fields / disallowed-resource-type / empty-allowlist paths, spec() reflection.
• Beyond CI — what did you manually verify?
  • The new schema-driven registry surfaces Philips Hue automatically — confirmed by reading the new all_integrations(&Config) loop, which consumes Config::integration_descriptors(), which is auto-generated by the #[integration(...)] attribute the Configurable derive picks up.
  • zeroclaw integrations info "Philips Hue" prints the push-button pairing steps (new arm in show_integration_info).
  • Not verified live: I did not pair against a real bridge — set_light/recall_scene HTTP success paths are not covered. Unit tests exhaustively cover the gating logic (allowlist, missing fields, security policy) and request body assembly (build_light_state).
• If any command was intentionally skipped, why: Skipped ./dev/ci.sh all because the change is scoped to three crates + docs + a changelog entry; targeted clippy+test runs already gated those crates with -D warnings.

Security & Privacy Impact (required)

• New permissions, capabilities, or file system access scope? No. HTTP only.
• New external network calls? Yes. The tool connects to https://<bridge_address>/clip/v2/.... Disabled by default; operator opts in.
• Secrets / tokens / credentials handling changed? Yes. New application_key field on PhilipsHueConfig carries #[secret] (encrypted at rest when [secrets] encrypt = true) and falls back to PHILIPS_HUE_APPLICATION_KEY env var.
• PII, real identities, or personal data in diff, tests, fixtures, or docs? No. Tests use neutral placeholders (192.0.2.10 is RFC 5737 documentation IP, test-key, UUIDs are synthetic).
• Risk and mitigation:
  • verify_tls = false is the default because Hue bridges ship with self-signed certs that no public CA chain validates. The risk is a same-LAN MITM swapping bridges. Mitigation: documented in the setup guide; operators on hardened networks can flip to verify_tls = true if they front the bridge with a reverse-proxied real cert. The flag flows through to reqwest::Client::builder().danger_accept_invalid_certs(!verify_tls).
  • A misconfigured allowed_resource_types could let the agent recall scenes the operator didn't expect. Mitigation: defaults are conservative (light, grouped_light, scene, room); empty allowlist blocks all mutations; the check fires server-side in execute() before any HTTP call.

Compatibility (required)

• Backward compatible? Yes. Additive config, default enabled: false. Config::default() includes philips_hue: PhilipsHueConfig::default() so existing configs missing [philips_hue] continue to deserialize unchanged.
• Config / env / CLI surface changed? Yes — new [philips_hue] block; new PHILIPS_HUE_APPLICATION_KEY env var fallback. No CLI changes.
• Upgrade steps for existing users: None required. To opt in, add [philips_hue] enabled = true, bridge_address, and either application_key or PHILIPS_HUE_APPLICATION_KEY (after one-time push-button pairing — documented).

Rollback (required for risk: medium and risk: high)

• Fast rollback command/path: Set [philips_hue] enabled = false in ~/.zeroclaw/config.toml (or remove the block) and restart the agent. The tool is unregistered on next boot.
• Feature flags or config toggles: philips_hue.enabled (master switch). philips_hue.allowed_resource_types (per-mutation throttle; empty disables all mutations while keeping reads available). philips_hue.verify_tls (TLS posture).
• Observable failure symptoms:
  • Logs: philips_hue: enabled but no application key found ... or ... bridge_address is empty — skipping registration indicate config issues.
  • Logs: philips_hue: failed to construct HTTP client: ... indicates a system TLS init failure.
  • Logs: Philips Hue {action} ... failed (4xx/5xx) indicates upstream bridge problems (key revoked, bridge unreachable, resource ID stale).
  • Tools registry at /api/tools will not include philips_hue if either bridge_address or application_key is missing.