docs(module): migrate authoring examples to LibModule

Author: ImperaZim

CHANGELOG.md

@@ -93,6 +93,11 @@
   `ModuleCommandRunner`, `ModulesCommand` and `NativeModulesCommand` now live
   in `LibModule`, making `/easymodule`, `/emodule` and `/modules` a
   LibModule-owned surface instead of an EasyLibrary core-owned command.
+- Added the OP-68H authoring example migration. The `examples/` tree now
+  documents the `LibModule` public API directly: modules use `ModuleContext`,
+  commands extend `BaseModuleCommand`, services/capabilities are provided
+  through `ModuleRuntime`, and EasyLibrary's legacy `ModuleManager` is no
+  longer imported by the examples.
 - Validated OP-60 live loading against the local PMMP smoke server. LibModule
   loaded as `source=package-backed-virtual` from
   `plugin_data/EasyLibrary/packages/libmodule/1.0.0-dev` and as
@@ -154,8 +159,10 @@
   link to the new repository operations guide.
 - Aligned GitHub About, homepage and topics with the official EasyLibrary lib
   repository pattern instead of leaving the remote metadata blank.
-- Kept the existing example plugins, but documented that they are still backed
-  by EasyLibrary's internal runtime until extraction work is promoted.
+- Reworked the example plugin docs as `LibModule` authoring references instead
+  of EasyLibrary-backed module examples. The docs now explain that PMMP
+  discovery/resource registration remains a host-adapter responsibility until
+  OP-68I/OP-68J finish the migration.
 - Updated `LibModuleInfo` and `package.yml` metadata to report
   contracts/read-model/provider-contract/provider-probe/dependency-resolver
   manifest/source, loader-boundary and registry/service readiness while still

README.md

@@ -120,12 +120,13 @@ The following pieces are already present:
   OP-68 finishes removing the old core runtime;
 - OP-60 live smoke evidence: `elprobe run libmodule` reports
   `functional=yes` for both package-backed virtual and standalone loading;
-- examples showing the current EasyLibrary-backed module format;
+- examples showing the `LibModule` authoring API with `BaseModule`,
+  `ModuleContext`, `BaseModuleCommand`, services, capabilities and diagnostics;
 - docs describing the extraction boundary and current scaffold status.
 
 PMMP host adapters such as YAML reading through `pocketmine\utils\Config`,
-listener/task registration and example plugin migration are still being
-extracted from EasyLibrary 3.0-dev after OP-68E.
+listener/task registration and copy-into-server example smoke are still being
+extracted from EasyLibrary 3.0-dev after OP-68H.
 
 ## Installation
 
@@ -141,30 +142,30 @@ EasyLibrary 3.0-dev. When both standalone and package-backed copies exist, the
 standalone plugin wins for that server session and EasyLibrary reports the
 internal package as shadowed.
 
-Plugins that use the current EasyLibrary-backed module authoring helpers should
-still depend on EasyLibrary:
+New module authoring code should import the public `LibModule` API:
 
-```yaml
-depend:
-  - EasyLibrary
+```php
+use imperazim\module\BaseModule;
+use imperazim\module\ModuleContext;
 ```
 
-Do not publish a stable migration promise from this dev baseline alone. The
-portable `LibModule` runtime is active/catalog-ready and the public authoring
-classes exist here, but EasyLibrary still owns filesystem discovery, runtime
-host registration and example migration until the rest of OP-68 is complete.
+Do not publish a stable copy-into-server module authoring promise from this dev
+baseline alone. The portable `LibModule` runtime is active/catalog-ready and
+the public authoring classes/examples exist here, but EasyLibrary still owns
+part of the PMMP host adapter until the rest of OP-68 is complete.
 
 ## Examples
 
-The `examples/` directory contains PocketMine-MP plugin examples that target
-the current EasyLibrary-backed module system:
+The `examples/` directory contains module authoring examples that target the
+`LibModule` API:
 
 - `01-basic-plugin`: basic module discovery and lifecycle;
 - `02-economy-provider-plugin`: service/capability provider example;
 - `03-farm-consumer-plugin`: cross-plugin consumer example;
 - `04-diagnostics-plugin`: controlled broken modules for diagnostics.
 
-See [docs/examples.md](docs/examples.md) for the current usage notes.
+See [docs/examples.md](docs/examples.md) for the current usage notes and host
+registration boundary.
 See [docs/authoring-api.md](docs/authoring-api.md) for the OP-68B
 `BaseModule`, context, helper, event, command, listener and async API slice.
 The command diagnostics surface is now owned here too: `/easymodule`,
@@ -251,6 +252,9 @@ runtime is removed.
 OP-68F prepared the public GitHub repository presence: badges, issue/PR
 templates, release note categories, Dependabot, CODEOWNERS, repository
 notification workflow documentation and remote About/topics metadata.
+OP-68H moved the authoring examples and usage docs out of EasyLibrary's legacy
+core tree and into this repository. The examples now use `ModuleContext` and
+the `LibModule` public helpers instead of EasyLibrary's legacy `ModuleManager`.
 
 ## License
 

docs/examples.md

@@ -1,42 +1,102 @@
 # Examples
 
-The runnable example plugins in this repository still target the EasyLibrary
-3.0-dev module runtime.
+The `examples/` directory now belongs to `LibModule` and targets the
+`imperazim\module` authoring API:
 
-Each example plugin declares:
+- modules extend `imperazim\module\BaseModule`;
+- lifecycle hooks receive `imperazim\module\ModuleContext`;
+- module-owned native commands extend `imperazim\module\command\BaseModuleCommand`;
+- listeners extend `imperazim\module\event\BaseModuleListener`;
+- services, capabilities, cleanup callbacks and diagnostics use
+  `ModuleContext`/`ModuleRuntime`.
 
-```yaml
-depend:
-  - EasyLibrary
-```
+These examples are intentionally no longer written against EasyLibrary's legacy
+`ModuleManager` helpers.
+
+## Current Host Status
+
+OP-68H moves the authoring examples and docs into `LibModule`. The examples are
+authoring references for the new API, not a stable copy-into-server promise yet.
+
+During the rest of OP-68, EasyLibrary still owns part of the PMMP host adapter:
 
-That dependency is correct for these examples until OP-68H migrates them.
+- plugin/module source discovery;
+- YAML reading through the PocketMine environment;
+- PMMP command, listener and task registration;
+- compatibility with old `ModuleManager`-centric modules.
 
-The public authoring API already exists in `LibModule` after OP-68B. The
-examples still need a separate pass because they also exercise filesystem
-discovery, command/listener/task registration and full server smoke behavior.
+That means a host must explicitly wire these examples into a `ModuleRuntime`
+session and register any PMMP resources it wants to expose. The files under
+`examples/` show the module shape and the runtime contracts that the host will
+load once OP-68I removes the remaining EasyLibrary legacy runtime.
 
 ## Included Examples
 
-- `01-basic-plugin`: minimal module discovery, command, listener, service and
-  task usage.
-- `02-economy-provider-plugin`: module-owned service and capability provider.
-- `03-farm-consumer-plugin`: module consuming a service from another example.
-- `04-diagnostics-plugin`: intentionally broken modules for doctor/failure
-  command testing.
+- `01-basic-plugin`: basic service/capability provider, health reporting,
+  cleanup and optional command/listener/task classes.
+- `02-economy-provider-plugin`: module-owned economy service and capability
+  provider.
+- `03-farm-consumer-plugin`: consumer module waiting on the economy service and
+  capability, plus optional hello-service usage.
+- `04-diagnostics-plugin`: intentionally disabled/missing-dependency modules
+  for doctor/failure output.
+
+## Module Shape
+
+Minimal module:
+
+```php
+<?php
+
+declare(strict_types=1);
 
-## Manual Test Flow
+namespace vendor\plugin\modules\farm;
 
-1. Install EasyLibrary 3.0-dev on a PocketMine-MP test server.
-2. Copy one example plugin directory into `plugins/`.
-3. Start the server.
-4. Run:
+use imperazim\module\BaseModule;
+use imperazim\module\ModuleContext;
 
-```text
-/easymodule list
-/easymodule doctor
-/easymodule info <module-id>
+final class FarmModule extends BaseModule {
+    protected function onEnable(ModuleContext $context): void {
+        $this->provideService('vendor:farm-service', new FarmService());
+        $this->addCleanup(static function(): void {
+            // Close runtime resources here.
+        });
+    }
+}
 ```
 
-The command names may change when the LibModule extraction reaches the command
-provider phase.
+Minimal manifest:
+
+```yaml
+id: vendor:farm
+name: Farm System
+version: 1.0.0
+loader: FarmModule
+namespace: vendor\plugin\modules\farm
+
+provides:
+  services:
+    - vendor:farm-service
+  capabilities:
+    - vendor.farm
+```
+
+## Host Registration Boundary
+
+`BaseModule` deliberately does not hide PMMP command/listener/task registration.
+That work belongs to the active host adapter, because `LibModule` also needs to
+support non-EasyLibrary consumers and pure runtime tests.
+
+A host can:
+
+1. scan `module.yml` files with `ModuleManifestPathScanner`;
+2. normalize them with `ModuleManifestNormalizer`;
+3. load classes with `ModuleClassFileLoader`;
+4. validate classes with `ModuleRuntimeClassValidator`;
+5. register module instances in `ModuleRuntime`;
+6. register optional PMMP resources such as `BaseModuleCommand`,
+   `BaseModuleListener` or `Task` instances.
+
+The current examples include command/listener/task classes so the host adapter
+has realistic resources to register, but the modules themselves only use the
+portable API.

docs/scaffold-status.md

@@ -1,11 +1,11 @@
 # Scaffold Status
 
-`LibModule` is intentionally in early extraction mode.
+`LibModule` is intentionally in 3.0-dev extraction mode.
 
 The repository can now be validated, built and released as a dev artifact, but
-it does not yet own the production module runtime. OP-40 moved only the first
-portable contracts/read-model slice. The runtime remains inside EasyLibrary
-under `imperazim\module` until later extraction steps promote it.
+the PMMP host adapter is still being completed. The portable runtime, command
+surface, authoring API and examples now live here; EasyLibrary still owns the
+transitional host bridge until OP-68I/OP-68J prove parity.
 
 ## Ready
 
@@ -17,21 +17,20 @@ under `imperazim\module` until later extraction steps promote it.
 - Discord notification workflow.
 - Portable module constants and read models.
 - Read-only module provider contract.
-- Examples preserved for current EasyLibrary-backed modules.
+- Authoring examples updated for the `LibModule` public API.
 
 ## Not Ready
 
-- Runtime replacement for EasyLibrary modules.
-- Module manager/lifecycle/commands.
-- Mutable provider operations.
+- Full PMMP host adapter ownership.
+- Copy-into-server example smoke as the only supported module workflow.
 - Official EasyLibrary package catalog entry.
 - Stable release.
-- Standalone production usage.
+- Standalone production usage without EasyLibrary host integration.
 
 ## Guardrails
 
-- Do not add `LibModule` to EasyLibrary's package catalog while
-  `runtime-ready` is `false`.
-- Do not remove `imperazim\module` from EasyLibrary until external provider
+- Keep `imperazim\module` owned by `LibModule`; EasyLibrary transitional code
+  must stay under `imperazim\library\module`.
+- Do not remove the remaining EasyLibrary host bridge until external provider
   tests prove parity.
 - Do not publish a stable release from scaffold-only code.

examples/01-basic-plugin/README.md

@@ -1,37 +1,37 @@
-# EasyModuleBasicExample
-
-Plugin minimo para testar um modulo externo da EasyLibrary.
-
-## O que ele testa
-
-- descoberta por `easylibrary-modules`;
-- `module.yml` externo;
-- `BaseModule`;
-- `ModuleContext`;
-- logger por modulo;
-- config propria do modulo;
-- command/listener/task registrados pelo lifecycle;
-- cleanup automatico;
-- service registry;
-- API publica por modulo;
-- health check.
-
-## Comandos
-
-```txt
-/examplehello
-/examplehello api
-/examplehello service
-/examplehello config
+# LibModule Basic Example
+
+Minimal module authoring example for the `LibModule` API.
+
+This example shows:
+
+- a `BaseModule` using `ModuleContext`;
+- service/capability provisioning;
+- module settings stored in `module.yml`;
+- health reporting;
+- cleanup registration;
+- optional PMMP-facing command, listener and task classes that a host adapter
+  can register.
+
+## Module
+
+```text
+examples:hello
 ```
 
-## Diagnostico recomendado
+## Provided Service
 
-```txt
-/easymodule info examples:hello
-/easymodule resources examples:hello
-/easymodule health examples:hello
-/easymodule services
-/easymodule capabilities
-/easymodule reload examples:hello
+```text
+examples:hello-service
 ```
+
+Contract/interface:
+
+```php
+easylibraryexamples\basic\modules\hello\api\HelloApi
+```
+
+## Notes
+
+The module itself only uses portable `LibModule` APIs. Command/listener/task
+registration is intentionally left to the active host adapter during the OP-68
+runtime extraction.