Rewrite docs and website for About and Use section

.github/copilot-instructions.md

@@ -9,8 +9,9 @@ Use these instructions when suggesting or generating changes in this repo (chat,
 - Agent operating manual: `AGENTS.md`
 - Coding and documentation rules: `STYLEGUIDE.md`
 - Contributor workflow + Definition of Done: `CONTRIBUTING.md`
-- Architecture: `docs/advanced/architecture.md`
-- Security + trust boundaries: `docs/advanced/security.md`
+- Concepts: `docs/about/concepts.md`
+- Security + trust boundaries: `docs/about/security.md`
+- Extensibility: `docs/extend/extensibility.md`
 
 If anything in this file conflicts with those, the more specific document wins.
 

AGENTS.md

@@ -25,7 +25,6 @@ Authoritative docs:
 
 - `README.md` (high-level)
 - `docs/index.md` (documentation entry point)
-- `docs/advanced/architecture.md` (architecture decisions)
 - `docs/advanced/security.md` (trust boundaries)
 - `docs/advanced/provider-capabilities.md` (Capability rules)
 - `docs/reference/providers-and-contracts.md` (Provider contracts)
@@ -161,8 +160,8 @@ Before proposing or finalizing a PR, ensure:
 - [ ] Public APIs have comment-based help
 - [ ] Docs updated where needed (`README.md`, `docs/`, `examples/`)
 - [ ] Generated docs regenerated if required (`docs/reference/*`)
-- [ ] No architecture rules violated (`docs/advanced/architecture.md`)
-- [ ] No security boundary regressions (`docs/advanced/security.md`)
+- [ ] No concept or extensibility rules violated (`docs/about/concepts.md`, `docs/extend/extensibility.md`)
+- [ ] No security boundary regressions (`docs/about/security.md`)
 
 ---
 
@@ -171,8 +170,9 @@ Before proposing or finalizing a PR, ensure:
 - General, cross-cutting agent rules → `AGENTS.md` (repo root)
 - Code style details → `STYLEGUIDE.md`
 - Contributor workflow and DoD → `CONTRIBUTING.md`
-- Architecture decisions → `docs/advanced/architecture.md`
-- Security boundaries → `docs/advanced/security.md`
+- Concept decisions → `docs/about/concepts.md`
+- Extensibility decisions → `docs/extend/extensibility.md`
+- Security boundaries → `docs/about/security.md`
 
 ---
 

CONTRIBUTING.md

@@ -125,7 +125,8 @@ A contribution is complete when:
 
 - all tests pass (`pwsh -NoProfile -File ./tools/Invoke-IdlePesterTests.ps1`)
 - static analysis passes (`pwsh -NoProfile -File ./tools/Invoke-IdleScriptAnalyzer.ps1`)
-- no architecture rules are violated (see `docs/advanced/architecture.md`)
+- no concept rules are violated (see `docs/about/concepts.md`)
+- no security or trust boundaries are violated (see `docs/about/security.md`)
 - public APIs are documented (comment-based help for exported functions)
 - documentation is updated where required:
   - README.md (only high-level overview + pointers)
@@ -300,12 +301,14 @@ Repository maintainers should configure branch protection so that required statu
 Keep docs short and linkable:
 
 - README.md: landing page (what/why + 30s quickstart + links)
-- docs/: architecture, usage, examples (small focused pages)
+- docs/: concepts, usage, examples (small focused pages)
 - examples/: runnable scripts and workflow samples
 
 Key links:
 
-- Architecture: `docs/about/architecture.md`
+- Concepts: `docs/about/concepts.md`
+- Security: `docs/about/security.md`
+- Extensibility: `docs/extend/extensibility.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 **[About > Concepts](docs/about/concepts.md)**.
+For a complete overview of concepts, see **[About > Concepts](docs/about/concepts.md)**.
 
 ---