Reviewed member nickname changes

Member nickname changes have no immediate-call path and are independent of member-directory, moderation, role, and voice authority. Set capabilities.nicknameChanges: true, configure non-empty exact scopes.nicknameGuildIds, and keep that guild scope inside readScope.guildIds when a read allowlist exists. The base gate requires pinned application and bot IDs and enables only the narrow current-bot route backed by CHANGE_NICKNAME. Set capabilities.otherMemberNicknameChanges: true only when the broader exact-member route is intentional; it depends on the base gate, requires MANAGE_NICKNAMES, and applies scopes.protectedUserIds plus owner, pending-member, administrator, and strict hierarchy exclusions.

Each request uses a discriminated exact target: { "kind": "current-bot" } for the connector's own guild nickname or { "kind": "member", "userId": "..." } for another exact member. The desired nickname is either a literal string or explicit null to clear it. Strings must contain 1 to 32 well-formed Unicode scalar values with no control or formatting code points, surrounding whitespace, or repeated whitespace. The connector never trims, normalizes, substitutes, searches by display name, or converts an empty string into clearing intent.

1. Call plan_member_nickname_change with one exact guild, exact target object, strict nickname or null, Discord audit-log reason, and unique one-shot operation key.
2. Review the pinned identities, exact target kind and member ID, transient untrusted guild name, username, current and desired nickname, required permission, unknown permission bits, protected-target and hierarchy results where applicable, privacy projection, risks, warnings, operation-key hash, and keyed digest.
3. Call execute_member_nickname_change with the identical intent and digest.
4. Approve the signed MCP confirmation only if every identity, target kind, nickname, permission, hierarchy result, reason, risk, warning, hash, and digest remains intended.
5. Review the exact response and member readback, activity ID, verification, and outcome before any related operation.

Planning verifies the exact guild and owner, connector-bot membership, target membership, and complete bounded role inventory. It requires one unambiguous highest role for each evaluated member and complete effective guild permission evidence. An other-member target cannot be the connector bot, guild owner, pending membership-screening member, administrator, protected user, or a member at or above the connector bot's unique highest role. Missing roles, unknown member role references, malformed names or nicknames, mismatched identities, missing required permission, ambiguous hierarchy, a spent operation key, or a prior quarantined same-member outcome fails closed.

An already matching nickname is a verified no-op that requires no confirmation, operation-key reservation, activity record, or Discord mutation. A real execution re-creates the complete plan, durably coordinates the exact member across connector processes sharing the activity-state root, reserves the one-shot operation key, appends pending content-free activity, and issues one non-retried PATCH through /guilds/{guild.id}/members/@me or /guilds/{guild.id}/members/{user.id} with only the exact nick value. It strictly validates the returned member identity and nickname, then performs one exact member readback. The workflow never retries, rolls back, compensates, or sends a full member replacement.

Matching response and readback produce completed; a valid response or readback difference produces completed-with-drift. A known non-rate-limited Discord 4xx refusal before a valid response is failed. Rate limiting, transport or server failure, malformed or mismatched success evidence, readback failure, or any other indeterminate post-reservation state is uncertain and potentially completed. Every reserved key remains spent. Uncertainty retains the durable exact-member claim for operator review and blocks later same-member nickname changes in that process.

Durable activity and operation records contain only exact guild and member IDs, target kind, plan digest, domain-separated operation-key hash, timestamps, fixed status and verification values, activity ID, and sanitized error category. Nicknames, usernames, guild or role names, permission and hierarchy evidence, audit reasons, raw operation keys, request or response bodies, routes, and transport causes never enter durable records, diagnostics, or telemetry. Use review_member_nickname_change for a locally validated plan-only prompt, and inspect the exact member plus Discord audit log before forming a new intent after uncertainty. See Discord's modify current member and modify guild member contracts.

Canonical source: docs/reference.md