From 463fad27363bdaa90c3d29034148aa98979e2f69 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 25 Jan 2026 12:14:15 +0000
Subject: [PATCH 1/6] Initial plan


From eb8ace211ff8d294068f3a1be8db6c5f288e8919 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 25 Jan 2026 12:20:00 +0000
Subject: [PATCH 2/6] Consolidate installation and provider documentation

Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
---
 README.md                                 |  47 +-------
 docs/_sidebar.md                          |  34 ++++--
 docs/advanced/extensibility.md            |  45 ++++----
 docs/getting-started/installation.md      |  96 ++++++++++++++---
 docs/index.md                             |  88 ++++++++++-----
 docs/reference/providers-and-contracts.md | 126 +++++++++++++++++-----
 docs/usage/providers.md                   | 106 +++++-------------
 7 files changed, 314 insertions(+), 228 deletions(-)

diff --git a/README.md b/README.md
index 6afcdef1..8719257c 100644
--- a/README.md
+++ b/README.md
@@ -47,59 +47,16 @@ IdLE aims to be:
 
 ---
 
-## Requirements
-
-- PowerShell **7.x** (`pwsh`)
-- Pester **5.7.1** (for tests)
-- PSScriptAnalyzer **1.24.0** (for tests)
-
----
-
 ## Installation
 
-### Install from PowerShell Gallery (recommended)
+**Quick install:**
 
 ```powershell
 Install-Module -Name IdLE -Scope CurrentUser
 Import-Module IdLE
 ```
 
-> The `IdLE` meta-module loads the bundled nested modules (engine, built-in steps, and the mock provider used by examples)
-> from within the installed package.
-
-### Install from source (contributors / development)
-
-```powershell
-git clone https://github.com/blindzero/IdentityLifecycleEngine
-cd IdentityLifecycleEngine
-
-# Import meta module
-Import-Module ./src/IdLE/IdLE.psd1 -Force
-```
-
-#### What gets loaded when you import `IdLE`
-
-`IdLE` is the **batteries-included** entrypoint. Importing it loads:
-
-- `IdLE.Core` — the workflow engine (step-agnostic)
-- `IdLE.Steps.Common` — first-party built-in steps (e.g. `IdLE.Step.EmitEvent`, `IdLE.Step.EnsureAttribute`)
-
-Built-in steps are **available to the engine by default**, but are intentionally **not exported into the global session state**.
-This keeps your PowerShell session clean while still allowing workflows to reference built-in steps by `Step.Type`.
-
-If you want to call step functions directly (e.g. `Invoke-IdleStepEmitEvent`) you can explicitly import the step pack:
-
-```powershell
-Import-Module ./src/IdLE.Steps.Common/IdLE.Steps.Common.psd1 -Force
-```
-
-#### Engine-only import
-
-Advanced hosts can import the engine without any step packs:
-
-```powershell
-Import-Module ./src/IdLE.Core/IdLE.Core.psd1 -Force
-```
+For detailed installation instructions, requirements, and import options, see **[Installation Guide](docs/getting-started/installation.md)**.
 
 ---
 
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index ac7be075..bc0afb12 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -1,40 +1,52 @@
 - [Home](index.md)
 
-### Overview
+### User Documentation
+
+#### Overview
 
 - [Concept](overview/concept.md)
 
-### Getting started
+#### Getting Started
 
 - [Installation](getting-started/installation.md)
 - [Quickstart](getting-started/quickstart.md)
 
-### Usage
+#### Usage
 
 - [Workflows](usage/workflows.md)
 - [Steps](usage/steps.md)
 - [Providers](usage/providers.md)
 
-### Reference
+#### Reference
 
 - [Cmdlet Reference](reference/cmdlets.md)
+- [Step Catalog](reference/steps.md)
+- [Configuration](reference/configuration.md)
 - [Events and Observability](reference/events-and-observability.md)
 - [Providers and Contracts](reference/providers-and-contracts.md)
+
+#### Provider Guides
+
 - [Active Directory Provider](reference/providers/provider-ad.md)
 - [Entra ID Provider](reference/providers/provider-entraID.md)
-- [Configuration](reference/configuration.md)
-- [Steps and Metadata](reference/steps-and-metadata.md)
-- [Step Catalog](reference/steps.md)
 
-### Specifications
+### Developer Documentation
 
-- [Plan export (JSON)](specs/plan-export.md)
+#### Contributing
+
+- [Contributing](../CONTRIBUTING.md)
+- [Style Guide](../STYLEGUIDE.md)
+- [Agents Manual](../AGENTS.md)
 
-### Advanced
+#### Advanced
 
 - [Architecture](advanced/architecture.md)
-- [Provider Capabilities](advanced/provider-capabilities.md)
 - [Security](advanced/security.md)
 - [Extensibility](advanced/extensibility.md)
+- [Provider Capabilities](advanced/provider-capabilities.md)
 - [Testing](advanced/testing.md)
 - [Releasing](advanced/releases.md)
+
+#### Specifications
+
+- [Plan export (JSON)](specs/plan-export.md)
diff --git a/docs/advanced/extensibility.md b/docs/advanced/extensibility.md
index 266299f2..fb7f07af 100644
--- a/docs/advanced/extensibility.md
+++ b/docs/advanced/extensibility.md
@@ -2,6 +2,8 @@
 
 IdLE is designed for change through modules instead of forks.
 
+---
+
 ## Add a new step
 
 A new step typically involves:
@@ -17,6 +19,8 @@ Steps can emit structured events using the execution context contract:
 
 Keep steps host-agnostic: do not call UI APIs directly.
 
+---
+
 ## Add a new provider
 
 Providers are responsible for interacting with external systems (directories,
@@ -29,31 +33,9 @@ A new provider typically involves:
 3. Auth session acquisition via host execution context (AuthSessionBroker)
 4. Contract tests and unit tests
 
-### Auth session acquisition (AuthSessionBroker)
-
-IdLE keeps authentication out of the core engine. Hosts provide an auth session broker
-that is responsible for obtaining and caching authenticated runtime handles (tokens,
-Graph clients, Exchange Online sessions, LDAP binds, etc.).
-
-- Hosts MUST pass the broker via `Providers.AuthSessionBroker`.
-- Providers SHOULD acquire sessions through the execution context:
-  - `Context.AcquireAuthSession(Name, Options)`
-
-Broker contract:
-
-- The broker MUST expose an `AcquireAuthSession(Name, Options)` method.
-- `Name` is a routing key (for example: `MicrosoftGraph`, `ExchangeOnline`, `ActiveDirectory`).
-- `Options` is optional (`$null` is treated as an empty hashtable) and must be data-only:
-  - ScriptBlock values are rejected, including nested values.
-- The engine enriches options with `CorrelationId` and `Actor` when available.
-- The engine deep-copies `Options` before invoking the broker; brokers MUST treat
-  options as immutable and MUST NOT mutate nested values.
-
-Security notes:
+For detailed provider contracts, responsibilities, and auth session acquisition patterns, see:
 
-- Do not embed credentials directly in `Options`.
-- Treat `Options` as configuration input, not a secret store.
-- Use host secret management and keep secrets out of plans, events, and exports.
+**→ [Providers and Contracts](../reference/providers-and-contracts.md)** — Provider concepts and AuthSessionBroker contract
 
 ### Capability Advertisement
 
@@ -68,6 +50,8 @@ The full contract, naming rules, and validation behavior are described in
 Providers should include the corresponding provider capability contract tests
 to ensure compliance.
 
+---
+
 ## Versioning strategy
 
 Keep workflows stable by treating step identifiers as contracts.
@@ -76,6 +60,8 @@ If behavior changes incompatibly:
 - introduce a new step id or explicit handler mapping
 - keep the old step id available for older workflows
 
+---
+
 ## Keep the core headless
 
 Do not add:
@@ -87,6 +73,8 @@ Do not add:
 
 Those belong in a host application.
 
+---
+
 ## Register step handlers
 
 Steps are executed via a host-provided step registry.
@@ -99,3 +87,12 @@ ScriptBlock handlers are intentionally not supported as a secure default.
 Step handlers may optionally declare a `Context` parameter.
 For backwards compatibility, the engine passes `-Context` only when the handler
 supports it.
+
+---
+
+## Related
+
+- [Providers and Contracts](../reference/providers-and-contracts.md) — Provider extension guidance
+- [Provider Capabilities](provider-capabilities.md) — Capability system
+- [Architecture](architecture.md) — Design principles
+- [Testing](testing.md) — Test strategy
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index 241588b6..0d5c962e 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -1,9 +1,21 @@
 # Installation
 
+This is the **single source of truth** for installing and importing IdLE.
+
 IdLE can be consumed either from the **PowerShell Gallery** (recommended for most users) or directly from the
 repository source (useful for contributors and development scenarios).
 
-## Install from PowerShell Gallery
+---
+
+## Requirements
+
+- PowerShell **7.x** (`pwsh`)
+- Pester **5.7.1+** (for running tests, optional)
+- PSScriptAnalyzer **1.24.0+** (for running static analysis, optional)
+
+---
+
+## Install from PowerShell Gallery (recommended)
 
 From a PowerShell 7 prompt:
 
@@ -12,24 +24,18 @@ Install-Module -Name IdLE -Scope CurrentUser
 Import-Module IdLE
 ```
 
-### Verify install
+### Verify installation
 
 ```powershell
 Get-Module IdLE -ListAvailable | Select-Object Name, Version, Path
-Get-Command -Module IdLE | Select-Object -First 10
+Get-Command -Module IdLE
 ```
 
-> Note: The `IdLE` meta-module loads the bundled nested modules (e.g. `IdLE.Core`, built-in steps, and the mock provider
-> used by examples) from within the installed package.
+---
 
 ## Install from repository source
 
-This path is primarily intended for contributors.
-
-### Requirements
-
-- PowerShell **7+** (`pwsh`)
-- Pester **5+** (for tests)
+This path is primarily intended for contributors and development scenarios.
 
 ### Clone and import
 
@@ -43,17 +49,75 @@ cd IdentityLifecycleEngine
 Import-Module ./src/IdLE/IdLE.psd1 -Force
 ```
 
-## Optional step modules
+### Verify installation (source)
+
+```powershell
+Get-Command -Module IdLE
+Get-Command -Module IdLE.Core
+```
+
+---
+
+## What gets imported
+
+### Default: `IdLE` meta-module (batteries included)
+
+`IdLE` is the **batteries-included** entrypoint. Importing it loads:
+
+- **IdLE.Core** — the workflow engine (step-agnostic)
+- **IdLE.Steps.Common** — first-party built-in steps (e.g. `IdLE.Step.EmitEvent`, `IdLE.Step.EnsureAttribute`)
+
+Built-in steps are **available to the engine by default**, but are intentionally **not exported into the global session state**.
+This keeps your PowerShell session clean while still allowing workflows to reference built-in steps by `Step.Type`.
+
+**When to use:** Most users and production scenarios.
+
+### Advanced: Import built-in steps explicitly
 
-The core engine is step-agnostic. To use built-in steps, import the step module(s) you need:
+If you want to call step functions directly (e.g. `Invoke-IdleStepEmitEvent`) you can explicitly import the step pack:
 
 ```powershell
 Import-Module ./src/IdLE.Steps.Common/IdLE.Steps.Common.psd1 -Force
 ```
 
-## Verify install (source)
+**When to use:** Advanced testing, debugging, or building custom step compositions.
+
+### Advanced: Engine-only import
+
+Advanced hosts can import the engine without any step packs:
 
 ```powershell
-Get-Command -Module IdLE
-Get-Command -Module IdLE.Core
+Import-Module ./src/IdLE.Core/IdLE.Core.psd1 -Force
+```
+
+**When to use:** Custom host implementations that provide their own step registry and providers.
+
+---
+
+## Provider modules (optional)
+
+The core engine is provider-agnostic. To use provider implementations, install or import the provider modules you need:
+
+### Active Directory Provider
+
+```powershell
+# From source
+Import-Module ./src/IdLE.Provider.AD/IdLE.Provider.AD.psd1 -Force
+```
+
+### Entra ID Provider
+
+```powershell
+# From source
+Import-Module ./src/IdLE.Provider.EntraID/IdLE.Provider.EntraID.psd1 -Force
 ```
+
+Provider modules are **not** included in the IdLE meta-module and must be imported separately when needed.
+
+---
+
+## Next steps
+
+- [Quickstart](quickstart.md) — Run the demo and learn the Plan → Execute flow
+- [Providers](../usage/providers.md) — Learn about provider aliases and usage
+- [Workflows](../usage/workflows.md) — Learn how to define workflows
diff --git a/docs/index.md b/docs/index.md
index a2fb2e44..9502a750 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -7,46 +7,78 @@ Welcome to the documentation for **IdentityLifecycleEngine (IdLE)**.
 IdLE is a **generic, headless, configuration-driven** lifecycle orchestration engine
 for identity and account processes (Joiner / Mover / Leaver) built for **PowerShell 7+**.
 
-## Start here
+---
 
-- [Overview: What is IdLE?](overview/concept.md)
-- [Getting started: Installation](getting-started/installation.md)
-- [Getting started: Quickstart](getting-started/quickstart.md)
+## User Documentation
 
-## Usage
+For admins, operators, and workflow authors:
 
-- [Workflows](usage/workflows.md)
-- [Steps](usage/steps.md)
-- [Providers](usage/providers.md)
+### Getting Started
 
-## Reference
+- [Installation](getting-started/installation.md) — Install and import guide (requirements, import options)
+- [Quickstart](getting-started/quickstart.md) — Run the demo and understand Plan → Execute flow
 
-- [Cmdlet Reference](reference/cmdlets.md)
-- [Events and Observability](reference/events-and-observability.md)
-- [Providers and Contracts](reference/providers-and-contracts.md)
-- [Configuration](reference/configuration.md)
-- [Steps and Metadata](reference/steps-and-metadata.md)
-- [Step Catalog](reference/steps.md)
+### Usage
 
-## Specifications
+- [Workflows](usage/workflows.md) — Define lifecycle workflows
+- [Steps](usage/steps.md) — Use and configure steps
+- [Providers](usage/providers.md) — Provider aliases and injection
+
+### Overview
+
+- [Concept](overview/concept.md) — What is IdLE and why does it exist
+
+### Reference
+
+- [Cmdlet Reference](reference/cmdlets.md) — Public cmdlets and usage
+- [Step Catalog](reference/steps.md) — Built-in step reference (generated)
+- [Configuration](reference/configuration.md) — Configuration schema reference
+- [Events and Observability](reference/events-and-observability.md) — Event structure and streaming
+- [Providers and Contracts](reference/providers-and-contracts.md) — Provider responsibilities and contracts
+
+### Provider Guides
+
+- [Active Directory Provider](reference/providers/provider-ad.md)
+- [Entra ID Provider](reference/providers/provider-entraID.md)
+
+---
+
+## Developer Documentation
+
+For contributors, extenders, and maintainers:
+
+### Contributing
+
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — Contribution workflow, PR guidelines, quality gates
+- [STYLEGUIDE.md](../STYLEGUIDE.md) — Code style and documentation rules
+- [AGENTS.md](../AGENTS.md) — Agent operating manual
+
+### Advanced Topics
+
+- [Architecture](advanced/architecture.md) — Design principles and decisions
+- [Security](advanced/security.md) — Trust boundaries and threat model
+- [Extensibility](advanced/extensibility.md) — Add steps and providers
+- [Provider Capabilities](advanced/provider-capabilities.md) — Capability system and validation
+- [Testing](advanced/testing.md) — Test strategy and tooling
+- [Releasing](advanced/releases.md) — Maintainer release process
+
+### Specifications
 
 Specifications are **normative contracts** (machine-readable formats / stable interfaces)
 used between IdLE and its hosts.
 
 - [Plan export (JSON)](specs/plan-export.md)
 
-## Advanced
+---
+
+## Examples
+
+- [Examples README](../examples/README.md) — Runnable examples and demo workflows
 
-- [Architecture](advanced/architecture.md)
-- [Provider Capabilities](advanced/provider-capabilities.md)
-- [Security](advanced/security.md)
-- [Extensibility](advanced/extensibility.md)
-- [Testing](advanced/testing.md)
-- [Releasing](advanced/releases.md)
+---
 
-## Repository links
+## Quick Links
 
-- [Project README](../README.md)
-- [Contributing](../CONTRIBUTING.md)
-- [Style guide](../STYLEGUIDE.md)
-- [Examples](../examples/README.md)
+- [Project README](../README.md) — Repository landing page
+- [GitHub Issues](https://github.com/blindzero/IdentityLifecycleEngine/issues)
+- [GitHub Releases](https://github.com/blindzero/IdentityLifecycleEngine/releases)
diff --git a/docs/reference/providers-and-contracts.md b/docs/reference/providers-and-contracts.md
index c6d4c0ef..0e741239 100644
--- a/docs/reference/providers-and-contracts.md
+++ b/docs/reference/providers-and-contracts.md
@@ -1,5 +1,9 @@
 # Providers and Contracts
 
+**This is the single source of truth for provider concepts, contracts, and usage.**
+
+---
+
 ## Purpose
 
 Providers in IdLE are responsible for interacting with external systems such as
@@ -12,25 +16,6 @@ the engine portable, testable, and host-agnostic.
 
 ---
 
-## Scope
-
-This document covers:
-
-- The role of providers in IdLE
-- The meaning of contracts and why they exist
-- Responsibility boundaries between engine, steps, providers, and host
-- Conceptual provider categories
-- Recommended usage patterns
-
-Out of scope:
-
-- Detailed API or method reference
-- Provider configuration schema
-- Step-specific provider requirements
-- Implementation details of concrete providers
-
----
-
 ## Concept
 
 ### Providers as infrastructure adapters
@@ -39,7 +24,7 @@ A provider is an **adapter to an external system**.
 
 Examples include:
 
-- identity directories
+- identity directories (Active Directory, Entra ID)
 - account stores
 - entitlement systems
 - mock or file-based systems used for testing
@@ -83,7 +68,7 @@ conventions rather than strict type systems.
 
 IdLE favors implicit contracts because they:
 
-- align with PowerShell’s object-based pipeline model
+- align with PowerShell's object-based pipeline model
 - avoid rigid inheritance hierarchies
 - keep providers easy to mock and test
 - allow gradual evolution without breaking existing implementations
@@ -96,6 +81,8 @@ The contract is expressed through:
 
 ---
 
+## Responsibilities
+
 ### Separation of responsibilities
 
 Clear separation is essential for maintainability:
@@ -115,6 +102,10 @@ Clear separation is essential for maintainability:
   - Implement infrastructure-specific behavior
   - Fulfill contracts expected by steps
   - Encapsulate external system details
+  - Authenticate and manage sessions
+  - Translate generic operations to system APIs
+  - Are mockable for tests
+  - Avoid global state
 
 - **Host**
   - Selects and configures providers
@@ -123,11 +114,77 @@ Clear separation is essential for maintainability:
 
 This separation keeps the core engine free of environmental assumptions.
 
+**Important:** Steps should not handle authentication. Authentication is a provider responsibility via AuthSessionBroker.
+
 ---
 
 ## Usage
 
-### Typical provider categories
+### Provider Aliases
+
+When you supply providers to IdLE, you use a **hashtable** that maps **alias names** to **provider instances**:
+
+```powershell
+$providers = @{
+    Identity = $adProvider
+}
+```
+
+#### Alias Naming
+
+The alias name (hashtable key) is **completely flexible** and chosen by you (the host):
+
+- It can be any valid PowerShell hashtable key
+- Common patterns:
+  - **Role-based**: `Identity`, `Entitlement`, `Messaging` (when you have one provider per role)
+  - **Instance-based**: `SourceAD`, `TargetEntra`, `ProdForest`, `DevSystem` (when you have multiple providers)
+- The built-in steps default to `'Identity'` if no `Provider` is specified in the step's `With` block
+
+#### How Workflows Reference Providers
+
+Workflow steps can specify which provider to use via the `Provider` key in the `With` block:
+
+```powershell
+@{
+    Name = 'Create user in source'
+    Type = 'IdLE.Step.CreateIdentity'
+    With = @{
+        IdentityKey = 'newuser'
+        Attributes  = @{ ... }
+        Provider    = 'SourceAD'  # References the alias from the provider hashtable
+    }
+}
+```
+
+If `Provider` is not specified, it defaults to `'Identity'`:
+
+```powershell
+# These are equivalent when Provider is not specified:
+With = @{ IdentityKey = 'user1'; Name = 'Department'; Value = 'IT' }
+With = @{ IdentityKey = 'user1'; Name = 'Department'; Value = 'IT'; Provider = 'Identity' }
+```
+
+#### Multiple Provider Example
+
+```powershell
+# Create provider instances
+$sourceAD = New-IdleADIdentityProvider -Credential $sourceCred
+$targetEntra = New-IdleEntraIdentityProvider -Credential $targetCred
+
+# Map to custom aliases
+$providers = @{
+    SourceAD    = $sourceAD
+    TargetEntra = $targetEntra
+}
+
+# Workflow steps reference the aliases
+# Step 1: With = @{ Provider = 'SourceAD'; ... }
+# Step 2: With = @{ Provider = 'TargetEntra'; ... }
+```
+
+---
+
+### Provider Categories
 
 While IdLE does not enforce provider categories, common conceptual groupings exist:
 
@@ -226,6 +283,26 @@ Guidance:
 - New step handlers should accept `Context` to access providers, event sink, and auth session acquisition.
 - Existing handlers without `Context` continue to work unchanged.
 
+---
+
+## Testing providers
+
+Providers should have contract tests that verify behavior against a mock or test harness.
+Unit tests must not call live systems.
+
+For testing guidance, see [Testing](../advanced/testing.md).
+
+---
+
+## Trust and security
+
+Providers and the step registry are host-controlled extension points and should be treated as trusted code.
+Workflows and lifecycle requests are data-only and must not contain executable objects.
+
+For details, see [Security](../advanced/security.md).
+
+---
+
 ## Common pitfalls
 
 ### Treating providers as part of the engine
@@ -264,7 +341,8 @@ should be clarified or refined.
 
 ## Related documentation
 
-- [Steps](../usage/steps.md)
-- [Providers](../usage/providers.md)
 - [Workflows](../usage/workflows.md)
+- [Steps](../usage/steps.md)
 - [Architecture](../advanced/architecture.md)
+- [Extensibility](../advanced/extensibility.md)
+- [Provider Capabilities](../advanced/provider-capabilities.md)
diff --git a/docs/usage/providers.md b/docs/usage/providers.md
index 4eb4ac24..3c38fb89 100644
--- a/docs/usage/providers.md
+++ b/docs/usage/providers.md
@@ -1,105 +1,51 @@
 # Providers
 
-Providers are the system-specific adapters (for example: Active Directory, Entra ID, Exchange Online).
+Providers are the system-specific adapters (for example: Active Directory, Entra ID, Exchange Online) that connect
+IdLE workflows to external systems.
 
-The engine core talks only to provider contracts.
+For complete provider documentation, including concepts, contracts, authentication, usage patterns, and examples, see:
 
-## Responsibilities
+**→ [Providers and Contracts](../reference/providers-and-contracts.md)** (single source of truth)
 
-Providers typically:
+---
 
-- authenticate and manage sessions
-- translate generic operations to system APIs
-- are mockable for tests
-- avoid global state
+## Quick Reference
 
-Steps should not handle authentication.
+### What are providers?
 
-## Provider Aliases
+Providers:
 
-When you supply providers to IdLE, you use a **hashtable** that maps **alias names** to **provider instances**:
+- Adapt IdLE workflows to external systems
+- Handle authentication via AuthSessionBroker
+- Translate generic operations to system APIs
+- Are mockable for tests
 
-```powershell
-$providers = @{
-    Identity = $adProvider
-}
-```
-
-### Alias Naming
-
-The alias name (hashtable key) is **completely flexible** and chosen by you (the host):
-
-- It can be any valid PowerShell hashtable key
-- Common patterns:
-  - **Role-based**: `Identity`, `Entitlement`, `Messaging` (when you have one provider per role)
-  - **Instance-based**: `SourceAD`, `TargetEntra`, `ProdForest`, `DevSystem` (when you have multiple providers)
-- The built-in steps default to `'Identity'` if no `Provider` is specified in the step's `With` block
-
-### How Workflows Reference Providers
-
-Workflow steps can specify which provider to use via the `Provider` key in the `With` block:
-
-```powershell
-@{
-    Name = 'Create user in source'
-    Type = 'IdLE.Step.CreateIdentity'
-    With = @{
-        IdentityKey = 'newuser'
-        Attributes  = @{ ... }
-        Provider    = 'SourceAD'  # References the alias from the provider hashtable
-    }
-}
-```
-
-If `Provider` is not specified, it defaults to `'Identity'`:
+See: [Provider responsibilities](../reference/providers-and-contracts.md#responsibilities)
 
-```powershell
-# These are equivalent when Provider is not specified:
-With = @{ IdentityKey = 'user1'; Name = 'Department'; Value = 'IT' }
-With = @{ IdentityKey = 'user1'; Name = 'Department'; Value = 'IT'; Provider = 'Identity' }
-```
+### How to use providers
 
-### Multiple Provider Example
+Providers are supplied to plan execution as a hashtable with alias names:
 
 ```powershell
-# Create provider instances
-$sourceAD = New-IdleADIdentityProvider -Credential $sourceCred
-$targetEntra = New-IdleEntraIdentityProvider -Credential $targetCred
-
-# Map to custom aliases
 $providers = @{
-    SourceAD   = $sourceAD
-    TargetEntra = $targetEntra
+    Identity = New-IdleMockIdentityProvider
 }
 
-# Workflow steps reference the aliases
-# Step 1: With = @{ Provider = 'SourceAD'; ... }
-# Step 2: With = @{ Provider = 'TargetEntra'; ... }
+$result = Invoke-IdlePlan -Plan $plan -Providers $providers
 ```
 
-## Acquire sessions via host
+See: [Provider aliases and usage](../reference/providers-and-contracts.md#usage)
 
-Providers can acquire sessions through a host-provided execution context callback:
+### Available providers
 
-- the host may allow interactive auth (or disallow it in CI)
-- the host may cache sessions
-- the provider declares requirements and asks for a session
+- [Active Directory Provider](../reference/providers/provider-ad.md)
+- [Entra ID Provider](../reference/providers/provider-entraID.md)
 
-This keeps IdLE.Core headless while supporting real-world auth flows.
-
-## Testing providers
-
-Providers should have contract tests that verify behavior against a mock or test harness.
-Unit tests must not call live systems.
+---
 
 ## Related
 
-- [Testing](../advanced/testing.md)
-- [Architecture](../advanced/architecture.md)
-
-## Trust and security
-
-Providers and the step registry are host-controlled extension points and should be treated as trusted code.
-Workflows and lifecycle requests are data-only and must not contain executable objects.
-
-For details, see `docs/advanced/security.md`.
+- [Providers and Contracts](../reference/providers-and-contracts.md) — Complete provider reference
+- [Workflows](workflows.md) — How workflows reference providers
+- [Steps](steps.md) — How steps use providers
+- [Extensibility](../advanced/extensibility.md) — How to create custom providers

From add5144d1272ec473b8996dae633870b39af3145 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 25 Jan 2026 12:21:20 +0000
Subject: [PATCH 3/6] Consolidate overview/concept documentation and slim down
 README

Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
---
 README.md                | 28 ++++++----------------------
 docs/overview/concept.md | 28 ++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 8719257c..3c7de656 100644
--- a/README.md
+++ b/README.md
@@ -17,33 +17,17 @@ It helps you standardize identity lifecycle processes across environments by sep
 - **what** should happen (workflow definition)
 - from **how** it happens (providers/adapters)
 
----
-
-## Why IdLE?
-
-Identity lifecycle automation tends to become:
-
-- tightly coupled to one system or one environment
-- hard to test
-- hard to change (logic baked into scripts)
-
-IdLE aims to be:
-
-- **portable** (run anywhere PowerShell 7 runs)
-- **modular** (steps + providers are swappable)
-- **testable** (Pester-friendly; mock providers)
-- **configuration-driven** (workflows as data)
+For a complete overview of concepts, architecture, and why IdLE exists, see **[Overview: Concept](docs/overview/concept.md)**.
 
 ---
 
-## Features
+## Key Features
 
-- **Joiner / Mover / Leaver** orchestration (and custom life cycle events)
 - **Plan → Execute** flow (preview actions before applying them)
-- **Plugin step model** (`Test` / `Invoke`, optional `Rollback` later)
-- **Provider/Adapter pattern** (directory, SaaS, REST, file/mock…)
-- **Structured events** for audit/progress (CorrelationId, Actor, step results)
-- **Idempotent execution** (steps can be written to converge state)
+- **Configuration-driven** (workflows as data, no code in config)
+- **Modular** (steps + providers are swappable)
+- **Portable** (PowerShell 7+, runs anywhere)
+- **Testable** (Pester-friendly; mock providers)
 
 ---
 
diff --git a/docs/overview/concept.md b/docs/overview/concept.md
index f5fe6e01..c16bf71f 100644
--- a/docs/overview/concept.md
+++ b/docs/overview/concept.md
@@ -1,5 +1,7 @@
 # Overview
 
+**This is the single source of truth for what IdLE is and why it exists.**
+
 IdLE (IdentityLifecycleEngine) is a **generic orchestration framework** for identity lifecycle automation.
 
 The key idea is to **separate intent from implementation**:
@@ -7,6 +9,8 @@ The key idea is to **separate intent from implementation**:
 - **What** should happen is defined in a **workflow** (data-only configuration).
 - **How** it happens is implemented by **steps** and **providers** (pluggable modules).
 
+---
+
 ## Why IdLE exists
 
 Identity lifecycle automation often turns into long scripts that are:
@@ -22,6 +26,19 @@ IdLE aims to be:
 - **testable** (Pester-friendly, mock providers)
 - **configuration-driven** (workflows as data)
 
+---
+
+## Key Features
+
+- **Joiner / Mover / Leaver** orchestration (and custom lifecycle events)
+- **Plan → Execute** flow (preview actions before applying them)
+- **Plugin step model** (`Test` / `Invoke`, optional `Rollback` later)
+- **Provider/Adapter pattern** (directory, SaaS, REST, file/mock…)
+- **Structured events** for audit/progress (CorrelationId, Actor, step results)
+- **Idempotent execution** (steps can be written to converge state)
+
+---
+
 ## Core concepts
 
 ### Request
@@ -47,6 +64,8 @@ Execution runs **only the plan** (no re-planning). This supports:
 - repeatability
 - deterministic audits
 
+---
+
 ## Non-goals (V1)
 
 IdLE.Core stays headless and avoids responsibilities that belong to a host application:
@@ -55,3 +74,12 @@ IdLE.Core stays headless and avoids responsibilities that belong to a host appli
 - no interactive prompts
 - no authentication flows inside steps
 - no dynamic code execution from configuration
+
+---
+
+## Next Steps
+
+- [Installation](../getting-started/installation.md) — Install and import guide
+- [Quickstart](../getting-started/quickstart.md) — Run the demo
+- [Architecture](../advanced/architecture.md) — Design principles and decisions
+- [Workflows](../usage/workflows.md) — Define lifecycle workflows

From 414547a34ffce41a4d05f2e27124ded2241d5bbc Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 25 Jan 2026 12:47:05 +0000
Subject: [PATCH 4/6] Address PR feedback: improve README, remove SST markers,
 clarify providers, enhance extensibility

Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
---
 README.md                                 | 29 ++++++++++++++++++-----
 docs/advanced/extensibility.md            | 17 +++++++++++--
 docs/getting-started/installation.md      | 25 +++----------------
 docs/overview/concept.md                  | 26 ++++++++++++++++++--
 docs/reference/providers-and-contracts.md |  4 ----
 5 files changed, 65 insertions(+), 36 deletions(-)

diff --git a/README.md b/README.md
index 3c7de656..63eafe19 100644
--- a/README.md
+++ b/README.md
@@ -15,19 +15,36 @@
 It helps you standardize identity lifecycle processes across environments by separating:
 
 - **what** should happen (workflow definition)
-- from **how** it happens (providers/adapters)
+- from **how** it happens (providers)
 
-For a complete overview of concepts, architecture, and why IdLE exists, see **[Overview: Concept](docs/overview/concept.md)**.
+---
+
+## Why IdLE?
+
+Identity lifecycle automation tends to become:
+
+- tightly coupled to one system or one environment
+- hard to test
+- hard to change (logic baked into scripts)
+
+IdLE aims to be:
+
+- **portable** (run anywhere PowerShell 7 runs)
+- **modular** (steps + providers are swappable)
+- **testable** (Pester-friendly; mock providers)
+- **configuration-driven** (workflows as data)
+- **extensible** (add custom steps and providers)
+
+For a complete overview of concepts and architecture, see **[Overview: Concept](docs/overview/concept.md)**.
 
 ---
 
 ## Key Features
 
 - **Plan → Execute** flow (preview actions before applying them)
-- **Configuration-driven** (workflows as data, no code in config)
-- **Modular** (steps + providers are swappable)
-- **Portable** (PowerShell 7+, runs anywhere)
-- **Testable** (Pester-friendly; mock providers)
+- **Joiner / Mover / Leaver** orchestration (and custom lifecycle events)
+- **Plugin step model** (idempotent, provider-agnostic)
+- **Structured events** for audit/progress (CorrelationId, Actor, step results)
 
 ---
 
diff --git a/docs/advanced/extensibility.md b/docs/advanced/extensibility.md
index fb7f07af..bbccd54f 100644
--- a/docs/advanced/extensibility.md
+++ b/docs/advanced/extensibility.md
@@ -33,9 +33,22 @@ A new provider typically involves:
 3. Auth session acquisition via host execution context (AuthSessionBroker)
 4. Contract tests and unit tests
 
-For detailed provider contracts, responsibilities, and auth session acquisition patterns, see:
+### Auth session acquisition
 
-**→ [Providers and Contracts](../reference/providers-and-contracts.md)** — Provider concepts and AuthSessionBroker contract
+IdLE keeps authentication out of the core engine. Providers acquire sessions through the execution context:
+
+- `Context.AcquireAuthSession(Name, Options)`
+
+Key points:
+
+- Hosts provide an AuthSessionBroker via `Providers.AuthSessionBroker`
+- Providers request sessions by name (e.g., `MicrosoftGraph`, `ActiveDirectory`)
+- Options are data-only (ScriptBlocks rejected)
+- The broker handles caching, interactive auth policy, and secret management
+
+For detailed contract specifications and usage patterns, see:
+
+**→ [Providers and Contracts](../reference/providers-and-contracts.md)** — Complete provider contracts and AuthSessionBroker details
 
 ### Capability Advertisement
 
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index 0d5c962e..ed3e6dc8 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -1,7 +1,5 @@
 # Installation
 
-This is the **single source of truth** for installing and importing IdLE.
-
 IdLE can be consumed either from the **PowerShell Gallery** (recommended for most users) or directly from the
 repository source (useful for contributors and development scenarios).
 
@@ -72,16 +70,6 @@ This keeps your PowerShell session clean while still allowing workflows to refer
 
 **When to use:** Most users and production scenarios.
 
-### Advanced: Import built-in steps explicitly
-
-If you want to call step functions directly (e.g. `Invoke-IdleStepEmitEvent`) you can explicitly import the step pack:
-
-```powershell
-Import-Module ./src/IdLE.Steps.Common/IdLE.Steps.Common.psd1 -Force
-```
-
-**When to use:** Advanced testing, debugging, or building custom step compositions.
-
 ### Advanced: Engine-only import
 
 Advanced hosts can import the engine without any step packs:
@@ -96,23 +84,16 @@ Import-Module ./src/IdLE.Core/IdLE.Core.psd1 -Force
 
 ## Provider modules (optional)
 
-The core engine is provider-agnostic. To use provider implementations, install or import the provider modules you need:
+The core engine is provider-agnostic. Provider modules are **packaged with IdLE** but must be **imported separately** when needed.
 
-### Active Directory Provider
+Example:
 
 ```powershell
 # From source
 Import-Module ./src/IdLE.Provider.AD/IdLE.Provider.AD.psd1 -Force
 ```
 
-### Entra ID Provider
-
-```powershell
-# From source
-Import-Module ./src/IdLE.Provider.EntraID/IdLE.Provider.EntraID.psd1 -Force
-```
-
-Provider modules are **not** included in the IdLE meta-module and must be imported separately when needed.
+For a complete list of available providers and usage details, see **[Providers](../usage/providers.md)**.
 
 ---
 
diff --git a/docs/overview/concept.md b/docs/overview/concept.md
index c16bf71f..63d44528 100644
--- a/docs/overview/concept.md
+++ b/docs/overview/concept.md
@@ -1,7 +1,5 @@
 # Overview
 
-**This is the single source of truth for what IdLE is and why it exists.**
-
 IdLE (IdentityLifecycleEngine) is a **generic orchestration framework** for identity lifecycle automation.
 
 The key idea is to **separate intent from implementation**:
@@ -66,6 +64,30 @@ Execution runs **only the plan** (no re-planning). This supports:
 
 ---
 
+## Building Blocks
+
+### Steps
+
+**Steps** are reusable plugins that define convergence logic. They:
+
+- Operate idempotently (converge towards desired state)
+- Are provider-agnostic (use contracts, not direct system calls)
+- Emit structured events for audit and progress
+
+Learn more: [Steps](../usage/steps.md) | [Step Catalog](../reference/steps.md)
+
+### Providers
+
+**Providers** are system-specific adapters that connect workflows to external systems. They:
+
+- Authenticate and manage sessions
+- Translate generic operations to system APIs
+- Are mockable for tests
+
+Learn more: [Providers](../usage/providers.md) | [Providers and Contracts](../reference/providers-and-contracts.md)
+
+---
+
 ## Non-goals (V1)
 
 IdLE.Core stays headless and avoids responsibilities that belong to a host application:
diff --git a/docs/reference/providers-and-contracts.md b/docs/reference/providers-and-contracts.md
index 0e741239..7392e75e 100644
--- a/docs/reference/providers-and-contracts.md
+++ b/docs/reference/providers-and-contracts.md
@@ -1,9 +1,5 @@
 # Providers and Contracts
 
-**This is the single source of truth for provider concepts, contracts, and usage.**
-
----
-
 ## Purpose
 
 Providers in IdLE are responsible for interacting with external systems such as

From 7f5ccf8609497abc931a5d70bc021287d70a18b9 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 25 Jan 2026 13:02:34 +0000
Subject: [PATCH 5/6] Restore note about IdLE meta-module loading nested
 modules

Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
---
 docs/getting-started/installation.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index ed3e6dc8..053ead88 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -22,6 +22,9 @@ Install-Module -Name IdLE -Scope CurrentUser
 Import-Module IdLE
 ```
 
+> Note: The `IdLE` meta-module loads the bundled nested modules (e.g. `IdLE.Core`, built-in steps, and the mock provider
+> used by examples) from within the installed package.
+
 ### Verify installation
 
 ```powershell

From c2c82b79d00b4925b1b0b5e9ae8db71a01597e31 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 25 Jan 2026 13:44:33 +0000
Subject: [PATCH 6/6] Fix cmdlet name: New-IdleEntraIDIdentityProvider (correct
 spelling)

Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
---
 docs/reference/providers-and-contracts.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/reference/providers-and-contracts.md b/docs/reference/providers-and-contracts.md
index 7392e75e..bfef3f17 100644
--- a/docs/reference/providers-and-contracts.md
+++ b/docs/reference/providers-and-contracts.md
@@ -165,7 +165,7 @@ With = @{ IdentityKey = 'user1'; Name = 'Department'; Value = 'IT'; Provider = '
 ```powershell
 # Create provider instances
 $sourceAD = New-IdleADIdentityProvider -Credential $sourceCred
-$targetEntra = New-IdleEntraIdentityProvider -Credential $targetCred
+$targetEntra = New-IdleEntraIDIdentityProvider -Credential $targetCred
 
 # Map to custom aliases
 $providers = @{