From 5943eca3491179942754a61ed5498dc4efd70e76 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 7 Feb 2026 20:40:56 +0000
Subject: [PATCH 1/8] Initial plan


From 28879accca8571e62423107e6d3fd99aa86c6a15 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 7 Feb 2026 20:44:42 +0000
Subject: [PATCH 2/8] Unify provider-ad.md structure with template

Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
---
 docs/reference/providers/provider-ad.md | 267 +++++++++++++++++-------
 1 file changed, 191 insertions(+), 76 deletions(-)

diff --git a/docs/reference/providers/provider-ad.md b/docs/reference/providers/provider-ad.md
index 7b23467a..77eb8e07 100644
--- a/docs/reference/providers/provider-ad.md
+++ b/docs/reference/providers/provider-ad.md
@@ -3,43 +3,93 @@ title: Provider Reference - IdLE.Provider.AD (Active Directory)
 sidebar_label: Active Directory
 ---
 
-## Overview
+> **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.
 
-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.
+---
+
+## Summary
 
-**Platform:** Windows-only (requires RSAT/ActiveDirectory PowerShell module)
+- **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)
+
+---
 
-**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
+List the IdLE provider contracts this provider implements and what they mean at a glance.
 
-- **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
+| 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) |
 
-### Entitlement Operations
+> Keep the contract list stable and link to the canonical contract reference.
 
-- **IdLE.Entitlement.List** - List group memberships
-- **IdLE.Entitlement.Grant** - Add users to groups
-- **IdLE.Entitlement.Revoke** - Remove users from groups
+### Capability advertisement (`GetCapabilities()`)
+
+- **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,26 +136,45 @@ 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
 
-- **Auth session name(s) used by built-in steps:** `ActiveDirectory`
-- **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' }`
+How to create an instance.
 
-:::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.
 
-### Auth examples
+### Provider bag / alias usage
+
+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)**
 
@@ -151,6 +220,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)
@@ -331,23 +438,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:
@@ -383,45 +473,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
 
 ---
 

From 684e041130710e5ca2dd3f72bd229e8c69990fb0 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 7 Feb 2026 20:46:28 +0000
Subject: [PATCH 3/8] Enhance provider-entraID.md structure with missing
 sections

Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
---
 docs/reference/providers/provider-entraID.md | 232 ++++++++++++++++---
 1 file changed, 194 insertions(+), 38 deletions(-)

diff --git a/docs/reference/providers/provider-entraID.md b/docs/reference/providers/provider-entraID.md
index cc064b27..564d0577 100644
--- a/docs/reference/providers/provider-entraID.md
+++ b/docs/reference/providers/provider-entraID.md
@@ -3,11 +3,37 @@ title: Provider Reference - IdLE.Provider.EntraID
 sidebar_label: Entra ID
 ---
 
-Microsoft Entra ID (formerly Azure Active Directory) identity provider for IdLE.
+> **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.
 
-## Overview
+---
+
+## Summary
 
-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).
+- **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)
+
+---
+
+## What this provider does
+
+- **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)
+
+---
 
 ## Installation
 
@@ -17,6 +43,34 @@ The provider is included in the IdLE repository under `src/IdLE.Provider.EntraID
 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
 
 ### Host-Owned Authentication (Required Pattern)
@@ -183,6 +237,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)
@@ -205,20 +299,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
 
@@ -299,6 +380,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.
@@ -366,44 +483,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
 
-- `With.AuthSessionName = 'MicrosoftGraph'`
-- `With.AuthSessionOptions = @{ Role = 'Admin' }` (or other routing keys)
+# 3) Create broker
+$broker = New-IdleAuthSession -SessionMap @{ @{} = $token } -DefaultCredential $token
 
-### Example Step Definition
+# 4) Build provider map
+$providers = @{
+  Identity = $provider
+  AuthSessionBroker = $broker
+}
+
+# 5) Plan + execute
+$plan = New-IdlePlan -WorkflowPath './workflow.psd1' -Request $request -Providers $providers
+$result = Invoke-IdlePlan -Plan $plan -Providers $providers
+```
+
+### 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)
@@ -411,6 +557,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"

From 649903b67d89e56a1512dd382c4bd993e2f873b0 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 7 Feb 2026 20:47:10 +0000
Subject: [PATCH 4/8] Add Testing sections to all remaining provider docs

Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
---
 .../providers/provider-directorysync-entraconnect.md | 12 ++++++++++++
 docs/reference/providers/provider-exchangeonline.md  |  8 ++++++++
 docs/reference/providers/provider-mock.md            |  8 ++++++++
 3 files changed, 28 insertions(+)

diff --git a/docs/reference/providers/provider-directorysync-entraconnect.md b/docs/reference/providers/provider-directorysync-entraconnect.md
index 0d42b067..57906ba0 100644
--- a/docs/reference/providers/provider-directorysync-entraconnect.md
+++ b/docs/reference/providers/provider-directorysync-entraconnect.md
@@ -136,6 +136,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
@@ -226,3 +230,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-exchangeonline.md b/docs/reference/providers/provider-exchangeonline.md
index 82f6eb48..b41d36e5 100644
--- a/docs/reference/providers/provider-exchangeonline.md
+++ b/docs/reference/providers/provider-exchangeonline.md
@@ -203,3 +203,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 2bfe82a5..4423965d 100644
--- a/docs/reference/providers/provider-mock.md
+++ b/docs/reference/providers/provider-mock.md
@@ -178,3 +178,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)

From af5d33a2f8d170b4c8c628b42b17af08e0ee2493 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 7 Feb 2026 20:48:17 +0000
Subject: [PATCH 5/8] Remove redundant Installation section from
 provider-entraID.md

Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
---
 docs/reference/providers/provider-entraID.md | 10 ----------
 1 file changed, 10 deletions(-)

diff --git a/docs/reference/providers/provider-entraID.md b/docs/reference/providers/provider-entraID.md
index 564d0577..ad749e0d 100644
--- a/docs/reference/providers/provider-entraID.md
+++ b/docs/reference/providers/provider-entraID.md
@@ -35,16 +35,6 @@ sidebar_label: Entra ID
 
 ---
 
-## Installation
-
-The provider is included in the IdLE repository under `src/IdLE.Provider.EntraID/`.
-
-```powershell
-Import-Module ./src/IdLE.Provider.EntraID/IdLE.Provider.EntraID.psd1
-```
-
----
-
 ## Contracts and capabilities
 
 ### Contracts implemented

From dea9da431f2bf8c617c4c3e9fbf7a02680cb208f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 7 Feb 2026 21:39:23 +0000
Subject: [PATCH 6/8] Remove Purpose statement from all provider docs

Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
---
 docs/reference/providers/provider-ad.md                      | 5 -----
 .../providers/provider-directorysync-entraconnect.md         | 5 -----
 docs/reference/providers/provider-entraID.md                 | 5 -----
 docs/reference/providers/provider-exchangeonline.md          | 5 -----
 docs/reference/providers/provider-mock.md                    | 5 -----
 5 files changed, 25 deletions(-)

diff --git a/docs/reference/providers/provider-ad.md b/docs/reference/providers/provider-ad.md
index 77eb8e07..c64ded4c 100644
--- a/docs/reference/providers/provider-ad.md
+++ b/docs/reference/providers/provider-ad.md
@@ -3,11 +3,6 @@ title: Provider Reference - IdLE.Provider.AD (Active Directory)
 sidebar_label: Active Directory
 ---
 
-> **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:** `AD` (Active Directory)
diff --git a/docs/reference/providers/provider-directorysync-entraconnect.md b/docs/reference/providers/provider-directorysync-entraconnect.md
index 57906ba0..9be22948 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
diff --git a/docs/reference/providers/provider-entraID.md b/docs/reference/providers/provider-entraID.md
index ad749e0d..ab2ab6c0 100644
--- a/docs/reference/providers/provider-entraID.md
+++ b/docs/reference/providers/provider-entraID.md
@@ -3,11 +3,6 @@ title: Provider Reference - IdLE.Provider.EntraID
 sidebar_label: Entra ID
 ---
 
-> **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:** `EntraID` (Microsoft Entra ID)
diff --git a/docs/reference/providers/provider-exchangeonline.md b/docs/reference/providers/provider-exchangeonline.md
index b41d36e5..42a56d33 100644
--- a/docs/reference/providers/provider-exchangeonline.md
+++ b/docs/reference/providers/provider-exchangeonline.md
@@ -3,11 +3,6 @@ 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.
-
----
-
 ## Summary
 
 - **Provider name:** ExchangeOnline
diff --git a/docs/reference/providers/provider-mock.md b/docs/reference/providers/provider-mock.md
index 4423965d..7284c516 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

From 495401889e3e9fccb6278bc53074ec49d4b985fb Mon Sep 17 00:00:00 2001
From: Matthias <13959569+blindzero@users.noreply.github.com>
Date: Sat, 7 Feb 2026 22:54:11 +0100
Subject: [PATCH 7/8] Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 docs/reference/providers/provider-exchangeonline.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/reference/providers/provider-exchangeonline.md b/docs/reference/providers/provider-exchangeonline.md
index 4dccd230..6b12ee06 100644
--- a/docs/reference/providers/provider-exchangeonline.md
+++ b/docs/reference/providers/provider-exchangeonline.md
@@ -3,6 +3,11 @@ title: Provider Reference - IdLE.Provider.ExchangeOnline
 sidebar_label: ExchangeOnline
 ---
 
+## Purpose
+
+This provider manages Exchange Online mailbox configuration and Out of Office settings as part of IdLE workflows.
+
+---
 ## Summary
 
 - **Provider name:** ExchangeOnline

From f46ee0d916a169943a22c8fc9cbc974b2365f4f2 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 7 Feb 2026 21:56:21 +0000
Subject: [PATCH 8/8] Fix New-IdleAuthSession examples and remove template
 placeholder text

Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
---
 docs/reference/providers/provider-ad.md      | 6 ++----
 docs/reference/providers/provider-entraID.md | 2 +-
 2 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/docs/reference/providers/provider-ad.md b/docs/reference/providers/provider-ad.md
index f157bd0e..fd78eda6 100644
--- a/docs/reference/providers/provider-ad.md
+++ b/docs/reference/providers/provider-ad.md
@@ -33,8 +33,6 @@ sidebar_label: Active Directory
 
 ### Contracts implemented
 
-List the IdLE provider contracts this provider implements and what they mean at a glance.
-
 | Contract | Used by steps for | Notes |
 | --- | --- | --- |
 | Identity provider (implicit) | Identity read/write operations | Supports comprehensive identity lifecycle operations including OU moves |
@@ -198,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
@@ -295,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 @{
diff --git a/docs/reference/providers/provider-entraID.md b/docs/reference/providers/provider-entraID.md
index 4d1d7773..bc633a6b 100644
--- a/docs/reference/providers/provider-entraID.md
+++ b/docs/reference/providers/provider-entraID.md
@@ -489,7 +489,7 @@ $provider = New-IdleEntraIDIdentityProvider
 $token = (Get-AzAccessToken -ResourceUrl "https://graph.microsoft.com").Token
 
 # 3) Create broker
-$broker = New-IdleAuthSession -SessionMap @{ @{} = $token } -DefaultCredential $token
+$broker = New-IdleAuthSession -AuthSessionType OAuth -SessionMap @{ MicrosoftGraph = $token } -DefaultAuthSession $token
 
 # 4) Build provider map
 $providers = @{