Consolidate documentation into single sources of truth with audience split

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)**.
 
 ---
 

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)

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

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