Permission explanations

explain_channel_access evaluates only the authenticated connector bot. It unions the guild @everyone role with the bot's roles, applies channel overwrites in Discord's documented everyone, combined-role, and member order, and treats permission bitfields as arbitrary-width integers. ADMINISTRATOR bypasses channel overwrites, unknown future bits are preserved and reported, and incomplete role or overwrite evidence yields partial confidence instead of a false access claim.

Threads use their parent's overwrites. A successful lookup of a private thread is also reported as evidence that Discord exposed that thread to the bot. The explanation identifies required and missing read permissions, but it remains a diagnostic snapshot rather than a guarantee that a later Discord request will succeed. See Discord's permissions reference.

explain_principal_permissions extends that model to the connector bot, one exact member, or one exact role in a permitted guild. It accepts either named permissions, one supported action, or both. Channel actions cover viewing, reading, sending, attaching files, adding reactions, pinning messages, deleting messages, and managing a channel or thread. Hierarchy actions cover assigning or removing one exact role and kicking, banning, or timing out one exact member. Hierarchy requests remain at guild scope and require an exact target plus a connector or member subject.

The service derives channel scope from the exact channel response, fetches members only through Discord's exact guild-member endpoint, and validates a complete bounded role inventory. It never invokes the guild-member listing endpoint. Decisions account for guild ownership, ADMINISTRATOR, Discord's overwrite order, channel and voice prerequisites, thread-specific send and management permissions, active member timeouts, strict role position, managed roles, protected guild owners, self-targeting, and administrator timeout immunity. Private-thread checks use the exact thread-member endpoint for member subjects; a 404 is explicit non-membership, while unavailable role membership stays unknown. Missing or contradictory evidence returns partial confidence and an allowed: null decision.

audit_channel_role_access evaluates every role in the complete guild inventory for up to five selected channel actions, then returns a bounded deterministic page keyed by an exact role ID. Full-inventory allow, deny, and unknown totals remain available even when rows are paged. Each row is a standalone role baseline: member-specific overwrites and timeouts do not belong to a role, so their count is disclosed and they are excluded. Private-thread membership is likewise unknown for a role unless MANAGE_THREADS supplies moderator access.

Both tools are read-only snapshots. They return Discord identifiers, role names, permission bitfields, decision traces, and warnings to the caller, but the connector does not persist those results or member profile data. A later Discord request can still fail if state changes between diagnosis and use.

Canonical source: docs/reference.md