Updated Docs at Website

README.md

@@ -90,8 +90,8 @@ Start here:
 
 - [docs/index.md](docs/index.md) – Documentation map
 - [docs/about/intro.md](docs/about/intro.md) – About IdLE
-- [docs/use/intro.md](docs/use/intro.md) – How to use IdLE
-- [docs/reference/intro.md](docs/reference/intro.md) - The authoritative IdLE reference
+- [docs/use/intro-use.md](docs/use/intro-use.md) – How to use IdLE
+- [docs/reference/intro-reference.md](docs/reference/intro-reference.md) - The authoritative IdLE reference
 
 ---
 

docs/extend/intro.md → docs/extend/intro-extend.md

@@ -22,13 +22,6 @@ It is written for people who want to add or customize functionality, for example
 - Authentication and session handling
 - Testing approaches (unit tests, contract tests)
 
-## Where to continue?
-
-1. [Extensibility](extensibility.md)
-2. [Providers](providers.md)
-3. [Steps](steps.md)
-4. [Events](events.md)
-
 ## Not the right section?
 
-If you want to run workflows as an operator/admin, go to [Use Idle](../use/intro.md) instead.
+If you want to run workflows as an operator/admin, go to [Use Idle](../use/intro-use.md) instead.

docs/index.md

@@ -20,7 +20,7 @@ Learn the basics [about IdLE](about/intro.md)
 
 ## Use IdLE
 
-Learn how to [use IdLE](use/intro.md) as an operator or admin, e.g. for workflow authoring.
+Learn how to [use IdLE](use/intro-use.md) as an operator or admin, e.g. for workflow authoring.
 
 - [Quickstart](use/quickstart.md) - Run the demo and understand Plan → Execute flow
 - [Installation](use/installation.md) - Install and import guide (requirements, import options)
@@ -30,28 +30,20 @@ Learn how to [use IdLE](use/intro.md) as an operator or admin, e.g. for workflow
 
 ## Extend IdLE
 
-Learn how to [extend IdLE](extend/intro.md) as a developer.
+Learn how to [extend IdLE](extend/intro-extend.md) as a developer.
 
 - [Extensibility](extend/extensibility.md) - General extensibility concept of IdLE
 - [Events](extend/events.md) - Eventing at IdLE to be used in your extensions
 - [Providers](extend/providers.md) - How to build your own custom providers
 
 ## Reference
 
-The [authoritative reference](reference/intro.md) for IdLE components.
+The [authoritative reference](reference/intro-reference.md) for IdLE components.
 
-- [Cmdlets](reference/cmdlets.md) - Public cmdlets and usage
-- [Step Catalog](reference/steps.md) - Built-in step reference (generated)
-- [Capabilities](reference/capabilities.md) - The capabilities catalog
-
-## Workflow Examples
-
-- [Workflow Examples](../examples/README.md) - Runnable examples and demo workflows
-
-### Provider Reference
-
-- [Active Directory Provider](reference/providers/provider-ad.md)
-- [Entra ID Provider](reference/providers/provider-entraID.md)
+- [Cmdlet Reference](reference/cmdlets.md)
+- [Provider Reference](reference/providers.md)
+- [Step Reference](reference/steps.md)
+- [Capabilities](reference/capabilities.md)
 
 ### Specifications
 
@@ -60,6 +52,10 @@ used between IdLE and its hosts.
 
 - [Plan export (JSON)](reference/specs/plan-export.md) - The JSON specification of the Plan export file
 
+### Workflow Examples
+
+- [Workflow Examples](../examples/README.md) - Runnable examples and demo workflows
+
 ---
 
 ## Developer Documentation

docs/reference/cmdlets.md

@@ -1,4 +1,4 @@
-# Cmdlet Reference
+# Cmdlets
 
 > Generated file. Do not edit by hand.
 > Source: tools/Generate-IdleCmdletReference.ps1

docs/reference/intro.md → docs/reference/intro-reference.md

@@ -6,22 +6,20 @@ sidebar_label: Reference
 This section is the **authoritative reference** for IdLE.
 
 It contains precise, stable and normative information intended for lookup and verification.
-Content here is not tutorial-style and usually assumes prior knowledge from the **Use** or
-**Extend** sections.
-
-## What you will find here
-
-- Cmdlet reference
-- Step reference
-- Capability reference
-- Specifications (schemas, formats, contracts)
+Content here is not tutorial-style and usually assumes prior knowledge from the **[Use](../use/intro-use.md)** or
+**[Extend](../extend/intro-extend.md)** sections.
 
 ## How to use this section
 
 - Look up exact behavior, parameters or contracts
 - Verify assumptions during development or review
 - Link from guides and concepts to authoritative definitions
 
-## Not the right section?
+## What you will find here
 
-If you are looking for guidance or explanations, start with [Use](../use/intro.md) or [Extend](../extend/intro.md) instead.
+- [Cmdlet reference](./cmdlets.md)
+- [Step reference](./steps.md)
+- [Providers](./providers.md)
+- [Capability reference](capabilities.md)
+- Specifications (schemas, formats, contracts)
+  - [Plan Export JSON Schema](./specs/plan-export.md)

docs/reference/providers.md

@@ -0,0 +1,41 @@
+---
+title: Providers Reference
+sidebar_label: Providers
+---
+
+> Entry page for provider reference. This section is **reference-only**: what a provider implements, how to configure it, and which contracts/capabilities it exposes.
+
+---
+
+## Built-in / first-party providers
+
+- **[Active Directory (AD)](providers/provider-ad.md)** — Identity operations against on-prem AD via the AD provider module
+- **[Entra ID](providers/provider-entraID.md)** — Identity operations against Microsoft Entra ID via Microsoft Graph
+- **[Exchange Online](providers/provider-exchangeonline.md)** — Messaging / mailbox related operations against Exchange Online
+- **[DirectorySync.EntraConnect](providers/provider-directorysync-entraconnect.md)** — Directory synchronization provider for Entra Connect / sync-cycle related operations
+- **[Mock Provider](providers/provider-mock.md)** — In-memory / file-backed provider for tests and local development without live systems
+
+---
+
+## Choosing a provider
+
+- Match the **capabilities required by your steps** to the provider’s `GetCapabilities()` output.
+- Steps acquire auth sessions via `Context.AcquireAuthSession(...)` and pass them to provider methods that accept an optional `AuthSession` parameter (host-controlled).
+- In workflows, steps select a provider by **alias** (defaults to `Identity` if omitted).
+
+Related:
+
+- [Capabilities Reference](capabilities.md)
+- [Provider fundamentals (concept)](../about/concepts.md#providers)
+- [Use Providers](../use/providers.md)
+
+---
+
+## Authoring a provider (for developers)
+
+Minimal checklist:
+
+- Implement provider contracts (only what you need)
+- Advertise deterministic capabilities (`GetCapabilities()`)
+- Accept optional `AuthSession` parameter in methods that require authentication (sessions acquired by steps via host context; no prompts inside providers)
+- Add unit tests + contract tests (no live calls in CI)