Non-blocking batteries included baseline for packaging

[blindzero]

Problem Statement

We want to publish a single IdLE package to PowerShell Gallery, while ensuring:

• Install-Module IdLE + Import-Module IdLE is always non-blocking
• system-/tool-dependent providers can still be shipped, but must not break the baseline experience
• the staged package layout behaves the same as the repository src/ layout (“source vs packaged parity”)

Current state shows inconsistencies between:

• what IdLE auto-loads via NestedModules (integration modules), and
• what the packaging script stages (Core + Steps only), and
• what docs communicate about the “baseline” and shipped modules.

Proposed Solution (Decisions)

A) Publishing model

• We will publish only one PowerShell Gallery module/package: IdLE.
• The IdLE package may contain additional shipped modules (steps/providers) that are not automatically imported.

B) Import / module-loading policy (baseline vs optional)

Baseline (auto-imported by IdLE)

• IdLE (meta)
• IdLE.Core
• IdLE.Steps.Common

Optional (shipped, but not auto-imported)

• Provider modules and any other modules that may be system-/tool-dependent (e.g. RSAT, PSRemoting configuration, OS-specific features).
• Dev/Test/Example helper modules (not required for baseline runtime).

Hard rule

• Import-Module IdLE must remain non-blocking. Optional modules must never be required to import the baseline.

C) Provider dependency policy (no implicit third-party loading)

• Provider modules must not auto-install or auto-load third-party dependencies at import time.
• No #Requires -Modules <ThirdParty> and no top-level Import-Module <ThirdParty> that can block.
• Providers must validate prerequisites at execution time and fail fast with actionable remediation hints.

D) Mock provider policy

• IdLE.Provider.Mock should be shipped (supports examples and developer workflows),
  but not auto-imported by IdLE.
• Examples (and dev tooling) are responsible for importing it explicitly when needed.

Scope adjustment (split)

The documentation needs a clear, single-source definition of the above rules, with deduplication and structure review.
To avoid growing #97 beyond its packaging/loader scope:

• Non-blocking batteries included baseline for packaging #97 will focus on packaging + nested module staging + loader behavior to implement the decisions above.
• Documentation consolidation and “single-source of truth” work will be tracked in a new dedicated docs issue (to be created).
• Non-blocking batteries included baseline for packaging #97 will reference the docs issue as a dependency for final wording, but can still implement the technical behavior.

Impact

• Breaking change risk: Low-to-medium. Auto-import behavior changes for shipped modules.
• User experience: Improved stability. Baseline import always succeeds; missing prerequisites surface at execution time with clear remediation.
• Developer experience: Clear contract for provider authors (no import-time hard dependencies; prerequisite checks at execution).

Acceptance Criteria

1. Import-Module IdLE succeeds on a clean PowerShell 7 environment without RSAT/AD tools and without optional provider prerequisites.

• Importing IdLE only auto-imports succeeding IdLE.Core and IdLE.Steps.Common
• No further submodules are imported automatically

3. The staged PSGallery artifact contains the baseline modules and ships optional modules without importing them automatically.
4. Source layout and packaged layout behave consistently for module resolution.
5. Provider modules do not block on import due to third-party dependencies (validated by tests / lint rules where feasible).
6. Clear error messages for missing prerequisites occur at execution time, not import time.
7. All docs and examples are updated accordingly and describe consistently the desired behavior
8. Tests are updated / there is a test to ensure the wanted auto-import behavior

Definition of Done

• All acceptance criteria met
• Pester green
• PSScriptAnalyzer green
• Git status clean
• Docs updated where needed
• Examples updated where needed