Capability-safe native Guild Template lifecycle

list_guild_templates exposes one complete bounded native Guild Template inventory for a separately allowlisted source guild. Set capabilities.guildTemplateAudit: true and list every eligible guild in scopes.guildTemplateGuildIds. The template 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. Every read verifies the expected application and bot, exact guild and owner, connector membership, complete bounded roles, continuity-stable complete or visibility-bounded live channel evidence, and effective guild-level MANAGE_GUILD permission. The equivalent discord://guilds/{guildId}/templates resource applies the same policy and privacy projection.

A template code and its discord.new use URL are reusable bearer capabilities. The REST client keeps each code only in transient private state and replaces it with a process-keyed HMAC reference before building an MCP result. Inventory exposes timestamps, creator user ID without a profile, usage count, dirty state, metadata character counts, count-only role, channel, overwrite, risky-permission, and unknown-field structure, live count-only guild structure, channel evidence counts and coverage, complete permission evidence, and explicit limitations. Template names, descriptions, creator profiles, guild and resource names, channel topics, icon hashes, codes, URLs, serialized source snapshots, and raw payloads are omitted. An opaque reference cannot be converted back into a code and expires when the connector process restarts.

A native Guild Template is a Discord snapshot for creating a future guild, not a backup or restore artifact. It does not preserve original IDs, members, messages, audit history, integrations, or application-owned resources, and Discord may omit unsupported channel types, managed roles, and guild features. The connector does not expose template use, guild creation from a template, export, import, restore, or arbitrary code lookup. Count-only structural drift is advisory because Discord's serialized source snapshot is partial; channelComparisonComplete separately states whether the live channel side was complete, and Discord's is_dirty: false state is authoritative for a no-op synchronization plan. Read-only inventory counts unknown top-level template fields, but change planning fails closed when any are present because the privacy projection intentionally discards their values. Unknown fields inside the serialized source snapshot remain privately freshness-bound and are returned only as counts.

Changes have no immediate-call path. Set capabilities.guildTemplateChanges: true in addition to audit scope. Supported actions are create, synchronize, update-metadata, and delete. Creation and synchronization can capture live channel state, so either action requires complete live channel metadata and fails closed if any channel is obfuscated. Metadata update and delete target an exact existing capability and remain available with explicitly visibility-bounded live structure and drift. Creation requires an exact bounded name and a nullable bounded description. Metadata update accepts at least one supplied name or description field, including an empty description or null to clear it. Every non-creation action accepts only an opaque process-local reference, never a code or URL. The audit reason rejects template URLs and, after fresh target resolution, rejects the exact target code.

1. Call list_guild_templates and review the complete capability-safe inventory, channel evidence and comparison completeness, live structure, dirty state, risky-permission counts, permission evidence, privacy projection, and limitations.
2. Call plan_guild_template_change with the exact action-specific request, bounded audit reason, and unique one-shot operation key.
3. Review the verified application and bot IDs, exact guild, action, mutation, target reference, requested metadata, complete inventory bounds, channel evidence, count-only live and target structure, advisory drift and its channel-comparison completeness, MANAGE_GUILD evidence, privacy omissions, risks, warnings, operation-key hash, and keyed digest.
4. Call execute_guild_template_change with identical request fields plus the digest.
5. Approve the signed MCP confirmation only if every identity, action, target, metadata field, permission, limitation, risk, warning, audit reason, operation-key hash, and digest remains intended.
6. Review the returned action, opaque reference when applicable, exact full-inventory readback result, activity ID, and outcome before any follow-up.

The process-keyed HMAC digest binds the normalized request, desired metadata, one-shot operation-key hash, verified application and bot identities, exact guild, complete private template inventory, complete live roles, continuity-stable channel evidence, trusted visible channel metadata, connector membership, effective permission evidence, target projection, count-only drift, privacy projection, risks, and warnings. The MCP adapter rebuilds the plan before approval, and the service rebuilds it immediately before mutation. Any identity, template, usage, metadata, snapshot, guild structure, permission, channel coverage, or intent change invalidates the reviewed plan. A clean synchronization or unchanged metadata request returns already-current without reservation or activity.

After a non-no-op plan, execution atomically reserves the operation key and appends a pending content-free activity record before one non-retried mutation. The connector validates the returned capability and metadata, requires Discord to report a clean snapshot after creation or synchronization, fetches the complete inventory again, and requires the exact expected full-inventory transition plus matching target snapshot or verified absence. A known Discord 4xx refusal before an acknowledged mutation is failed; rate limiting, transport or server failure, malformed success, returned-capability mismatch, a non-clean snapshot, or failed exact readback is uncertain and potentially completed. A mutation with exact successful readback whose local completion record fails returns completed-record-failed. Every reserved key remains spent, the direct service quarantines the guild after either ambiguous outcome, and the production facade retains a durable exact guild template-collection claim across connector processes sharing the activity-state root. Never retry, compensate, or infer a result from template names.

Discord offers no conditional Guild Template snapshot mutation. The continuity-stable evidence proves the reviewed HTTP pass matched one complete Gateway layout, but a later concurrent guild change between final review and creation or synchronization can still alter what Discord captures even when the returned capability and complete template inventory read back exactly. Exact readback proves the resulting Discord template object, not complete fidelity with the reviewed live guild or a future guild created from that template. Prevent concurrent guild administration during creation and synchronization, and use an exclusive administration window for high-risk snapshots.

Discord does not document audit-log-reason support for the Guild Template endpoints. The connector validates and binds the reason into review, signed confirmation, and plan freshness but deliberately does not send an undocumented audit-log header. Activity and operation records contain only the exact guild ID, optional opaque template reference, action, plan digest, operation-key hash, timestamps, fixed verification and outcome values, activity ID, and sanitized error category. Template codes, URLs, names, descriptions, creator profiles, source snapshots, guild or resource names, permission evidence, audit reasons, raw operation keys, raw responses, and transport causes never enter persistent records, diagnostics, or telemetry. See Discord's Guild Template resource and permission flags.

Canonical source: docs/reference.md