docs: separate an agent's routing identifier from its display name

[raullopez-sandbox]

Last of the display-name stack. Documentation only, plus the two tool docstrings that are documentation.

An agent has a lowercase name that routes and an optional free-form display_name that is only ever shown. The docs never distinguished them.

The part that is a correctness fix, not a clarification

SLACK_SETUP.md and DISCORD_SETUP.md both describe autocomplete adoption as matching a group or role "named exactly after" an agent. With one name that was unambiguous. With two it is not, and the wrong reading is actionable: an operator who names a Discord role or Slack user group after an agent's display name gets a role that is adopted by nothing and an agent with no autocomplete, silently.

Matching is on the identifier alone. Verified in code rather than inferred:

• slack/adapter.py:1686 — builds its lookup keys from agent_name and matches them against groups keyed by folded handle and folded name.
• discord/adapter.py:1028 — discord.utils.get(guild.roles, name=agent_name), an exact match on the identifier.

Both pages now say identifier explicitly, and say what happens to a group or role made under a display name.

The gap that was missing entirely

MATTERMOST_SETUP.md had nothing about TeamSettings.TeammateNameDisplay. Mattermost stores a bot's display name and renders it only when that server-wide setting is full_name or nickname_full_name; the default is username, under which the whole feature is invisible. Switch's own deployments set it — an operator bringing their own server does not, and had no way to know. The new prerequisite gives the System Console path, both accepted values, and notes the setting is server-wide so it changes how human members render too.

Everything else

• bridges/README.md — the shared definition of the two names, which the five platform guides lean on, so each of those stays a one-line clarification.
• TEAMS_SETUP.md, TELEGRAM_SETUP.md — which name is rendered where; Telegram also notes that addressing runs the other way.
• ARCHITECTURE.md — the Agent domain-model bullet.
• The three connector skills/switch/SKILL.md copies — list_agents and get_agent_detail return both fields and a target_names entry carrying a display name addresses no one. Substantively identical in all three; every pre-existing divergence between them is untouched.
• The two skills/configure/SKILL.md copies — one clause noting the name pattern constrains the identifier only.
• operations/definitions.py — the same note on the two tool docstrings that return the field.

console/…/opencode/skill-file.ts embeds the opencode skill byte-for-byte and connector-assets.test.ts fails on drift, so its copy moves in step.

Not in this PR

docs/official/ is generated from sandbox-quantum/docs and rewritten by just sync-docs, so it is not editable here. Several published pages — deploy/messaging-apps/how-connections-work.md most of all — need the same distinction and will need a change in that repo.

Verification

• ruff format --check, ruff check, mypy — clean.
• Full core suite: 2201 passed.
• test_mcp_tool_surface.py (compares the three skills' tool indexes against each other and against the registered tools): 7 passed.
• Embedded opencode skill confirmed byte-identical to the connector file (41769 bytes).

🤖 Generated with Claude Code

[abeldantas]

LGTM