move from simple GH Pages to DocuSaurus

.github/workflows/ci.yml

@@ -2,8 +2,12 @@ name: CI
 
 on:
   pull_request:
+    paths-ignore:
+      - 'website/**'
   push:
     branches: [ main ]
+    paths-ignore:
+      - 'website/**'
 
 concurrency:
   group: ci-${{ github.ref }}

.github/workflows/pages.yml

@@ -0,0 +1,97 @@
+name: Website (Docs) - Build & Deploy
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "website/**"
+      - "tools/**"
+      - ".github/workflows/pages.yml"
+  push:
+    branches: [ "main" ]
+    paths:
+      - "docs/**"
+      - "website/**"
+      - "tools/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs-consistency:
+    name: Docs consistency audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Run docs consistency audit
+        shell: pwsh
+        run: >
+          pwsh -NoProfile -File ./tools/Test-DocsConsistency.ps1
+          -DocsPath ./docs
+          -WebsitePath ./website
+          -FailOnOrphans:$false
+
+      - name: Upload docs audit artifact
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: docs-audit
+          if-no-files-found: warn
+          path: |
+            artifacts/docs-audit.json
+
+  build:
+    name: Build Docusaurus site
+    runs-on: ubuntu-latest
+    needs: [ docs-consistency ]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: "website/package-lock.json"
+
+      - name: Install dependencies
+        working-directory: website
+        run: npm ci
+
+      - name: Sync docs assets
+        working-directory: website
+        run: npm run sync-assets
+
+      - name: Build site
+        working-directory: website
+        run: npm run build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: website/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    needs: [ build ]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -46,6 +46,7 @@ coverage.*
 test-results.*
 *.lcov
 testresults.xml
+docs-audit.json
 
 # Packages
 *.7z

CONTRIBUTING.md

@@ -305,9 +305,8 @@ Keep docs short and linkable:
 
 Key links:
 
-- Docs map: `docs/00-index.md`
-- Architecture: `docs/advanced/architecture.md`
-- Examples: `docs/02-examples.md`
+- Architecture: `docs/about/architecture.md`
+- Examples: `examples/README.md`
 - Coding & in-code documentation rules: `STYLEGUIDE.md`
 
 ---

README.md

@@ -35,7 +35,7 @@ IdLE aims to be:
 - **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)**.
+For a complete overview of concepts and architecture, see **[About > Concepts](docs/about/concepts.md)**.
 
 ---
 
@@ -57,7 +57,7 @@ Install-Module -Name IdLE -Scope CurrentUser
 Import-Module IdLE
 ```
 
-For detailed installation instructions, requirements, and import options, see **[Installation Guide](docs/getting-started/installation.md)**.
+For detailed installation instructions, requirements, and import options, see **[Installation Guide](docs/use/installation.md)**.
 
 ---
 
@@ -80,23 +80,18 @@ By default, the demo runs **Mock workflows** that work out-of-the-box without ex
 The execution result buffers all emitted events in `result.Events`. Hosts can optionally stream events live
 by providing `-EventSink` as an object implementing `WriteEvent(event)`.
 
-Next steps:
-
-- Documentation entry point: `docs/index.md`
-- Workflow samples: `examples/workflows/` (organized by category: mock, live, templates)
-- Repository demo: `examples/Invoke-IdleDemo.ps1`
-- Pester tests: `tests/`
-
 ---
 
 ## Documentation
 
+The documentation is also available at our project site: [https://blindzero.github.io/IdentityLifecycleEngine](https://blindzero.github.io/IdentityLifecycleEngine)
+
 Start here:
 
-- `docs/index.md` – documentation map
-- `docs/getting-started/quickstart.md` – plan → execute walkthrough
-- `docs/advanced/architecture.md` – architecture and principles
-- `docs/usage/workflows.md` – workflow schema and validation
+- [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/advanced/architecture.md → docs/about/architecture.md

@@ -1,3 +1,8 @@
+---
+title: Architecture
+sidebar_labels: Architecture
+---
+
 # Architecture
 
 This page summarizes the core architecture decisions for IdLE.
@@ -41,7 +46,7 @@ advertise which capabilities they support. The engine matches both sides
 and fails fast if required functionality is missing.
 
 For details on the capability-based provider model and the validation flow,
-see [Provider Capabilities](provider-capabilities.md).
+see [Provider Capabilities](../reference/capabilities.md).
 
 ### Execute
 
@@ -57,7 +62,7 @@ This enables previews, approvals, and repeatable audits.
 Hosts may persist or exchange a plan as a **machine-readable JSON artifact**.
 The canonical contract format is defined here:
 
-- [Plan export specification (JSON)](../specs/plan-export.md)
+- [Plan export specification (JSON)](../reference/specs/plan-export.md)
 
 The exported artifact is intended for **approvals, CI checks, and audits**.
 To keep exports deterministic and review-friendly, the contract intentionally omits volatile information
@@ -82,7 +87,7 @@ IdLE emits **structured events** during execution.
 
 Hosts may optionally provide an external sink to stream events live:
 
-- `Invoke-IdlePlan -EventSink <object>`
+- `Invoke-IdlePlan -EventSink &lt;object&gt;`
 - The sink must implement `WriteEvent(event)`
 - ScriptBlock sinks are rejected (secure default)
 
@@ -97,7 +102,7 @@ No deep merge: replace-at-path semantics only.
 - Steps implement behaviors
 - Providers integrate target systems
 
-See: [Extensibility](extensibility.md).
+See: [Extensibility](../extend/extensibility.md).
 
 ## Trust boundaries
 
@@ -152,7 +157,7 @@ The following are **not contracts** and may change in minor/patch versions:
 **Plan export contract** (JSON):
 - Format: JSON from `Export-IdlePlan`
 - Schema and semantics are stable
-- See [Plan export specification](../specs/plan-export.md)
+- See [Plan export specification](../reference/specs/plan-export.md)
 
 ### Capability ID Baseline (v1.0)
 

docs/about/concepts.md

@@ -0,0 +1,73 @@
+---
+title: Concepts
+sidebar_label: Concepts
+---
+
+# IdLE Concepts
+
+## Request
+
+A **LifecycleRequest** represents the business intent (for example: Joiner, Mover, Leaver).
+It is the input to planning.
+
+## Plan
+
+A **LifecyclePlan** is created deterministically from:
+
+- request
+- workflow definition
+- step catalog / step registry
+
+The plan is previewable and auditable.
+
+## Execute
+
+Execution runs **only the plan** (no re-planning). This supports:
+
+- approvals
+- 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](../use/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](../use/providers.md) | [Providers and Contracts](../extend/providers.md)
+
+---
+
+## Non-goals (V1)
+
+IdLE.Core stays headless and avoids responsibilities that belong to a host application:
+
+- no UI framework
+- no interactive prompts
+- no authentication flows inside steps
+- no dynamic code execution from configuration
+
+---
+
+## Next Steps
+
+- [Installation](../use/installation.md) — Install and import guide
+- [Quickstart](../use/quickstart.md) — Run the demo
+- [Architecture](../about/architecture.md) — Design principles and decisions
+- [Workflows](../use/workflows.md) — Define lifecycle workflows