Manual website content review

docs/about/concepts.md

@@ -3,16 +3,21 @@ title: IdLE Concepts
 sidebar_label: Concepts
 ---
 
-IdLE is a generic, headless, configuration-driven engine for identity lifecycle automation (Joiner / Mover / Leaver). It intentionally separates intent from implementation: workflows (data-only PSD1 files) declare what should happen, steps implement provider-agnostic, idempotent convergence logic, and providers adapt to external systems and manage authentication.
+IdLE is a **generic, headless, configuration-driven engine for identity lifecycle automation** (Joiner / Mover / Leaver). It intentionally **separates intent from implementation**:
 
-The engine first builds a deterministic, auditable execution plan from a LifecycleRequest and a workflow (Plan → Execute). Planning validates conditions, inputs, and required provider capabilities; execution runs only the produced plan to ensure repeatability, safe approvals, and reliable auditing. This design prioritizes portability, testability (mockable providers), and minimal runtime assumptions by keeping the core headless and side-effect free.
+- **Workflows** (data-only PSD1 files) declare what should happen,
+- **Steps** implement provider-agnostic, idempotent convergence logic, and
+- **Providers** adapt to external systems and manage authentication.
+
+The engine first builds a **deterministic, auditable execution plan** from a LifecycleRequest and a workflow (Plan → Execute). **Planning validates** conditions, inputs, and required provider capabilities; **Execution runs** only the produced plan to ensure repeatability, safe approvals, and reliable auditing.
+This design **prioritizes portability, testability (mockable providers), and minimal runtime assumptions** by keeping the core headless and side-effect free.
 
 This page explains the **big picture**: responsibilities, trust boundaries, and how the core artifacts fit together.
 
 ## Start here
 
 - If you want to **run IdLE now**: start with [Quick Start](../use/quickstart.md).
-- If you want the full end-to-end flow: follow the **Walkthrough**:
+- If you want the **full end-to-end flow**: follow the **Walkthrough**:
   1. [Workflow definition](../use/walkthrough/01-workflow-definition.md)
   2. [Request creation](../use/walkthrough/02-request-creation.md)
   3. [Plan build](../use/walkthrough/03-plan-creation.md)
@@ -21,12 +26,12 @@ This page explains the **big picture**: responsibilities, trust boundaries, and
 
 ## Goals
 
-- Generic, configurable lifecycle orchestration (Joiner / Mover / Leaver)
-- Portable, modular, testable
-- Headless core (works in CLI, service, CI)
-- Plan-first execution with structured events
+- **Generic, configurable lifecycle orchestration** (Joiner / Mover / Leaver)
+- **Portable, modular, testable**
+- **Headless core** (works in CLI, service, CI)
+- **Plan-first execution** with structured events
 
-## Non-goals
+### Non-goals
 
 - No UI framework or service host
 - No interactive prompts
@@ -41,7 +46,7 @@ This page explains the **big picture**: responsibilities, trust boundaries, and
 
 ### Separation of Responsibility
 
-Clear separation of responsibility is the essential foundation for maintainability:
+**Clear separation of responsibility** is the essential foundation for maintainability:
 
 - **Engine**
   - Orchestrates workflow execution
@@ -67,7 +72,7 @@ If you want the practical version of this (how to supply providers/auth in a run
 
 ## Request
 
-A **request** represents your business intent (Joiner/Mover/Leaver) plus the input data required to build a plan.
+A **request represents your business intent** (Joiner/Mover/Leaver) plus the input data required to build a plan.
 
 Typical request content:
 
@@ -81,61 +86,54 @@ Hands-on: [Walkthrough 2: Request creation](../use/walkthrough/02-request-creati
 
 ## Workflow
 
-A **workflow** is a data-only definition (`.psd1`) that describes **what** should happen, step by step.
+A **workflow is a data-only definition** (`.psd1`) that describes **what** should happen, step by step.
 
-### Workflows and Steps
+### Workflow Steps
 
-A workflow consists of ordered steps. Each step references a **StepType** by name and provides configuration under `With`.
+A **workflow consists of ordered steps**. Each step references a **StepType** by name and provides configuration under `With`.
 
-Hands-on: [Walkthrough 1: Workflow definition](../use/walkthrough/01-workflow-definition.md).
-Specification: [Use → Workflows](../use/workflows.md) and the [Reference section](../reference/steps.md).
+- Hands-on: [Walkthrough 1: Workflow definition](../use/walkthrough/01-workflow-definition.md).
+- Specification: [Use → Workflows](../use/workflows.md) and [Reference section](../reference/steps.md).
 
 ### Providers
 
-Workflows may reference providers by alias (for example: `With.Provider = 'Identity'`), but the actual provider instances are supplied by the host.
+**Workflows reference providers** by alias (for example: `With.Provider = 'Identity'`), but the actual provider instances are supplied by the host. Providers implement step capabilities specifically for each endpoint system.
 
 Hands-on: [Walkthrough 5: Providers and authentication](../use/walkthrough/05-providers-authentication.md).
 
 ### Declarative conditions
 
-Workflows can include declarative conditions (data-only) to decide whether steps should run.
+**Workflows can include declarative conditions** (data-only) to decide whether steps should run.
 For details, use the Reference workflow documentation.
 
 ---
 
 ## Plan
 
-A **plan** is the validated, resolved execution contract produced from a workflow and a request.
+A **plan is the validated, resolved execution contract** produced from a workflow and a request.
 
 Hands-on: [Walkthrough 3: Plan build](../use/walkthrough/03-plan-creation.md).
 
 ### Provider Capabilities (Planning-time Validation)
 
-IdLE can validate required capabilities at plan-build time (fail-fast), if providers are supplied.
+**IdLE validates required capabilities** at plan-build time (fail-fast) against supplied providers.
 This prevents discovering missing requirements only at execution time.
 
 ### Plan export
 
-Plans can be exported for review, approval, CI artifacts, and audit trails.
+**Plans can be exported** as a JSON file for review, approval, CI artifacts, and audit trails.
 
 Hands-on: [Use → Plan Export](../use/plan-export.md).
 
 ---
 
 ## Execute
 
-Executing a plan runs the steps in order and produces a structured result.
+Executing a plan **runs the steps in order as planned** and produces a structured result.
 
 Hands-on: [Walkthrough 4: Invoke and results](../use/walkthrough/04-invoke-results.md).
 
 ### Eventing
 
-IdLE emits structured events during execution.
+**IdLE emits structured events** during execution.
 Your host can log them, forward them, or store them for audit and diagnostics.
-
----
-
-## Next
-
-- Run the minimal end-to-end example: [Quick Start](../use/quickstart.md)
-- Continue with deep details: [Reference](../reference/intro-reference.md)

docs/about/intro.md

@@ -9,34 +9,35 @@ sidebar_label: Introduction
 
 ## Introduction
 
-IdLE (Identity Lifecycle Engine) is a **generic, configurable orchestration framework** for identity lifecycle processes
+IdLE (Identity Lifecycle Engine) is a **generic, configurable orchestration framework for identity lifecycle processes**
 (Joiner / Mover / Leaver and similar cases), built for **PowerShell 7+**.
 
 ---
 
 ## Why IdLE exists
 
-JML (joiner/mover/leavers) processes are
+**JML (joiner/mover/leavers) processes** are
 
-- error prone, especially if performed manually
-- time consuming and therefore
-- quite annoying for operators
+- **error prone**, especially if performed manually
+- **time consuming** and therefore
+- quite **annoying for operators**
 
-Self-made identity lifecycle automation often turns into long scripts that are:
+**Self-made identity lifecycle automation** often turns into long scripts that are:
 
-- tightly coupled to one environment
-- hard to test
-- hard to change safely
+- **tightly coupled to one environment**
+- **hard to test**
+- **hard to change** safely
+- **hard to maintain**
 
-Identity Management Systems (IdMS) on the other side are either complex or expensive (or both of it) and then often do not care about supplementary systems that also need to be covered within the workflows.
+**Identity Management Systems (IdMS)** on the other side are **either complex or expensive** (or both of it) and then often do not care about supplementary systems that also need to be covered within the workflows.
 
 ---
 
 ## Start using IdLE
 
-- If you want to run IdLE now: start with [Quick Start](../use/quickstart).
-- If you want a guided path: follow the [Walkthrough](../use/walkthrough/01-workflow-definition).
-- If you want the architecture and responsibility model: read [Concepts](./concepts).
+- If you want to **run IdLE now**: start with [Quick Start](../use/quickstart).
+- If you want a **guided path**: follow the [Walkthrough](../use/walkthrough/01-workflow-definition).
+- If you want the **architecture and responsibility model**: read [Concepts](./concepts).
 
 ---
 
@@ -68,4 +69,6 @@ Workflows and requests remain data-only.
   - [Installation](../use/installation.md)
   - [QuickStart](../use/quickstart.md)
   - [Walkthrough - Step 1: Workflow Definition](../use/walkthrough/01-workflow-definition.md)
-- [Reference](../reference/intro-reference.md)
+- More details on
+  - [Concepts](./concepts)
+  - [Security](./security.md)

docs/about/security.md

@@ -3,7 +3,7 @@ title: Security and Trust Boundaries
 sidebar_label: Security
 ---
 
-IdLE is designed to execute **data-driven** identity lifecycle workflows in a deterministic way.
+IdLE is designed to **execute data-driven identity lifecycle workflows** in a deterministic way.
 
 Because IdLE is an orchestration engine, it must be explicit about **what is trusted** and **what is untrusted**.
 
@@ -13,53 +13,58 @@ IdLE enforces a strict trust boundary between **untrusted data inputs** and **tr
 
 ### Untrusted inputs (data-only)
 
-These inputs may come from users, CI pipelines, or external systems and **must be treated as untrusted**:
+These inputs may come **from users, CI pipelines, or external systems** and **must be treated as untrusted**:
 
 - Workflow definitions (PSD1)
 - Lifecycle requests (input objects)
 - Step parameters (`With`, `When`)
 - Provider configuration maps (e.g., `Providers` passed into plan execution)
 - Event payloads (`Event.Data`) emitted by steps/providers
 
-**Rule:** Untrusted inputs must be *data-only*. They must not contain ScriptBlocks or other executable objects.
+:::info
+**Rule:** Untrusted inputs **must be *data-only***. They must not contain ScriptBlocks or other executable objects.
+:::
 
-IdLE enforces this by:
+**IdLE enforces** this by:
 
-- Rejecting ScriptBlocks when importing workflow definitions
-- Validating inputs at runtime using the public `Assert-IdleNoScriptBlock` function (provided by `IdLE.Core`)
-- Recursively scanning all hashtables, arrays, and PSCustomObjects for ScriptBlocks
+- **Rejecting ScriptBlocks** when importing workflow definitions
+- **Validating inputs** at runtime
+- **Recursively scanning** all hashtables, arrays, and PSCustomObjects for ScriptBlocks
 
 **Implementation:**
 
-- The `Assert-IdleNoScriptBlock` function is the single, authoritative validator for this boundary
+The public `Assert-IdleNoScriptBlock` function is the single, authoritative validator for this boundary
+
 - It performs deep recursive validation with no type exemptions
 - All workflow configuration, lifecycle requests, step parameters, and provider maps are validated
 - Validation failures include the exact path to the offending ScriptBlock for debugging
 
 ### Trusted extension points (code)
 
-These inputs are provided by the host and are **privileged** because they determine what code is executed:
+These inputs are **provided by the host** and are **privileged** because they determine what code is executed:
 
-- Step registry (maps `Step.Type` to a handler function name)
-- Provider modules / provider objects (system-specific adapters)
-- External event sinks (streaming events)
+- **Step registry** (maps `Step.Type` to a handler function name)
+- **Provider modules** / provider objects (system-specific adapters)
+- **External event sinks** (streaming events)
 - **AuthSessionBroker** (host-provided authentication orchestration)
 
+:::info
 **Rule:** Only trusted code should populate these extension points.
+:::
 
 These extension points may contain ScriptMethods (e.g., the `AcquireAuthSession` method on AuthSessionBroker objects) but should not contain ScriptBlock *properties* that could be confused with data.
 
 #### AuthSessionBroker Trust Model
 
 - The broker is a **trusted extension point** provided by the host
-- It orchestrates authentication without embedding secrets in workflows
+- It **orchestrates authentication** without embedding secrets in workflows
 - Broker objects may contain ScriptMethods (e.g., `AcquireAuthSession`) as part of their interface
 - Broker objects must **not** contain ScriptBlock properties; all logic should be in methods or direct function calls
-- Authentication options passed to `AcquireAuthSession` are validated as data-only (no ScriptBlocks)
+- **Authentication options** passed to `AcquireAuthSession` are validated as **data-only** (no ScriptBlocks)
 
 ## Secure defaults
 
-IdLE applies secure defaults to reduce accidental code execution:
+IdLE applies **secure defaults** to reduce accidental code execution:
 
 - Workflow configuration is loaded as data and ScriptBlocks are rejected.
 - Step registry handlers must be function names (strings); ScriptBlock handlers are rejected.
@@ -91,7 +96,7 @@ Redaction happens for:
 
 ### Where redaction is applied
 
-Redaction is intentionally centralized at output boundaries to keep the execution model unchanged and to avoid altering step/provider behavior while making outputs safe-by-default.
+**Redaction is intentionally centralized** at output boundaries to keep the execution model unchanged and to avoid altering step/provider behavior while making outputs safe-by-default.
 
 Redaction is applied **before** data is:
 
@@ -107,7 +112,7 @@ Redaction is applied **before** data is:
 
 ## Guidance for hosts
 
-- Keep workflow files in a protected location and review them like code (even though they are data-only).
-- Load step and provider modules explicitly before execution.
-- Treat the step registry as privileged configuration and do not let workflow authors change it.
+- **Keep workflow files in a protected location** and review them like code (even though they are data-only).
+- **Load step and provider modules explicitly** before execution.
+- Treat the **step registry as privileged configuration** and do not let workflow authors change it.
 - If you stream events, implement a small sink object with a `WriteEvent(event)` method and keep it side-effect free.

docs/reference/specs/plan-export.md

@@ -166,7 +166,7 @@ This bound prevents unbounded snapshot artifacts while keeping the marker audita
 ```json
 "plan": {
   "id": "plan-001",
-  "mode": "PlanOnly",
+  "mode": null,
   "steps": []
 }
 ```
@@ -177,7 +177,7 @@ This bound prevents unbounded snapshot artifacts while keeping the marker audita
 | ------ | ------------ |
 | id | Unique identifier of the plan |
 | createdAt | (Optional) ISO-8601 UTC timestamp |
-| mode | Plan lifecycle state |
+| mode | Plan lifecycle state (`null` when not explicitly set on the plan object) |
 | steps | Ordered list of step objects |
 
 ---

docs/use/installation.md

@@ -35,13 +35,15 @@ Get-InstalledModule IdLE, IdLE.Core, IdLE.Steps.Common -ErrorAction SilentlyCont
 Install-Module -Name IdLE -Scope CurrentUser -Force
 Import-Module -Name IdLE
 ```
+
 :::
 
 ---
 
 ## Install optional modules
 
 Providers and additional step modules are published as separate modules and can be installed independently.
+See the [reference](../reference/intro-reference.md) for further details on [Steps](../reference/steps.md) and [Providers](../reference/providers.md).
 
 ```powershell
 # Provider modules (examples)
@@ -56,32 +58,33 @@ Install-Module -Name IdLE.Steps.Mailbox -Scope CurrentUser
 Install-Module -Name IdLE.Provider.Mock -Scope CurrentUser
 ```
 
-Import only what you need:
-
-```powershell
-Import-Module -Name IdLE.Provider.Mock
-Import-Module -Name IdLE.Provider.AD
-```
 
 :::tip
 If a workflow references a StepType from an optional steps module, that steps module must be installed and imported in the host session.
 :::
 
 ---
 
-## Install from repository source (contributors)
+## Install from repository source
+
+:::info
+This installation method is primarily for fetching full example files, testing, and contributing.
+:::
 
 This path is intended for development and contribution scenarios.
 
 ```powershell
 git clone https://github.com/blindzero/IdentityLifecycleEngine
 cd IdentityLifecycleEngine
 
-# Import meta module (bootstraps module discovery for repo layout)
+# Import meta module
 Import-Module ./src/IdLE/IdLE.psd1 -Force
 ```
 
-After importing from source, you can import additional modules by name:
+:::info
+The meta module bootstraps module discovery for the repository layout. Avoid using this in parallel with an IdLE installation from the PowerShell Gallery.
+After importing from source, you can import additional modules by name.
+:::
 
 ```powershell
 Import-Module IdLE.Provider.Mock -Force
@@ -93,8 +96,11 @@ Import-Module IdLE.Steps.Mailbox -Force
 ## Verify installation
 
 ```powershell
-Get-Module IdLE -ListAvailable | Select-Object Name, Version, Path
+Get-Module IdLE* -ListAvailable | Select-Object Name, Version, Path
+# Public-facing user commands
 Get-Command -Module IdLE | Sort-Object Name
+# Public interface functions from modules
+Get-Command -Module IdLE.* | Sort-Object Name
 ```
 
 ---

docs/use/intro-use.md

@@ -42,5 +42,5 @@ Reference pages are the single source of truth for schemas and cmdlet details.
 ## When to use other sections
 
 - If you want the **big picture** (responsibilities, trust boundaries, architecture): see [Concepts](../about/concepts.md)
-- If you want to **extend IdLE** (write steps, providers, host integrations): see [Extend](../extend/intro-extend.md)
 - If you need **specification-level details**: see [Reference](../reference/intro-reference.md)
+- If you want to **extend IdLE** (write steps, providers, host integrations): see [Extend](../extend/intro-extend.md)