diff --git a/docs/reference/providers/provider-ad.md b/docs/reference/providers/provider-ad.md
index 27076535..fd78eda6 100644
--- a/docs/reference/providers/provider-ad.md
+++ b/docs/reference/providers/provider-ad.md
@@ -3,43 +3,86 @@ title: Provider Reference - IdLE.Provider.AD (Active Directory)
 sidebar_label: Active Directory
 ---
 
-## Overview
+## Summary
 
-The Active Directory provider (`IdLE.Provider.AD`) is a built-in provider for on-premises Active Directory environments. It enables IdLE to perform identity lifecycle operations directly against Windows Active Directory domains.
+- **Provider name:** `AD` (Active Directory)
+- **Module:** `IdLE.Provider.AD`
+- **Provider kind:** `Identity | Entitlement`
+- **Targets:** Windows Active Directory (on-premises domains)
+- **Status:** Built-in
+- **Since:** 0.9.0
+- **Compatibility:** PowerShell 7+ (IdLE requirement), Windows-only (requires RSAT/ActiveDirectory PowerShell module)
 
-**Platform:** Windows-only (requires RSAT/ActiveDirectory PowerShell module)
+---
 
-**Module:** IdLE.Provider.AD
+## What this provider does
 
-**Factory Function:** `New-IdleADIdentityProvider`
+- **Primary responsibilities:**
+  - Create, read, update, disable, enable, and delete (opt-in) user accounts in Active Directory
+  - Set and update user attributes (department, title, office location, etc.)
+  - Move users between organizational units (OUs)
+  - Manage group memberships (grant/revoke entitlements)
+- **Out of scope / non-goals:**
+  - Establishing AD connectivity or authentication (handled by host-provided credentials or integrated auth)
+  - Managing group policy objects (GPOs)
+  - Managing other AD object types (computers, contacts, etc.)
 
 ---
 
-## Capabilities
+## Contracts and capabilities
 
-The AD provider implements the following IdLE capabilities:
+### Contracts implemented
 
-### Identity Operations
+| Contract | Used by steps for | Notes |
+| --- | --- | --- |
+| Identity provider (implicit) | Identity read/write operations | Supports comprehensive identity lifecycle operations including OU moves |
+| Entitlement provider (implicit) | Grant/revoke/list entitlements | Only supports `Kind='Group'` (AD platform limitation) |
 
-- **IdLE.Identity.Read** - Query identity information
-- **IdLE.Identity.List** - List identities (provider API only, no built-in step)
-- **IdLE.Identity.Create** - Create new user accounts
-- **IdLE.Identity.Delete** - Delete user accounts (opt-in via `-AllowDelete`)
-- **IdLE.Identity.Disable** - Disable user accounts
-- **IdLE.Identity.Enable** - Enable user accounts
-- **IdLE.Identity.Move** - Move users between OUs
-- **IdLE.Identity.Attribute.Ensure** - Set/update user attributes
+> Keep the contract list stable and link to the canonical contract reference.
 
-### Entitlement Operations
+### Capability advertisement (`GetCapabilities()`)
 
-- **IdLE.Entitlement.List** - List group memberships
-- **IdLE.Entitlement.Grant** - Add users to groups
-- **IdLE.Entitlement.Revoke** - Remove users from groups
+- **Implements `GetCapabilities()`**: Yes
+- **Capabilities returned (stable identifiers):**
+  - `IdLE.Identity.Read` - Query identity information
+  - `IdLE.Identity.List` - List identities (provider API only, no built-in step)
+  - `IdLE.Identity.Create` - Create new user accounts
+  - `IdLE.Identity.Delete` - Delete user accounts (opt-in via `-AllowDelete`)
+  - `IdLE.Identity.Disable` - Disable user accounts
+  - `IdLE.Identity.Enable` - Enable user accounts
+  - `IdLE.Identity.Move` - Move users between OUs
+  - `IdLE.Identity.Attribute.Ensure` - Set/update user attributes
+  - `IdLE.Entitlement.List` - List group memberships
+  - `IdLE.Entitlement.Grant` - Add users to groups
+  - `IdLE.Entitlement.Revoke` - Remove users from groups
 
 **Note:** AD only supports `Kind='Group'` for entitlements. This is a platform limitation - Active Directory only provides security groups and distribution groups, not arbitrary entitlement types (roles, licenses, etc.).
 
 ---
 
+## Authentication and session acquisition
+
+> Providers must not prompt for auth. Use the host-provided broker contract.
+
+- **Auth session name(s) requested via `Context.AcquireAuthSession(...)`:**
+  - `ActiveDirectory`
+- **Session options (data-only):**
+  - Any hashtable; commonly `@{ Role = 'Tier0' }` or `@{ Role = 'Admin' }` or `@{ Domain = 'SourceForest' }`
+- **Auth session formats supported:**
+  - `$null` (integrated authentication / run-as context)
+  - `PSCredential` (used for AD cmdlets `-Credential` parameter)
+
+:::warning
+
+**Security notes**
+
+- Do not pass secrets in workflow files or provider options.
+- Ensure credential objects (or their secure strings) are not emitted in logs/events.
+
+:::
+
+---
+
 ## Prerequisites
 
 ### Windows and RSAT
@@ -86,10 +129,11 @@ This makes `New-IdleADIdentityProvider` available in your session.
 
 ---
 
-## Authentication and session acquisition
+## Configuration
 
-> Providers must not prompt for auth. Use the host-provided broker contract.
+### Provider constructor / factory
 
+How to create an instance.
 - **Auth session name(s) used by built-in steps:** `ActiveDirectory`
 - **Auth session formats supported:**  
   - `null` (integrated authentication / run-as)  
@@ -99,16 +143,39 @@ This makes `New-IdleADIdentityProvider` available in your session.
 
 The AD provider uses credential-based authentication where the module capabilities exist without requiring explicit session management. When creating the `AuthSessionBroker`, specify `AuthSessionType = 'Credential'` to indicate this authentication pattern.
 
-:::warning
+- **Public constructor cmdlet(s):**
+  - `New-IdleADIdentityProvider` — Creates an Active Directory identity provider instance
 
-**Security notes**
+**Parameters (high signal only)**
 
-- Do not pass secrets in workflow files or provider options.
-- Make sure your host does not emit credential objects (or their secure strings) in logs/events.
+- `-AllowDelete` (switch) — Opt-in to enable the `IdLE.Identity.Delete` capability (disabled by default for safety)
 
-:::
+> Do not copy full comment-based help here. Link to the cmdlet reference.
+
+### Provider bag / alias usage
 
-### Auth examples
+How to pass the provider instance to IdLE as part of the host's provider map.
+
+```powershell
+$providers = @{
+  Identity = New-IdleADIdentityProvider
+}
+```
+
+- **Recommended alias pattern:** `Identity` (single provider) or `SourceAD` / `TargetAD` (multi-provider scenarios)
+- **Default alias expected by built-in steps (if any):** `Identity` (if applicable)
+
+---
+
+## Provider-specific options reference
+
+> Document only **data-only** keys. Keep this list short and unambiguous.
+
+This provider has **no provider-specific option bag**. All configuration is done through the constructor parameters and authentication is managed via the `AuthSessionBroker`.
+
+---
+
+## Auth examples (Authentication patterns)
 
 **A) Integrated authentication (no broker)**
 
@@ -129,7 +196,7 @@ $adminCredential = Get-Credential -Message 'Enter AD admin credentials'
 $broker = New-IdleAuthSession -SessionMap @{
   @{ Role = 'Tier0' } = $tier0Credential
   @{ Role = 'Admin' } = $adminCredential
-} -DefaultCredential $adminCredential -AuthSessionType 'Credential'
+} -DefaultAuthSession $adminCredential -AuthSessionType 'Credential'
 
 $providers = @{
   Identity         = New-IdleADIdentityProvider
@@ -156,6 +223,44 @@ $broker = New-IdleAuthSession -SessionMap @{
 # Steps use With.AuthSessionOptions = @{ Domain = 'SourceForest' } etc.
 ```
 
+---
+
+## Operational behavior
+
+### Idempotency and consistency
+
+- **Idempotent operations:** Yes (all operations)
+- **Consistency model:** Strong (Active Directory platform consistency)
+- **Concurrency notes:** Operations are safe for retries. AD handles concurrent operations natively.
+
+All operations are idempotent and safe for retries:
+
+| Operation | Idempotent Behavior |
+| --------- | ------------------- |
+| Create | If identity exists, returns `Changed=$false` (no error) |
+| Delete | If identity already gone, returns `Changed=$false` (no error) |
+| Move | If already in target OU, returns `Changed=$false` |
+| Enable/Disable | If already in desired state, returns `Changed=$false` |
+| Grant membership | If already a member, returns `Changed=$false` |
+| Revoke membership | If not a member, returns `Changed=$false` |
+
+This design ensures workflows can be re-run safely without causing duplicate operations or errors.
+
+### Error mapping and retry behavior
+
+- **Common error categories:** `NotFound`, `AlreadyExists`, `PermissionDenied`, `ObjectNotFound`
+- **Retry strategy:** none (delegated to host)
+
+---
+
+## Observability
+
+- **Events emitted by provider (if any):**
+  - Steps emit events via the execution context; provider operations are traced through step events
+- **Sensitive data redaction:** Credential objects and secure strings are not included in operation results or events
+
+---
+
 ## Usage
 
 ### Basic Usage (Integrated Auth)
@@ -188,7 +293,7 @@ $provider = New-IdleADIdentityProvider
 $broker = New-IdleAuthSession -SessionMap @{
     @{ Role = 'Tier0' } = $tier0Credential
     @{ Role = 'Admin' } = $adminCredential
-} -DefaultCredential $adminCredential -AuthSessionType 'Credential'
+} -DefaultAuthSession $adminCredential -AuthSessionType 'Credential'
 
 # Use provider with broker
 $plan = New-IdlePlan -WorkflowPath './workflow.psd1' -Request $request -Providers @{
@@ -336,23 +441,6 @@ The provider supports multiple identifier formats and resolves them deterministi
 
 ---
 
-## Idempotency Guarantees
-
-All operations are idempotent and safe for retries:
-
-| Operation | Idempotent Behavior |
-| --------- | ------------------- |
-| Create | If identity exists, returns `Changed=$false` (no error) |
-| Delete | If identity already gone, returns `Changed=$false` (no error) |
-| Move | If already in target OU, returns `Changed=$false` |
-| Enable/Disable | If already in desired state, returns `Changed=$false` |
-| Grant membership | If already a member, returns `Changed=$false` |
-| Revoke membership | If not a member, returns `Changed=$false` |
-
-This design ensures workflows can be re-run safely without causing duplicate operations or errors.
-
----
-
 ## Entitlement Model
 
 Active Directory entitlements use:
@@ -388,45 +476,70 @@ Step metadata (including required capabilities) is provided by step pack modules
 
 ---
 
-## Example Workflows
-
-Complete example workflows are available in the repository:
-
-- **examples/workflows/ad-joiner-complete.psd1** - Full joiner workflow (Create + Attributes + Groups + OU move)
-- **examples/workflows/ad-mover-department-change.psd1** - Mover workflow (Update attributes + Group delta + OU move)
-- **examples/workflows/ad-leaver-offboarding.psd1** - Leaver workflow (Disable + OU move + conditional Delete)
-
----
-
-## Provider Aliases
+## Examples
 
-The provider uses **provider aliases** - the hashtable key in the `Providers` parameter is an alias chosen by the host:
+### Minimal host usage
 
 ```powershell
-# Single provider scenario
-$plan = New-IdlePlan -Providers @{ Identity = $provider }
+# 1) Create provider instance
+$provider = New-IdleADIdentityProvider
 
-# Multi-provider scenario
-$plan = New-IdlePlan -Providers @{ 
-    SourceAD = $sourceProvider
-    TargetAD = $targetProvider 
-}
+# 2) Build provider map
+$providers = @{ Identity = $provider }
+
+# 3) Plan + execute
+$plan = New-IdlePlan -WorkflowPath './workflow.psd1' -Request $request -Providers $providers
+$result = Invoke-IdlePlan -Plan $plan -Providers $providers
 ```
 
-Workflow steps reference the alias via `With.Provider`:
+### Example workflow snippet
 
 ```powershell
 @{
-    Type = 'IdLE.Step.CreateIdentity'
-    With = @{
-        Provider = 'SourceAD'  # Matches the alias in Providers hashtable
-        IdentityKey = 'user@contoso.local'
-        # ...
+  Steps = @(
+    @{
+      Name = 'CreateUser'
+      Type = 'IdLE.Step.CreateIdentity'
+      With = @{
+        Provider = 'Identity'
+        IdentityKey = 'jdoe'
+        Attributes = @{
+          GivenName = 'John'
+          Surname = 'Doe'
+          UserPrincipalName = 'jdoe@contoso.local'
+        }
+        AuthSessionName = 'ActiveDirectory'
+        AuthSessionOptions = @{ Role = 'Admin' }
+      }
     }
+  )
 }
 ```
 
-Built-in steps default to `'Identity'` when `With.Provider` is omitted.
+### Complete example workflows
+
+Complete example workflows are available in the repository:
+
+- **examples/workflows/ad-joiner-complete.psd1** - Full joiner workflow (Create + Attributes + Groups + OU move)
+- **examples/workflows/ad-mover-department-change.psd1** - Mover workflow (Update attributes + Group delta + OU move)
+- **examples/workflows/ad-leaver-offboarding.psd1** - Leaver workflow (Disable + OU move + conditional Delete)
+
+---
+
+## Limitations and known issues
+
+- **Platform:** Windows-only (requires RSAT/ActiveDirectory PowerShell module)
+- **Entitlement types:** Only supports `Kind='Group'` (AD platform limitation - no roles, licenses, etc.)
+- **Concurrency:** While operations are thread-safe, concurrent modifications to the same object should be managed by the host
+- **Delete capability:** Disabled by default; must opt-in with `-AllowDelete` for safety
+
+---
+
+## Testing
+
+- **Unit tests:** `tests/Providers/ADIdentityProvider.Tests.ps1`
+- **Contract tests:** Provider contract tests validate implementation compliance
+- **Known CI constraints:** Tests use mock adapter layer; no live AD dependency in CI
 
 ---
 
diff --git a/docs/reference/providers/provider-directorysync-entraconnect.md b/docs/reference/providers/provider-directorysync-entraconnect.md
index b71985ac..44e4e24f 100644
--- a/docs/reference/providers/provider-directorysync-entraconnect.md
+++ b/docs/reference/providers/provider-directorysync-entraconnect.md
@@ -3,11 +3,6 @@ title: Provider Reference - IdLE.Provider.DirectorySync.EntraConnect
 sidebar_label: DirectorySync.EntraConnect
 ---
 
-> **Purpose:** This page is a **reference** for a specific provider implementation.
-> Keep it factual and contract-oriented. Put conceptual explanations elsewhere and link to them.
-
----
-
 ## Summary
 
 - **Provider name:** EntraConnect DirectorySync
@@ -139,6 +134,10 @@ $broker | Add-Member -MemberType ScriptMethod -Name AcquireAuthSession -Value {
 - **Public constructor cmdlet(s):**
   - `New-IdleEntraConnectDirectorySyncProvider` — Creates a provider instance.
 
+**Parameters (high signal only)**
+
+- No mandatory parameters; provider has no configuration options
+
 > Do not copy full comment-based help here. Link to the cmdlet reference.
 
 ### Provider bag / alias usage
@@ -229,3 +228,11 @@ $result = Invoke-IdlePlan -Plan $plan -Providers $providers
 
 - Requires an elevated remote execution context on the Entra Connect server.
 - The remote target must have the ADSync cmdlets available (`Start-ADSyncSyncCycle`, `Get-ADSyncScheduler`).
+
+---
+
+## Testing
+
+- **Unit tests:** `tests/Providers/EntraConnectDirectorySyncProvider.Tests.ps1`
+- **Contract tests:** Provider contract tests validate implementation compliance
+- **Known CI constraints:** Tests use mock remote execution layer; no live Entra Connect server dependency in CI
diff --git a/docs/reference/providers/provider-entraID.md b/docs/reference/providers/provider-entraID.md
index 16697c48..bc633a6b 100644
--- a/docs/reference/providers/provider-entraID.md
+++ b/docs/reference/providers/provider-entraID.md
@@ -3,19 +3,58 @@ title: Provider Reference - IdLE.Provider.EntraID
 sidebar_label: Entra ID
 ---
 
-Microsoft Entra ID (formerly Azure Active Directory) identity provider for IdLE.
+## Summary
 
-## Overview
+- **Provider name:** `EntraID` (Microsoft Entra ID)
+- **Module:** `IdLE.Provider.EntraID`
+- **Provider kind:** `Identity | Entitlement`
+- **Targets:** Microsoft Entra ID (formerly Azure Active Directory) via Microsoft Graph API (v1.0)
+- **Status:** First-party (bundled)
+- **Since:** 0.9.0
+- **Compatibility:** PowerShell 7+ (IdLE requirement)
 
-The `IdLE.Provider.EntraID` module provides a production-ready provider for managing identities and group entitlements in Microsoft Entra ID via the Microsoft Graph API (v1.0).
+---
 
-## Installation
+## What this provider does
 
-The provider is included in the IdLE repository under `src/IdLE.Provider.EntraID/`.
+- **Primary responsibilities:**
+  - Create, read, update, disable, enable, and delete (opt-in) user accounts in Microsoft Entra ID
+  - Set and update user attributes (givenName, surname, department, jobTitle, etc.)
+  - List group memberships and manage group entitlements (grant/revoke)
+  - Resolve identities by objectId (GUID), UserPrincipalName (UPN), or mail address
+- **Out of scope / non-goals:**
+  - Establishing authentication or obtaining Graph access tokens (handled by host-provided broker)
+  - Managing M365 groups, distribution lists, or Teams
+  - License assignment or MFA/Conditional Access management
+  - Custom attributes or schema extensions (not supported in MVP)
 
-```powershell
-Import-Module ./src/IdLE.Provider.EntraID/IdLE.Provider.EntraID.psd1
-```
+---
+
+## Contracts and capabilities
+
+### Contracts implemented
+
+| Contract | Used by steps for | Notes |
+| --- | --- | --- |
+| Identity provider (implicit) | Identity read/write/delete operations | Full identity lifecycle support via Microsoft Graph API |
+| Entitlement provider (implicit) | Grant/revoke/list group memberships | Only Entra ID groups; not M365 groups or distribution lists |
+
+### Capability advertisement (`GetCapabilities()`)
+
+- **Implements `GetCapabilities()`**: Yes
+- **Capabilities returned (stable identifiers):**
+  - `IdLE.Identity.Read` - Read identity information
+  - `IdLE.Identity.List` - List identities (filter support varies)
+  - `IdLE.Identity.Create` - Create new identities
+  - `IdLE.Identity.Attribute.Ensure` - Set/update identity attributes
+  - `IdLE.Identity.Disable` - Disable user accounts
+  - `IdLE.Identity.Enable` - Enable user accounts
+  - `IdLE.Entitlement.List` - List group memberships
+  - `IdLE.Entitlement.Grant` - Add group membership
+  - `IdLE.Entitlement.Revoke` - Remove group membership
+  - `IdLE.Identity.Delete` - **Opt-in only** (see Safety section)
+
+---
 
 ## Authentication
 
@@ -190,6 +229,46 @@ $broker | Add-Member -MemberType ScriptMethod -Name AcquireAuthSession -Value {
 # Steps use With.AuthSessionOptions = @{ Tenant = 'Prod' } etc.
 ```
 
+---
+
+## Configuration
+
+### Provider constructor / factory
+
+How to create an instance.
+
+- **Public constructor cmdlet(s):**
+  - `New-IdleEntraIDIdentityProvider` — Creates an Entra ID identity provider instance
+
+**Parameters (high signal only)**
+
+- `-AllowDelete` (switch) — Opt-in to enable the `IdLE.Identity.Delete` capability (disabled by default for safety)
+
+> Do not copy full comment-based help here. Link to the cmdlet reference.
+
+### Provider bag / alias usage
+
+How to pass the provider instance to IdLE as part of the host's provider map.
+
+```powershell
+$providers = @{
+  Identity = New-IdleEntraIDIdentityProvider
+}
+```
+
+- **Recommended alias pattern:** `Identity` (single provider) or `TargetEntra` (multi-provider scenarios)
+- **Default alias expected by built-in steps (if any):** `Identity` (if applicable)
+
+---
+
+## Provider-specific options reference
+
+> Document only **data-only** keys. Keep this list short and unambiguous.
+
+This provider has **no provider-specific option bag**. All configuration is done through the constructor parameters and authentication is managed via the `AuthSessionBroker`.
+
+---
+
 ## Required Microsoft Graph Permissions
 
 ### Delegated Permissions (User Context)
@@ -212,20 +291,7 @@ Minimum required (same as delegated):
 
 **Note**: Application permissions require admin consent in the tenant.
 
-## Capabilities
-
-The provider advertises these capabilities via `GetCapabilities()`:
-
-- `IdLE.Identity.Read` - Read identity information
-- `IdLE.Identity.List` - List identities (filter support varies)
-- `IdLE.Identity.Create` - Create new identities
-- `IdLE.Identity.Attribute.Ensure` - Set/update identity attributes
-- `IdLE.Identity.Disable` - Disable user accounts
-- `IdLE.Identity.Enable` - Enable user accounts
-- `IdLE.Entitlement.List` - List group memberships
-- `IdLE.Entitlement.Grant` - Add group membership
-- `IdLE.Entitlement.Revoke` - Remove group membership
-- `IdLE.Identity.Delete` - **Opt-in only** (see Safety section)
+---
 
 ## Identity Addressing
 
@@ -306,6 +372,42 @@ $provider = New-IdleEntraIDIdentityProvider -AllowDelete
 
 Workflows that require delete must explicitly declare the capability requirement in their metadata (not yet implemented in IdLE core, but provider is ready).
 
+---
+
+## Operational behavior
+
+### Idempotency and consistency
+
+- **Idempotent operations:** Yes (all operations)
+- **Consistency model:** Eventually consistent (Microsoft Graph API)
+- **Concurrency notes:** Microsoft Graph enforces rate limits; provider marks throttling errors as transient
+
+All operations are idempotent:
+
+| Operation | Idempotent Behavior |
+| --------- | ------------------- |
+| Create | If identity exists, returns `Changed=$false` (no error) |
+| Delete | If identity already gone, returns `Changed=$false` (no error) |
+| Enable/Disable | If already in desired state, returns `Changed=$false` |
+| Grant membership | If already a member, returns `Changed=$false` |
+| Revoke membership | If not a member, returns `Changed=$false` |
+| Set attribute | If already at desired value, returns `Changed=$false` |
+
+### Error mapping and retry behavior
+
+- **Common error categories:** `NotFound`, `AlreadyExists`, `PermissionDenied`, `Throttled` (HTTP 429)
+- **Retry strategy:** None (provider marks transient errors; retry is delegated to host)
+
+---
+
+## Observability
+
+- **Events emitted by provider (if any):**
+  - Steps emit events via the execution context; provider operations are traced through step events
+- **Sensitive data redaction:** Access tokens and credential objects are not included in operation results or events
+
+---
+
 ## Transient Error Handling
 
 The provider classifies errors as transient or permanent for retry policy support.
@@ -373,44 +475,73 @@ The provider automatically handles Microsoft Graph paging for `ListUsers` and `L
 
 No additional configuration required.
 
-## Built-in Steps Compatibility
+---
 
-The provider works with these built-in IdLE steps:
+## Examples
 
-- `IdLE.Step.CreateIdentity`
-- `IdLE.Step.EnsureAttribute`
-- `IdLE.Step.DisableIdentity`
-- `IdLE.Step.EnableIdentity`
-- `IdLE.Step.DeleteIdentity` (when `AllowDelete = $true`)
-- `IdLE.Step.EnsureEntitlement`
+### Minimal host usage
 
-## Workflow Configuration
+```powershell
+# 1) Create provider instance
+$provider = New-IdleEntraIDIdentityProvider
 
-### Recommended AuthSession Routing
+# 2) Obtain Graph token (host responsibility)
+$token = (Get-AzAccessToken -ResourceUrl "https://graph.microsoft.com").Token
+
+# 3) Create broker
+$broker = New-IdleAuthSession -AuthSessionType OAuth -SessionMap @{ MicrosoftGraph = $token } -DefaultAuthSession $token
+
+# 4) Build provider map
+$providers = @{
+  Identity = $provider
+  AuthSessionBroker = $broker
+}
 
-- `With.AuthSessionName = 'MicrosoftGraph'`
-- `With.AuthSessionOptions = @{ Role = 'Admin' }` (or other routing keys)
+# 5) Plan + execute
+$plan = New-IdlePlan -WorkflowPath './workflow.psd1' -Request $request -Providers $providers
+$result = Invoke-IdlePlan -Plan $plan -Providers $providers
+```
 
-### Example Step Definition
+### Example workflow snippet
 
 ```powershell
 @{
-    Id = 'CreateUser'
-    Type = 'IdLE.Step.CreateIdentity'
-    With = @{
+  Steps = @(
+    @{
+      Name = 'CreateUser'
+      Type = 'IdLE.Step.CreateIdentity'
+      With = @{
+        Provider = 'Identity'
         AuthSessionName = 'MicrosoftGraph'
         AuthSessionOptions = @{ Role = 'Admin' }
         Attributes = @{
-            UserPrincipalName = 'newuser@contoso.com'
-            DisplayName = 'New User'
-            GivenName = 'New'
-            Surname = 'User'
+          UserPrincipalName = 'newuser@contoso.com'
+          DisplayName = 'New User'
+          GivenName = 'New'
+          Surname = 'User'
         }
+      }
     }
+  )
 }
 ```
 
-## Limitations
+---
+
+## Built-in Steps Compatibility
+
+The provider works with these built-in IdLE steps:
+
+- `IdLE.Step.CreateIdentity`
+- `IdLE.Step.EnsureAttribute`
+- `IdLE.Step.DisableIdentity`
+- `IdLE.Step.EnableIdentity`
+- `IdLE.Step.DeleteIdentity` (when `AllowDelete = $true`)
+- `IdLE.Step.EnsureEntitlement`
+
+---
+
+## Limitations and known issues
 
 - **Supported API version**: v1.0 (beta endpoints not used)
 - **Group types**: Only Entra ID groups (not M365 groups or distribution lists)
@@ -418,6 +549,16 @@ The provider works with these built-in IdLE steps:
 - **MFA/Conditional Access**: Not managed by provider
 - **Custom attributes/extensions**: Not supported in MVP
 
+---
+
+## Testing
+
+- **Unit tests:** `tests/Providers/EntraIDIdentityProvider.Tests.ps1`
+- **Contract tests:** Provider contract tests validate implementation compliance
+- **Known CI constraints:** Tests use mock HTTP layer; no live Microsoft Graph calls in CI
+
+---
+
 ## Troubleshooting
 
 ### "AuthSession is required"
diff --git a/docs/reference/providers/provider-exchangeonline.md b/docs/reference/providers/provider-exchangeonline.md
index ac5493ea..6b12ee06 100644
--- a/docs/reference/providers/provider-exchangeonline.md
+++ b/docs/reference/providers/provider-exchangeonline.md
@@ -3,11 +3,11 @@ title: Provider Reference - IdLE.Provider.ExchangeOnline
 sidebar_label: ExchangeOnline
 ---
 
-> **Purpose:** This page is a **reference** for a specific provider implementation.
-> Keep it factual and contract-oriented. Put conceptual explanations elsewhere and link to them.
+## Purpose
 
----
+This provider manages Exchange Online mailbox configuration and Out of Office settings as part of IdLE workflows.
 
+---
 ## Summary
 
 - **Provider name:** ExchangeOnline
@@ -206,3 +206,11 @@ $result = Invoke-IdlePlan -Plan $plan -Providers $providers
 
 - Requires the `ExchangeOnlineManagement` PowerShell module at runtime.
 - The host must establish or broker a usable Exchange Online session; the provider does not connect interactively.
+
+---
+
+## Testing
+
+- **Unit tests:** `tests/Providers/ExchangeOnlineProvider.Tests.ps1`
+- **Contract tests:** Provider contract tests validate implementation compliance
+- **Known CI constraints:** Tests use mock cmdlet layer; no live Exchange Online calls in CI
diff --git a/docs/reference/providers/provider-mock.md b/docs/reference/providers/provider-mock.md
index 4a0e3bf0..4be3df23 100644
--- a/docs/reference/providers/provider-mock.md
+++ b/docs/reference/providers/provider-mock.md
@@ -3,11 +3,6 @@ title: Provider Reference - IdLE.Provider.Mock
 sidebar_label: Mock
 ---
 
-> **Purpose:** This page is a **reference** for a specific provider implementation.
-> Keep it factual and contract-oriented. Put conceptual explanations elsewhere and link to them.
-
----
-
 ## Summary
 
 - **Provider name:** MockIdentity
@@ -182,3 +177,11 @@ $result = Invoke-IdlePlan -Plan $plan -Providers $providers
 
 - Designed for tests and examples only.
 - `GetIdentity` auto-creates missing identities, which may hide "NotFound" scenarios unless tests seed the store explicitly.
+
+---
+
+## Testing
+
+- **Unit tests:** `tests/Providers/MockIdentityProvider.Tests.ps1`
+- **Contract tests:** Provider contract tests validate implementation compliance
+- **Known CI constraints:** None (in-memory provider designed for testing)