Unify provider documentation structure across all providers

[Copilot]

Provider Documentation Unification - COMPLETE ✅

Problem Statement

The dedicated provider documentation pages had structural inconsistencies. This PR unifies them to follow the same general structure while maintaining or improving quality and content coverage.

Analysis Summary

• Template baseline: _provider-name_template.md defines 11 mandatory sections
• Initial state: Providers missing 1-7 sections each, inconsistent ordering
• Goal: Unify structure while preserving all valuable content

Changes Implemented

✅ provider-ad.md

• Added 11 core template sections (Summary, What this provider does, Contracts, Configuration, Provider options, Operational behavior, Observability, Examples, Limitations, Testing)
• Removed duplicate sections (Idempotency Guarantees merged into Operational behavior)
• Removed Purpose statement (per review feedback)
• Removed template placeholder text from Contracts section
• Fixed New-IdleAuthSession examples to use correct parameters (-DefaultAuthSession instead of -DefaultCredential)
• Retained provider-specific content (Prerequisites, Identity Resolution, Troubleshooting, Architecture Notes)
• Result: Template-compliant + valuable extras

✅ provider-entraID.md

• Added 9 core template sections (Summary, What this provider does, Configuration, Provider options, Operational behavior, Observability, Examples, Testing)
• Removed redundant sections (duplicate Capabilities, Installation, Workflow Configuration)
• Removed Purpose statement (per review feedback)
• Fixed New-IdleAuthSession example to use correct parameters and AuthSessionType
• Retained provider-specific content (Graph Permissions, Identity Addressing, Attributes, Troubleshooting)
• Result: Template-compliant + valuable extras

✅ provider-exchangeonline.md

• Added Testing section
• Removed Purpose statement (per review feedback)
• Result: Perfect template alignment ✨

✅ provider-mock.md

• Added Testing section
• Removed Purpose statement (per review feedback)
• Result: Perfect template alignment ✨ (reference implementation)

✅ provider-directorysync-entraconnect.md

• Added Configuration Parameters subsection
• Added Testing section
• Removed Purpose statement (per review feedback)
• Result: Perfect template alignment ✨

Results

📊 Coverage Matrix

Section	AD	EntraID	Exchange	Mock	DirectorySync
All 11 mandatory sections	✅	✅	✅	✅	✅
Template order followed	✅	✅	✅	✅	✅
Testing section with paths	✅	✅	✅	✅	✅

📈 Improvements

• ✅ Consistency: All 11 mandatory sections present in all 5 providers
• ✅ Quality: No content removed; all valuable provider-specific content retained
• ✅ Coverage: +299 net lines added across all providers
• ✅ Structure: Consistent section ordering and naming
• ✅ Testing: All providers now document test locations and CI constraints
• ✅ Clean: Purpose statements removed per review feedback
• ✅ Accurate: All code examples use correct cmdlet parameters

📝 Files Changed

• provider-ad.md: +191, -84 lines (major restructure + fixes)
• provider-entraID.md: +194, -44 lines (major restructure + fixes)
• provider-exchangeonline.md: +7, -5 lines (Testing + Purpose removal)
• provider-mock.md: +7, -5 lines (Testing + Purpose removal)
• provider-directorysync-entraconnect.md: +14, -5 lines (Testing + Configuration + Purpose removal)

Validation

• All mandatory template sections present in all providers
• Section ordering consistent with template
• No content quality reduction
• All Testing sections reference correct test file paths
• Provider-specific valuable content retained
• Examples follow consistent structure
• Purpose statements removed per review feedback
• Template placeholder text removed
• All New-IdleAuthSession examples use correct parameters

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 29a0c0a77e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Unifies the structure of provider reference pages under docs/reference/providers/ so all providers follow a consistent template-style layout (including a standardized Testing section) while retaining provider-specific details.

Changes:

• Restructured AD and Entra ID provider reference pages to align with the shared provider documentation template sections/order.
• Removed the repeated “Purpose” intro block from provider pages.
• Added a standardized “Testing” section (with unit test paths and CI notes) to all provider pages.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
docs/reference/providers/provider-ad.md	Major restructure to template-style sections; adds operational/observability/testing content.
docs/reference/providers/provider-entraID.md	Major restructure to template-style sections; adds configuration/operational/observability/examples/testing content.
docs/reference/providers/provider-exchangeonline.md	Removes Purpose block; adds Testing section.
docs/reference/providers/provider-mock.md	Removes Purpose block; adds Testing section.
docs/reference/providers/provider-directorysync-entraconnect.md	Removes Purpose block; adds config parameters note and Testing section.

Comments suppressed due to low confidence (2)

docs/reference/providers/provider-ad.md:184

• In the “Auth examples” section, New-IdleAuthSession is invoked with -DefaultCredential, but the actual parameter name is -DefaultAuthSession (see src/IdLE/Public/New-IdleAuthSession.ps1). As written, these examples will fail when copy/pasted; please update the parameter name in this section.

## Auth examples (Authentication patterns)

**A) Integrated authentication (no broker)**

```powershell

docs/reference/providers/provider-ad.md:144

• The Configuration section is currently mixing in authentication/session details (AuthSessionName/formats/options/AuthSessionType) that are already covered in the dedicated “Authentication and session acquisition” section earlier. To avoid duplication and future drift, keep auth/session details in the authentication section and limit Configuration to constructor/factory + provider map usage.

- **Auth session formats supported:**  
  - `null` (integrated authentication / run-as)  
  - `PSCredential` (used for AD cmdlets `-Credential`)
- **Session options (data-only):** Any hashtable; commonly `@{ Role = 'Tier0' }` / `@{ Role = 'Admin' }`
- **Required `AuthSessionType`:** `Credential`