Manage PubNub Illuminate

  Supports full CRUD for: Business Objects, Metrics, Queries, Decisions, and Dashboards.

  **Operations:**
  - list: GET all resources of a given type
  - get: GET one resource by id
  - create: POST a new resource (Decisions use automatic 2-step POST→PUT workflow)
  - update: PUT/replace a resource
  - delete: DELETE a resource (Business Object delete cascades to all associated resources)
  - activate / deactivate: toggle isActive (Business Object) or enabled (Decision)
  - get-fields: fetch Query output field definitions (required before building a Query Decision)
  - execute-adhoc: run a one-off Query pipeline without saving it
  - publish-fake-data: generate type-aware fake PubNub messages and publish them to test Decisions. Fetches BO field schema and produces realistic values per field type. Payloads are NESTED to match each field's JSONPath (e.g. `$.message.body.application.user_id` produces `{ application: { user_id: ... } }`, not the flat key `"application.user_id"`), so JSONPath resolution works against nested BO schemas. Pass secret_key when the keyset has Access Manager enabled — initializing with the secret key grants root permissions and bypasses 403 errors. Alternatively pass auth_key with a token from grantToken(). Failures are reported per-message; partial publishes return success with a 'failures' array. NOTE: Illuminate ingests with a 20–30 second delay — wait before querying after publish.
  - verify-query: execute a saved Query by id and return results (confirms data is flowing)
  - check-action-log: fetch recent Decision action log entries to verify a Decision fired
  - raw-snapshot: return the most recent rows from a Business Object via ad-hoc query
  - aggregate: group and count BO data by user/channel or custom group_by fields
  - field-health: check which BO fields are populated vs empty (reveals JSONPath mismatches)
  - custom-query: run a fully custom ad-hoc pipeline

  **ID Dependency Chain — always capture before proceeding:**
  Business Object → id, fields[*].id
  Metric          → id, measureId, dimensionIds
  Query           → id, then call get-fields for output field IDs
  Decision        → id, inputFields[*].id, outputFields[*].id, actions[*].id
  Dashboard       → id, charts[*].id

  **Critical Decision rules:**
  hitType ('SINGLE'|'MATCH_ALL') and executeOnce (boolean) are required — omitting causes HTTP 500.
  Handler auto-injects safe defaults (hitType=SINGLE, executeOnce=false, activeFrom=now, activeUntil=now+2yr).
  The 2-step create workflow resolves field/action names → UUIDs in: action templates
  (both output variable names AND input field names — input names are sentinel-substituted
  pre-POST and restored post-POST), inputValues.inputFieldId, outputValues.outputFieldId,
  outputValues.value (dollar-brace), actionValues.actionId, and
  actionValues.executionLimitInputFieldIds. Use names everywhere.
  If the PUT step fails the handler deletes the orphaned scaffold automatically.

  **CRITICAL — QUERY decision input field naming:**
  For sourceType=QUERY decisions, each inputField.name MUST exactly match the source
  query's output field alias (case-sensitive, including underscores). Illuminate binds
  query result rows to decision inputs by NAME — not by sourceId. If names don't match,
  the decision will be created and activated successfully but will silently NEVER fire
  even with valid data. Always run get-fields on the source query first and copy the
  'field' values verbatim into your decision's inputFields[].name.

  **Business Object limits (handler pre-flights and rejects on violation):**
  - name: 1-100 characters
  - fields[].name: 1-50 characters
  - max 100 fields per BO
  - **max 5 TEXT_LONG fields per BO** (use TEXT, which holds 256 chars, for shorter strings)
  - keep `description` concise — overly long descriptions are rejected with HTTP 400 by the API

  **Decision action default:**
  When the user doesn't specify what action to fire, default to actionType='PUBNUB_PUBLISH'
  with a message body that includes the relevant input/output values via dollar-brace
  template references. PUBNUB_PUBLISH requires no external infrastructure and is trivially
  verifiable via check-action-log or by subscribing to the target channel. Only use WEBHOOK
  when the user has provided a specific URL.

  NEVER delete without explicit user confirmation.

  TOOL SELECTION GUIDE — Illuminate Claude Behavior:
  1. Intent-first: Always start from the user's desired outcome. Ask what they want
     to achieve before suggesting Business Objects, Metrics, or Decisions.
  2. Preview-first: Before creating any resources, describe automation in 1-2 sentences
     and show a conditions → actions decision table. Ask for confirmation before building.
  3. Predefined templates: For spam (flooding/cross-posting) and ranking (Top N/Bottom N),
     use the Query Builder predefined templates. Never recreate these from scratch.
  4. Built-in BO fields: For chat/moderation/ranking, User/Channel/Message/Message Type
     are auto-created. Never ask users to define them.
  5. Start simple: Minimal decision for the core goal; add complexity only when requested.
  6. PubNub extension: For delayed checks, scheduling, or orchestration beyond Illuminate,
     suggest PubNub Functions or pub/sub as the first extension path.