discord_bot/specs/SPEC-006-operator-controls.md

SPEC-006 — Staff / operator controls

Staff operate the bot from the staff channel without SSH. Runtime flags live in memory — a restart resets to config defaults (D-008). The staff-alert path is a tested contract: alerts are the business-critical feature on the restaurant deployment.

OPS-01 — Staff commands only work in the staff channel (coverage: test)

!bot … commands are honored only when sent in the configured staff channel. In any other channel the text is treated as a normal message.

OPS-02 — Pause and resume (coverage: test)

!bot pause stops all public replying (messages are ignored, no model calls); !bot resume restores it and clears quiet mode. Staff commands keep working while paused.

OPS-03 — Image kill-switch (coverage: test)

!bot images off drops the picture part of any response before generation (answer text still goes out); !bot images on restores.

OPS-04 — Quiet mode with auto-resume (coverage: test)

!bot quiet <minutes> silences public replies for N minutes, then the bot resumes by itself. Friday-service panic button that cannot be forgotten.

OPS-05 — Status report (coverage: test)

!bot status answers in the staff channel with the current flags (replies / images / tasks / remaining quiet time).

OPS-06 — Keyword-forced staff alerts (coverage: test)

When a user message matches any configured staff-alert-keywords regex and the model set no staff note, a staff alert is forced with user + message excerpt. Alerting must not depend solely on the model's judgement.

OPS-07 — Staff alerts are rate-limited (coverage: test)

At most staff-alert-max-per-hour (default 10) alerts reach the staff channel per rolling hour; excess alerts are logged. An injection or a glitch must not be able to flood staff.

OPS-08 — Lost staff alerts are logged (coverage: test)

When a staff alert cannot be delivered (staff channel unresolved), the alert text is written to the error log — never silently dropped.

OPS-09 — Self-tasking kill-switch (coverage: test)

!bot tasks off disables bot-initiated posting (today: the boreness loop; later: the FDB-011 scheduler); !bot tasks on restores. Bot-initiated posts also respect pause/quiet.

OPS-11 — Pins are listable (coverage: test)

!bot pins answers with all pinned facts and their ids (global + per-channel) — without it, !bot unpin <id> required guessing ids.

OPS-12 — Task queue surface (coverage: test)

!bot tasks lists open tasks (queued + awaiting approval) with ids; !bot task-approve <id> and !bot task-cancel <id> manage them (TSK-05). !bot tasks on|off stays the kill-switch (OPS-09).

OPS-10 — Spend report (coverage: test)

!bot spend answers in the staff channel with today's estimated spend in USD, token and image counts, and the configured budget. Management sees the cost, not just the cap.

OPS-17 — Help is complete and context-aware (coverage: test)

Help reflects where each command actually works, because not every command is allowed everywhere. !help answers in any channel and lists only the commands usable there: in a normal channel the everyone-commands (!help, !forgetme, !privacy, !wichtel); in the staff channel it additionally lists the operator commands grouped by purpose (control, cost, memory, tasks). !bot help — and any unrecognised !bot command — answers with that same full staff help, so the listing is exhaustive rather than the old hand-maintained partial line. Help works even while the bot is paused.