docs(module): document configurator lifecycle and module system (#4738)

* docs(module): document configurator lifecycle and module system

closes equinor/fusion-core-tasks#1258
ref equinor/fusion-core-tasks#1256

* docs(module): add sidebar entry and README doc links for module system

* feat(module): document configurator plugins

* fix(docs): quote module lifecycle frontmatter

Author: odinr

.changeset/fusion-framework-docs_module-plugin-docs.md

@@ -0,0 +1,5 @@
+---
+"@equinor/fusion-framework-docs": patch
+---
+
+Document module configurator plugins, including `registerPlugin`, `createPlugin`, plugin teardown behavior, lifecycle ordering, and VuePress navigation updates.

.changeset/fusion-framework-module_docs-configurator-lifecycle.md

@@ -0,0 +1,20 @@
+---
+"@equinor/fusion-framework-module": patch
+"@equinor/fusion-framework-docs": patch
+---
+
+Document the `@equinor/fusion-framework-module` configurator and lifecycle.
+
+Adds structured `docs/` pages covering:
+
+- **concepts** — module system overview, roles, and mental model
+- **lifecycle** — configure → initialize → post-initialize → dispose phase sequence
+- **configuration** — how to register modules and use `addConfig` / `configure`
+- **cross-module deps** — `requireInstance` pattern for inter-module dependencies
+- **events** — `event$` observable and event naming conventions
+- **authoring modules** — step-by-step guide for creating a custom module
+- **common mistakes** — FAQ-style pitfalls and how to avoid them
+
+All pages are structured for retrieval (chunked sections, import paths, copy-pasteable examples) to improve Fusion Knowledge / Azure AI Search answer quality.
+
+Closes: equinor/fusion-core-tasks#1258

.changeset/fusion-framework-module_register-plugin.md

@@ -5,7 +5,7 @@
 
 Add `registerPlugin` to `IModulesConfigurator` and `ModulesConfigurator` for application-level side effects that run after modules are initialized and before application render.
 
-Plugins receive the initialized module map through `FrameworkPluginArgs` and may return a teardown callback that runs during `dispose`. Plugin-related types and the `createPlugin(name, callback)` helper are available from the dedicated `@equinor/fusion-framework-module/plugins` entrypoint. Plugin registration and teardown failures are isolated so one failing plugin does not block other plugins or module disposal.
+Plugins receive the initialized module map through `FrameworkPluginArgs` and may return a teardown callback that runs during `dispose`. Plugin-related types and the `createPlugin(name, callback)` helper are available from the dedicated `@equinor/fusion-framework-module/plugins` entrypoint. Plugin registration and teardown failures are isolated so one failing plugin does not block other plugins or module disposal. `ModuleConfiguratorEventName` and `ModuleConfiguratorEventBaseName` are available from the `@equinor/fusion-framework-module/configurator` entrypoint for filtering `ModuleConfigurator.{name}.{state}` lifecycle events without hard-coded strings.
 
 ```typescript
 import { createPlugin } from '@equinor/fusion-framework-module/plugins';

packages/modules/module/README.md

@@ -17,6 +17,7 @@ A `Module` is a plain object that declares a name, an optional configuration fac
 1. **Configure** – each module's `configure()` factory creates a config builder; registered callbacks mutate it; `postConfigure()` hooks run.
 2. **Initialize** – modules are initialized concurrently; cross-module dependencies are resolved through `requireInstance()`.
 3. **Post-initialize** – `postInitialize()` hooks and `onInitialized` callbacks run.
+4. **Plugins** – registered plugins connect host-level side effects after every module is ready.
 
 The result is a sealed `ModulesInstance` whose property names match the module keys and whose values are the initialized providers.
 
@@ -28,6 +29,19 @@ An abstract class for building module configuration declaratively. Subclasses ex
 
 Abstract base class for module providers (the runtime instances returned by `initialize()`). It manages a `Subscription` container for automatic teardown and exposes a `SemanticVersion` for compatibility checks.
 
+## Documentation
+
+| Topic | Description |
+|---|---|
+| [Concepts](./docs/concepts.md) | Module system overview, roles, and mental model |
+| [Lifecycle](./docs/lifecycle.md) | Configure → initialize → post-initialize → dispose phase sequence |
+| [Configuration](./docs/configuration.md) | How to register modules and use `addConfig` / `configure` |
+| [Cross-Module Dependencies](./docs/cross-module-deps.md) | `requireInstance` pattern for inter-module dependencies |
+| [Plugins](./docs/plugins.md) | `registerPlugin`, `createPlugin`, plugin teardown, and host-level side effects |
+| [Events](./docs/events.md) | `event$` observable and event naming conventions |
+| [Authoring Modules](./docs/authoring-modules.md) | Step-by-step guide for creating a custom module |
+| [Common Mistakes](./docs/common-mistakes.md) | FAQ-style pitfalls and how to avoid them |
+
 ## Installation
 
 ```sh
@@ -92,7 +106,7 @@ export const greeterModule: Module<'greeter', GreeterProvider, GreeterConfigurat
 | Export | Kind | Description |
 |---|---|---|
 | `Module` | type | Interface describing a module's structure and lifecycle hooks |
-| `ModulesConfigurator` | class | Orchestrates configure → initialize → dispose for a set of modules |
+| `ModulesConfigurator` | class | Orchestrates configure → initialize → plugin → dispose for a set of modules |
 | `IModulesConfigurator` | interface | Public contract for the modules configurator |
 | `IModuleConfigurator` | interface | Descriptor for registering a single module with lifecycle hooks |
 | `BaseConfigBuilder` | class | Abstract config builder with dot-path targeting and observable pipelines |
@@ -105,6 +119,25 @@ export const greeterModule: Module<'greeter', GreeterProvider, GreeterConfigurat
 | `IModuleConsoleLogger` | interface | Logger interface with `formatModuleName` |
 | `DotPath`, `DotPathType`, `DotPathUnion` | types | Recursive dot-notation path utilities |
 
+### Configurator Sub-path (`@equinor/fusion-framework-module/configurator`)
+
+| Export | Kind | Description |
+|---|---|---|
+| `ModuleConfiguratorEventBaseName` | const | Shared `ModuleConfigurator` base segment for configurator lifecycle event names |
+| `ModuleConfiguratorEventName` | object | Map of `ModuleConfigurator.{name}.{state}` event names for filtering `event$` without hard-coded strings |
+
+### Plugins Sub-path (`@equinor/fusion-framework-module/plugins`)
+
+| Export | Kind | Description |
+|---|---|---|
+| `createPlugin` | function | Creates a named plugin callback for stable lifecycle diagnostics |
+| `FrameworkPluginArgs` | type | Arguments passed to inline plugin callbacks: initialized modules and optional ref |
+| `FrameworkPluginCallback` | type | Callback accepted by `IModulesConfigurator.registerPlugin` |
+| `FrameworkPluginTeardown` | type | Cleanup callback or disposable object returned by a plugin |
+| `FrameworkPluginRegistration` | type | Plugin return type: teardown or `undefined` |
+| `FrameworkPlugin` | interface | Named plugin callback returned by `createPlugin` |
+| `FrameworkPluginInitializer` | type | Developer-facing callback signature used by `createPlugin` |
+
 ### Provider Sub-path (`@equinor/fusion-framework-module/provider`)
 
 | Export | Kind | Description |
@@ -127,6 +160,8 @@ export const greeterModule: Module<'greeter', GreeterProvider, GreeterConfigurat
 │ Init     │ module.initialize()      │                │
 │          │ module.postInitialize()  │ onInitialized()│
 ├──────────┼──────────────────────────┼────────────────┤
+│ Plugin   │                          │ registerPlugin │
+├──────────┼──────────────────────────┼────────────────┤
 │ Dispose  │ module.dispose()         │ instance.      │
 │          │                          │  dispose()     │
 └──────────┴──────────────────────────┴────────────────┘
@@ -161,6 +196,25 @@ postInitialize: async ({ instance, modules }) => {
 
 `configure` and `initialize` are the two required hooks. `postConfigure`, `postInitialize`, and `dispose` are optional.
 
+### Plugins and host-level side effects
+
+Use `registerPlugin` for application-owned wiring that needs the complete module instance before render. Plugins run after `postInitialize` and `onInitialized`, but before `initialize()` resolves. Return a teardown callback to clean up subscriptions, global listeners, timers, or telemetry bindings during dispose.
+
+```typescript
+import { createPlugin } from '@equinor/fusion-framework-module/plugins';
+
+const contextTelemetryPlugin = createPlugin<[typeof eventModule, typeof telemetryModule]>(
+  'contextTelemetry',
+  (modules) => modules.event.addEventListener('context:changed', (event) => {
+    modules.telemetry.track('context.changed', event.detail);
+  }),
+);
+
+configurator.registerPlugin(contextTelemetryPlugin);
+```
+
+See [Plugins](./docs/plugins.md) for teardown rules, failure behavior, and API reference.
+
 Events are emitted on `configurator.event$` throughout the lifecycle for telemetry and debugging.
 
 ## Related Packages