Privacy-minimized guild onboarding and reviewed replacement

get_guild_onboarding returns one complete bounded onboarding audit for a separately allowlisted guild. Set capabilities.onboardingAudit: true and list every eligible guild in scopes.onboardingGuildIds. This allowlist must be a subset of readScope.guildIds when the outer read allowlist exists. Enabling audit also activates a nonprivileged layout-only Gateway connection and requires pinned application and bot IDs. The equivalent discord://guilds/{guildId}/onboarding resource applies the same policy and always omits member-facing text.

Every read verifies the expected application and bot, exact guild and owner, complete guild-feature evidence, connector membership, complete bounded roles, custom emojis, onboarding state, and effective permissions, plus continuity-stable complete or visibility-bounded channel metadata and overwrites. Results identify whether the guild has Discord's COMMUNITY feature, current prompt and option structure, assignments, modes, enablement evidence, reference health, text lengths, channel evidence counts and coverage, unknown-field and unknown-enum counts, and the exact privacy projection. Prompt titles, option titles, descriptions, and Unicode emoji are omitted by default. Set includeText=true only when their transient review is necessary. Nothing from an onboarding read is cached, journaled, exported, or persisted.

Changes have no immediate-call path. Set capabilities.onboardingChanges: true in addition to audit scope. The request is the complete desired state: enabled flag, mode, default channels, prompts, options, role and channel assignments, descriptions, and emoji. Omitted prompts, options, assignments, and default channels are deletions. Existing prompt IDs must belong to the fresh current configuration, and an existing option ID must remain under its fresh owning prompt. Omit an ID to request creation; the connector's required outbound prompt placeholders are transport-only and Discord's authoritative response IDs must replace them.

The connector requires complete guild-level MANAGE_GUILD and MANAGE_ROLES evidence, unless the connector bot is the exact guild owner. Every assignable role must exist, be standard rather than managed, carry zero permissions, and sit below the connector's highest role. Every referenced channel must exist as a direct guild channel and be visible to @everyone; a default channel must meet the same rule. If any channel is obfuscated, its permission overwrites are unavailable, so every existing or desired role reference is conservatively unsafe. A role-free replacement remains reviewable because it cannot grant access through a hidden channel overwrite. When the desired configuration is enabled, the connector requires fresh COMMUNITY guild-feature evidence and conservatively proves Discord's default-channel visibility and sendability requirement in every mode. A reviewed disable remains available when the feature is absent. Custom emoji must be available and structurally valid, including any role restrictions. Administrator authority is allowed by Discord but appears as a least-privilege warning.

The request and audit surfaces use explicit connector-local safety bounds for text, prompts, options, references, and complete audit evidence. These values are returned in the plan and must not be interpreted as Discord platform limits. State outside those local bounds can still be audited when it fits the larger audit ceilings, but it cannot be copied into a replacement unless it satisfies the stricter write contract. Unknown response fields or enum values block replacement because a complete PUT could otherwise erase future state the connector does not understand.

1. Call get_guild_onboarding with text omitted to inspect structure, permission evidence, reference health, and unknown-field counts. Request transient text only if the member-facing copy itself must be reviewed.
2. Call plan_onboarding_change with the exact complete desired state, Discord audit-log reason, and unique one-shot operation key.
3. Review the verified application and bot IDs, exact guild, COMMUNITY feature state, channel evidence, complete current and desired state, additions, removals, modifications, role and channel safety, emoji health, enablement proof, unknown-field counts, local limits, privacy projection, risks, warnings, operation-key hash, and keyed digest.
4. If the plan reports already-current, no confirmation, reservation, activity record, or Discord write is needed.
5. Call execute_onboarding_change with identical inputs plus the digest.
6. Approve the signed MCP confirmation only if every identity, complete replacement field, deletion, permission, role, channel, emoji, audit reason, operation-key hash, risk, warning, and digest remains intended.
7. Review the exact outcome, activity ID, and verification result, then inspect the enabled join flow with a fresh non-staff member account.

The process-keyed HMAC digest binds the normalized complete request, one-shot operation-key hash, verified identities, exact guild, owner, and feature set, connector member roles, complete roles, continuity-stable channel evidence, trusted visible overwrites, emoji and current onboarding evidence, effective permissions, desired state, diff, local limits, privacy projection, risks, warnings, and verification boundary. A connector restart invalidates the digest. The MCP adapter rebuilds the plan before approval, and the service rebuilds it immediately before mutation. Any identity, guild-feature, prompt, option, assignment, mode, enablement, permission, role, channel coverage, overwrite, emoji, or unknown-field drift invalidates the reviewed plan.

Execution atomically reserves the operation-key hash and appends a pending content-free activity record before one non-retried complete-state PUT with an encoded Discord audit-log reason. The returned state must contain authoritative prompt and option IDs and must semantically match the desired state, including server-assigned IDs for new items. A second complete fresh read verifies the controlled state. Exact response and readback agreement is completed; valid semantic drift is completed-with-drift; a definite Discord client refusal is failed; transport failure, Discord server failure, malformed success, or failed verification is uncertain. Every reserved key remains permanently spent, with no automatic retry, rollback, or compensating replacement.

Changes to the same guild serialize inside one process because every replacement shares the complete onboarding state, permission evidence, reference inventory, and capacity. The production facade additionally acquires a durable exact guild onboarding-collection claim, so connector processes sharing the activity-state root exclude overlapping replacements. An uncertain outcome retains that claim for operator review before another execution can replan, reserve, or write.

Activity and operation records contain only exact guild, application, and bot IDs, plan digest, operation-key hash, timestamps, fixed verification and outcome values, activity ID, and sanitized error category. Prompt and option text, descriptions, Unicode emoji, guild, role, channel, and custom emoji names, permission evidence, audit reasons, raw operation keys, raw payloads, and transport causes never enter durable records, diagnostics, or telemetry. API response and fresh readback verify server-controlled state but cannot prove what a newly joining member sees in a Discord client, so the separate fresh non-staff client check remains part of the operator workflow. See Discord's guild onboarding resource and guild resource permissions.

Canonical source: docs/reference.md