---
name: spiral-heal
description: Auto-heal (AGC) the audio-reactive bands in Spiralyst Lab so sliders stop pinning at their max and react to the music. Invoke when the user says /spiral-heal or asks to fix/tune audio reactivity, "the slider isn't moving", "it's maxed out / pinned", or to make a band responsive. Requires the app running + music playing.
---

# Spiralyst Lab — auto-heal audio reactivity

Spiralyst Lab maps each reactive band's level (0..1) onto a slider's `[min, max]`.
If the band is hot relative to its gain, the level clamps at 1.0 and the slider
pins at max (no movement). Healing is an AGC over three levers — don't tune only
gain:

1. **gain** — scaled so the peak lands ~0.85 (headroom, not pinned).
2. **squelch** (`noiseFloor`) — for a *steady* band, raise the floor so the constant
   level gates to 0 and only peaks above it pass through → excursion. The single
   most useful lever for a punchy reactive effect.
3. **signal** — if still flat, switch to one that reacts (`flux` = onsets).

By default (`policy: "auto"`) the heal searches squelch + signal for the most
responsive mapping, then re-tunes gain for the winner. The heal logic lives in the
app and is reachable over the API; this skill drives it.

Read `$BASE` and `$AUTH` from `~/.spiralyst-lab/api-port.json` as in `/spiral-observe`,
and send the bearer token on every request.

## Preconditions

- Spiralyst Lab is running.
- System audio is active AND **music is playing** — the heal tunes against live
  signal; silence gives it nothing to work with.

## What to do when invoked

1. Trigger the heal:

   ```
   curl -s -H "$AUTH" -XPOST "$BASE/api/audio/heal" \
     -H 'Content-Type: application/json' -d '{}'    # default policy = "auto"
   ```

   Body options:
   - `{"lockSignal": true}` — heal within the current signal (don't switch from
     amplitude to flux).
   - `{"key": "color:hueStart"}` — heal one band only.
   - `{"target": 0.8}` — different peak target (default 0.85).
   - `{"gainOnly": true}` — only adjust gain.

2. Read the result:

   ```
   curl -s -H "$AUTH" "$BASE/api/audio/heal"
   ```

   Returns a per-band report: `before / after` gain, peak, excursion, signal,
   plus a note (e.g. "saturated: gain 1.5 → 0.375" or "low dynamics → signal
   amplitude → flux").

3. If the report says "all bands read ~0", ask the user to start the music or
   enable system audio, then re-trigger.

4. Summarize what changed: which bands healed, gain before→after, any signal
   switch, resulting excursion. Higher excursion = more visible reaction.

## Verify independently

```
curl -s -H "$AUTH" "$BASE/api/audio/bands"
```

`saturated: true` or `peak ≈ 1` means still pinned; `peak − ema` is the
excursion. The heal is idempotent — safe to run again after changing the track.