fluid-telegram/docs/runbook.md

Runbook — helix-forge-telegram-publishing

Rotating the bot token

1. In BotFather: /revoke for the bot, which issues a new token.
2. Write the new token to OpenBao at the interface's secret path.
3. Restart the adapter. It reads the token at start only.
4. Confirm with one publication to the private test channel.

The old token stops working the moment it is revoked, so publications in flight will fail. Do this when nothing is publishing.

Recovering channel administration

If the bot loses its administrator rights, it cannot post and every publication fails with a Telegram 400.

1. In the channel's administrator settings, confirm the bot is present with Post Messages enabled.
2. Grant nothing else. The bot does not need to edit others' messages, delete messages, or manage members, and the intent forbids it from using such rights if it had them.
3. If the bot was removed entirely, re-add it and re-run one test publication.

A human must do this. The Daimon is forbidden from changing channel membership or permissions (InterfaceEvolutionIntent.md §7).

Rolling back a revision

Publish a routing policy with a higher generation naming the previous revision as default:

fluid experiment stop <experiment-id> --generation N --default-revision R-1 \
  --reason "..." --policy-out rollback.json
fluid policy put --file rollback.json

If no experiment is running, write the policy by hand with default_revision set to the known-good revision and a generation above the current one. Rollback is a document replacement; nothing is unwound.

Already-published Telegram messages are not rolled back. They were seen. Correcting a published entry is an edit through the adapter, not a rollback.

An entry published wrongly

1. Stop further publication: install a policy pointing at the last known-good revision.
2. Correct the entry in hall-of-helix and re-publish it. The adapter edits the existing messages rather than posting new ones.
3. If the entry cannot be corrected in place — wrong entry entirely, or content that should not have been published — delete the messages by hand in Telegram and record why in the publication's audit trail.
4. Record a pressure observation. An entry published wrongly is exactly the evidence the framework exists to collect, and the instinct to tidy it away is the instinct to lose it.

Checking what happened

export FLUID_INTERFACE=helix-forge-telegram-publishing

fluid audit trace R-1            # how a revision came to exist, and what followed
fluid pressure list              # what the interface is currently struggling with
fluid telemetry --limit 50       # recent traffic
fluid events --entity <entry-id> # one publication's history

When the evidence store is unavailable

Publication continues. The gateway serves from cached configuration and buffers telemetry, dropping it if the buffer fills. You lose observation, not service.

Do not promote anything while the store is down: the promotion would be unauditable, which is the one thing this framework will not trade away.