uad-console-mcp: Instructions file for Codex

AGENTS.md

Instructions for an LLM driving uad-console-mcp. Human-facing docs: README.md, docs/RECIPES.md, docs/PROTOCOL.md.

Orientation

1. This server controls Universal Audio Apollo interfaces through the local UA Mixer Engine on 127.0.0.1:4710: channels, preamps, sends, monitor, talkback, clock, plugins, meters, snapshots.
2. Discovery first. Channel counts, indices, monitor output, send IDs and slot counts differ per model and are read from the engine, never assumed.
3. Every write is read back. A write result is {verified, before, after, warnings} plus the resolved {device, index, name}.
4. Refusals are information, not obstacles. Each one names the env var or confirm flag that would unblock it. Relay it; do not route around it.
5. This is live audio hardware next to human ears. Loud is irreversible.

HARD RULES

1. Never hardcode a channel index, monitor index or slot number. Call uad_list_channels first and use what it returns. ANALOG 1 is input 0 on one model and absent on another.
2. Never raise monitor level without an explicit dB figure from the user. No "a bit louder", no probing to check a fix. uad_set_monitor(level_db=...) only with a number they said.
3. Never enable 48V without asking what microphone is connected. Ask, get an answer, then pass confirm_condenser_mic=true. Never on a ribbon mic: phantom power destroys them permanently. If the answer is unknown or vague, leave 48V alone and say why.
4. Never change clock source or sample rate while meters show signal. Check uad_peek_meters first, warn the user the chain will re-lock, then pass confirm=true. Both refuse above -60 dB.
5. Writes are verified. Treat verified: false as a failure, not as a retry cue. Read the property with uad_raw_get, report what the engine actually holds, and stop. Never loop.
6. Never probe by writing. The engine accepts writes to properties it marks read-only, so a test write is a real change. Learn a property's type, range or enum with uad_raw_get(path=...).
7. On SafetyRefusal, relay the remedy to the user. Do not raise the ceiling, do not switch mode, do not retry with a different tool that reaches the same property. The rail is the point.
8. Call uad_safe_state first when anything is unexpectedly loud. Diagnose afterwards. It needs no arguments and no confirmation.
9. Meter targets are names, and targets is optional. uad_peek_meters and uad_watch_meters both take targets, kind, device (watch also duration_s, threshold_db, interval_s). Omit targets and they sweep every channel of kind (default "input"). A numeric string is matched as a name first: "8" matches ANALOG 8, UG 8, VIRTUAL 8 and errors as ambiguous.
10. A verified rename is usable immediately (the cached topology is updated in place), but if a rename comes back verified: false the old name is still the truth. Use the index until a fresh uad_list_channels proves otherwise.
11. With more than one device, always pass device. An index that exists on several Apollos is ambiguous, by design.
12. Snapshot before experimenting, and show a dry_run=true restore before running it for real.