Reviewed resumable guild scaffolds

Guild scaffolds have no immediate-call path. Set capabilities.guildScaffolds: true and list every eligible guild in scopes.guildScaffoldGuildIds. The scaffold allowlist must be a subset of readScope.guildIds when the read allowlist is present. This authority is independent of the standalone channel-creation and role-creation toggles and allowlists. Grant Manage Channels, View Channels, and, when roles are requested, Manage Roles only in selected scaffold guilds. Parent-category overwrites must preserve the required channel permissions.

The bounded input is an exact symbolic graph of additive roles, categories, text channels, and forum channels. Every resource has a globally unique safe key. A child parentKey can reference only a category in the same request, so a scaffold cannot smuggle in an arbitrary unreviewed parent ID. Role and channel properties reuse the standalone strict schemas, including named-permission subset checks and the permanent ADMINISTRATOR prohibition. The request must contain multiple resources and stays within separate role, channel, and total-resource bounds. It cannot edit, assign, move, reorder, delete, reconcile, roll back, or create permission overwrites.

Planning canonicalizes roles by key, then categories, then child channels by parent and key. One bounded evidence pass fetches the exact guild, exact connector member, complete role inventory, and visible channel inventory. The plan labels channel matching, collision, guild-capacity, and parent-capacity evidence visibility-bounded because Discord may omit channels the connector cannot view. It validates application and bot identity, dedicated local scope, logical-name collisions, exact existing-state matches, guild and parent permissions, bot hierarchy, requested role permissions, visible guild role and channel capacity, visible category child capacity, every durable checkpoint, and the dependency frontier. Its steps are explicitly labeled already-current, completed, ready, or waiting-for-parent, and the ordered zero-based executionFrontier.stepIndexes identifies the exact ready steps selected by stepLimit. Exact pre-existing resources are safe no-ops; ambiguous, managed, mismatched, incomplete, or drifting resources are blockers rather than implicit edits.

1. Call plan_guild_scaffold with the exact guild, roles, channels, audit reason, stable scaffold operation key, and bounded stepLimit.
2. Review the verified application, bot, guild, canonical steps, symbolic keys, resolved resource and parent IDs, exact settings and permissions, checkpoint states, ordered execution-frontier indexes, inventories, capacities, permission evidence, warnings, operation-key hash, durable request digest, and keyed plan digest.
3. If every resource is already-current and the operation is unreserved, no confirmation or durable record is needed.
4. Call execute_guild_scaffold with identical intent plus the digest.
5. Approve the signed MCP confirmation only if every identity, resource, parent, property, permission, checkpoint, warning, limit, and digest remains intended.
6. Review the executed steps and remaining frontier. For a paused result, request a fresh plan with the same operation key before approving another frontier.
7. After a completed result, call verify_guild_scaffold with the same exact caller-retained request and operation key. Treat only verified as durable completion evidence; incomplete needs another reviewed frontier, while unrecorded means the exact live scaffold exists without a scaffold receipt.

The process-keyed plan digest binds the complete reviewed evidence and stepLimit, so a connector restart or operational-limit change requires a fresh review. A separate durable request digest binds the raw operation key as HMAC key to the verified application, bot, guild, audit reason, and canonical resource intent without storing any of those content fields. The execution limit is deliberately outside that persistent intent binding so an operator may reduce or increase a later frontier while the new plan digest and confirmation still bind the chosen limit. Reusing the operation key with any different identity or resource intent fails closed.

Before the first mutation, the production facade acquires durable claims over both the guild role and channel collections, then the scaffold reserves a private top-level receipt. It derives domain-separated one-shot keys for every canonical resource and delegates each ready step to the standalone creation service, preserving its pending activity journal, single non-retried POST, and exact readback. Completed per-step receipts are immutable restart-safe checkpoints. The top receipt remains pending across intentional pauses and becomes completed only after a fresh snapshot proves that no ready or dependency-blocked step remains. A normal verified pause releases both collection claims so another process can resume from a fresh plan. An exception, process loss, or uncertain pending outcome retains quarantine for exact operator review.

Execution runs only the ordered ready-step indexes named by the approved plan. A requested child remains waiting-for-parent while its category is absent, so creating that category cannot cascade into child creation under the same approval. A fresh plan must resolve the exact category ID and re-evaluate its overwrites before the child becomes ready. Independent ready roles and categories remain bounded by the same reviewed frontier.

A pending checkpoint indicates another active or interrupted execution and blocks progress. A failure before a per-step receipt exists leaves the top operation pending because no Discord write was authorized by that step reservation. The durable collection claims remain quarantined until an operator inspects Discord and the content-free evidence, explicitly releases the exact claim, and requests a fresh plan. A failed or uncertain checkpoint, an exact readback with drift, a completed receipt whose resource no longer matches, or a top-level identity mismatch permanently blocks that scaffold operation key. The connector never retries, skips, repairs, compensates, or rolls back such a step. Inspect Discord and the content-free receipts before deciding whether a genuinely new intent should use a new operation key.

Inside one connector process, the standalone target locks also serialize logical role and channel targets across different scaffold and standalone operation keys. Durable production-facade claims coordinate scaffolds and standalone role or channel creation across connector processes sharing the activity-state root. Scaffold claims use the persistent request digest rather than the process-keyed frontier digest, preventing a crashed pending operation from being mistaken for a different safely reclaimable plan after restart. Discord does not enforce logical-name uniqueness across different operation keys.

The durable records contain only domain-separated hashes, Discord IDs, timestamps, fixed statuses, verification states, activity IDs, and sanitized error categories. They never contain the raw operation key, symbolic keys, role, category, or channel names, topics, named permissions, audit reason, overwrites, or raw Discord responses. Per-step activity entries follow the same content-free rules. verify_guild_scaffold therefore requires the caller to retain and resubmit the exact request and operation key. It performs the same strict live evidence and checkpoint checks but returns a content-free projection and performs no reservation, activity append, or mutation. A completed scaffold verifies as verified, while an entirely pre-existing exact scaffold reports unrecorded and creates no receipt at all.

Canonical source: docs/reference.md