Gateway token-soup survival guide

Status: public Ana resource. Not provider-authored, platform-authored, or official platform documentation.

Most gateway failures do not start with a bad model. They start with six nearly identical strings, three places to put them, one profile you forgot you were using, and a bot sitting quietly in the wrong channel like a haunted intern.

This guide is for surviving that mess without pasting secrets into chats, docs, screenshots, logs, or agent prompts.

The short version

A working channel setup is not one thing. It is five separate things that must agree:

1. The bot or app credential proves the gateway may log in.
2. The profile environment file stores secrets and nothing else.
3. The config file stores behavior, routing, and enabled platforms.
4. The channel or thread target tells the gateway where to deliver messages.
5. The board-pump or job report proves what happened after the setup ran.

If you mix those together, you get token soup. Then someone blames the model. The model did not misconfigure your Discord intent, Kevin.

What this guide does and does not do

This guide does:

• separate credentials, behavior, channel targets, gateway status, and work reports;
• give a safe checklist before you rotate credentials or rebuild everything;
• show a handoff pattern where secrets stay private and proof stays reviewable;
• use synthetic examples only.

This guide does not:

• approve public posting, outreach, DMs, or channel engagement;
• change accounts, profile settings, gateways, DNS, payments, or credentials;
• claim launch readiness or public availability;
• provide official platform setup instructions.

Use the relevant platform documentation for exact current bot/app screens. This is the operational map that keeps the strings from eating your afternoon.

The pieces people confuse

1. Bot or app credential

The bot credential is the private login material for the platform adapter. It belongs in the profile environment file or secret manager, not in public docs, Markdown drafts, screenshots, issue comments, model prompts, or completion metadata.

Safe synthetic shape:

• platform bot credential: <synthetic-bot-credential>
• app/client identifier: APP_ID_EXAMPLE_ALPHA
• public key or verification string: PUBLIC_KEY_EXAMPLE_ALPHA

The credential proves the gateway may connect. It does not prove the bot can read a specific channel, see message content, post into a thread, receive events, or deliver Kanban reports.

2. Profile .env

The profile environment file is for secrets and per-profile private values. In Hermes-style profile separation, each profile can have its own environment file. That matters because the default profile, the Ana profile, and a test profile may not share the same gateway credential or delivery target.

Put secret values here. Do not put public behavior decisions here unless the software specifically requires it.

Safe handoff wording:

• “The bot credential is present in the Ana profile environment file.”
• “The exact value was not copied into this document.”
• “A readiness check confirmed the gateway can authenticate.”

Unsafe handoff wording:

• “Here is the bot credential.”
• “Paste this credential into the chat so the agent can fix it.”
• “The password is probably fine; try it in three places.”

3. config.yaml

The config file is for behavior: which platforms are enabled, which profile runs the gateway, which model/provider defaults apply, which delivery routes exist, and how jobs should report.

A clean split is:

• secrets in .env or a secret file;
• behavior in config.yaml;
• proof in verification notes;
• public writing with placeholders only.

If the config points to one profile and the credential lives in another, the gateway may fail even when both files look “correct” in isolation.

4. Channel and thread targets

A delivery target is not a credential. It is the destination. For public-safe examples, avoid raw platform IDs and use synthetic labels:

• DISCORD_CHANNEL_EXAMPLE_ALPHA
• THREAD_EXAMPLE_BUILD_LOG
• TELEGRAM_CHAT_EXAMPLE_ALPHA
• SLACK_CHANNEL_EXAMPLE_OPS

Common failure: the bot is valid, the gateway is running, but the report is aimed at the wrong channel, a missing thread, a topic the bot cannot access, or a delivery target copied from another profile.

5. Gateway status

Gateway status answers: is the adapter running, connected, authorized, and seeing the expected events?

It does not answer:

• whether the job prompt is correct;
• whether the Kanban task belongs to the right profile;
• whether the channel rules allow posting;
• whether the public copy passed the relevant copy-safety and publication gate;
• whether a user will see the message in the expected thread.

Gateway connected is necessary. It is not the victory parade. It is the bouncer letting the goblin into the lobby.

6. Board-pump and job reporting

A board-pump, scheduled job, or Kanban worker report is proof of work only if it states what it did, where the durable artifact is, what checks ran, and whether external side effects occurred.

A good internal report says:

• artifact path or approved public URL;
• plain-language verification where relevant;
• source inputs used;
• checks performed;
• approval status;
• external side effects;
• spend.

A bad report says: “Done.”

“Done” is not proof. “Done” is a sticky note on a trapdoor.

Before you blame the credential

Run this checklist before rotating secrets, rebuilding the bot, or summoning the configuration goblin tribunal.

Intent and permission check

• Does the platform app have the required event subscriptions or gateway intents?
• Does it have permission to read and send in the target channel?
• If message content is required, is the relevant privileged setting enabled where the platform requires it?
• Was the bot invited with the correct scope/permissions, not just created in a developer portal?

Channel and thread target check

• Is the delivery target from the same platform and workspace/server/account?
• Is the target a channel, a thread, a topic, a DM, or a forum post? Those are not interchangeable.
• Can the bot see that exact target?
• Are you using a synthetic placeholder in public docs and the real target only in private config or local verification notes?

Profile identity check

• Which Hermes profile is running the gateway?
• Which profile owns the .env credential?
• Which profile owns the config.yaml behavior?
• Which profile owns the Kanban task or cron job?
• Are you debugging the default profile while the Ana profile is the one actually sending?

Delivery target check

• Is the job configured to deliver to the intended place?
• Is it using current-thread/origin delivery, a specific channel target, or a broad fan-out target?
• Does a topic/thread identifier need to be included?
• Is the target safe and approved for this type of message?

Right-agent check

• Is this job assigned to the right specialist profile?
• Does that profile have the needed toolsets and source context?
• Is the task supposed to change gateway settings, or only document the setup?
• If the task is public-facing, did it pass the relevant copy-safety and publication gates before any posting?

If any answer is “I think so,” treat it as “not verified.” Hope is not an observability layer.

Safe handoff pattern

Use a three-layer handoff.

Layer 1: private secret state

Record privately that the secret exists and where it belongs, without copying it.

Example:

• “Ana profile environment file contains the platform bot credential.”
• “File permissions were checked locally.”
• “No credential value was printed, copied, committed, or included in public copy.”

Layer 2: behavior state

Record the non-secret behavior in config notes.

Example:

• “Discord adapter enabled for Ana profile.”
• “Delivery target is configured for the approved build-log channel placeholder.”
• “Kanban reports are expected to return to the origin thread unless an explicit approved target is set.”

For public docs, keep this generic. For internal verification notes, use private paths only if the artifact is explicitly internal.

Layer 3: proof state

Record what was tested and what happened.

Example:

• “Gateway status command returned connected for the adapter.”
• “Dry-run message was not sent because public/channel action was not approved.”
• “The public checklist passed its safety scan.”
• “Public Markdown scan found no private paths, real-looking credentials, raw platform IDs, live-public claims, affiliation claims, or pricing promises.”

Proof is the part another operator can audit without seeing secrets.

Public-copy rules

For public resource drafts:

• use synthetic identifiers only;
• avoid raw numeric platform IDs;
• avoid private local paths;
• do not include screenshots that show credentials or account pages;
• do not imply official status, affiliation, endorsement, partnership, or insider access;
• do not claim a channel, bot, website, or service is live unless verified and approved;
• do not ask readers to send credentials, private logs, payment details, production access, or client data.

If you need an example value, use a fake label like CHANNEL_EXAMPLE_ALPHA, not something that looks copied from a real platform.

Minimal troubleshooting flow

1. Confirm scope. Are you documenting, testing locally, or changing a live gateway? Those are different jobs.
2. Confirm profile. Name the exact profile that owns the gateway process.
3. Confirm credential location privately. Do not print the value.
4. Confirm config behavior. Check which platforms and delivery targets are enabled.
5. Confirm permissions/intents. Platform dashboards can silently block events even when login succeeds.
6. Confirm target. Channel, thread, topic, DM, forum post, and origin delivery are different routing shapes.
7. Confirm worker/job identity. The wrong profile can produce a perfect report in the wrong place.
8. Confirm proof. Write local verification notes with commands, outputs, approval status, side effects, and spend.
9. Only then rotate credentials or change accounts, and only with explicit approval.

A small template for internal verification notes

Use this internally, not as public copy:

• task or change requested:
• profile under test:
• platform adapter:
• credential state: present / missing / not inspected
• config state checked:
• delivery target checked:
• permissions/intents checked:
• dry-run or status command:
• result:
• external side effects:
• spend:
• approval status:
• next blocker:

The point is not bureaucracy. The point is making sure the next operator does not have to ask, “Which token did the goblin lick?”

Final rule

Never debug gateway soup by spreading the soup around. Keep secrets private, behavior explicit, targets synthetic in public, and proof boring enough that someone else can trust it.

Useful beats magical. Boring proof beats dramatic credential bonfires.