diff --git a/README.md b/README.md
index 6afcdef1..63eafe19 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@
 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)
 
 ---
 
@@ -33,73 +33,31 @@ IdLE aims to be:
 - **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)**.
 
 ---
 
-## 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…)
+- **Joiner / Mover / Leaver** orchestration (and custom lifecycle events)
+- **Plugin step model** (idempotent, provider-agnostic)
 - **Structured events** for audit/progress (CorrelationId, Actor, step results)
-- **Idempotent execution** (steps can be written to converge state)
-
----
-
-## 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..bbccd54f 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,22 @@ A new provider typically involves:
 3. Auth session acquisition via host execution context (AuthSessionBroker)
 4. Contract tests and unit tests
 
-### Auth session acquisition (AuthSessionBroker)
+### Auth session acquisition
 
-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.).
+IdLE keeps authentication out of the core engine. Providers acquire sessions through the execution context:
 
-- Hosts MUST pass the broker via `Providers.AuthSessionBroker`.
-- Providers SHOULD acquire sessions through the execution context:
-  - `Context.AcquireAuthSession(Name, Options)`
+- `Context.AcquireAuthSession(Name, Options)`
 
-Broker contract:
+Key points:
 
-- 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.
+- 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
 
-Security notes:
+For detailed contract specifications and usage 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)** — Complete provider contracts and AuthSessionBroker details
 
 ### Capability Advertisement
 
@@ -68,6 +63,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 +73,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 +86,8 @@ Do not add:
 
 Those belong in a host application.
 
+---
+
 ## Register step handlers
 
 Steps are executed via a host-provided step registry.
@@ -99,3 +100,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..053ead88 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -3,7 +3,17 @@
 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 +22,21 @@ Install-Module -Name IdLE -Scope CurrentUser
 Import-Module IdLE
 ```
 
-### Verify install
+> 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
 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 +50,58 @@ 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
+```
+
+---
 
-The core engine is step-agnostic. To use built-in steps, import the step module(s) you need:
+## 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: Engine-only import
+
+Advanced hosts can import the engine without any step packs:
 
 ```powershell
-Import-Module ./src/IdLE.Steps.Common/IdLE.Steps.Common.psd1 -Force
+Import-Module ./src/IdLE.Core/IdLE.Core.psd1 -Force
 ```
 
-## Verify install (source)
+**When to use:** Custom host implementations that provide their own step registry and providers.
+
+---
+
+## Provider modules (optional)
+
+The core engine is provider-agnostic. Provider modules are **packaged with IdLE** but must be **imported separately** when needed.
+
+Example:
 
 ```powershell
-Get-Command -Module IdLE
-Get-Command -Module IdLE.Core
+# From source
+Import-Module ./src/IdLE.Provider.AD/IdLE.Provider.AD.psd1 -Force
 ```
+
+For a complete list of available providers and usage details, see **[Providers](../usage/providers.md)**.
+
+---
+
+## 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/overview/concept.md b/docs/overview/concept.md
index f5fe6e01..63d44528 100644
--- a/docs/overview/concept.md
+++ b/docs/overview/concept.md
@@ -7,6 +7,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 +24,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 +62,32 @@ Execution runs **only the plan** (no re-planning). This supports:
 - repeatability
 - deterministic audits
 
+---
+
+## 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:
@@ -55,3 +96,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
diff --git a/docs/reference/providers-and-contracts.md b/docs/reference/providers-and-contracts.md
index c6d4c0ef..bfef3f17 100644
--- a/docs/reference/providers-and-contracts.md
+++ b/docs/reference/providers-and-contracts.md
@@ -12,25 +12,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 +20,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 +64,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 +77,8 @@ The contract is expressed through:
 
 ---
 
+## Responsibilities
+
 ### Separation of responsibilities
 
 Clear separation is essential for maintainability:
@@ -115,6 +98,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 +110,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-IdleEntraIDIdentityProvider -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 +279,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 +337,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