MB698 closes an important gap in the Mediabot v3 plugin v2 lifecycle.

Until now, plugin v2 sidecar manifests could describe commands correctly, but the complete path from configuration to automatic boot loading and command registration still needed to be hardened.

This round focused on one simple requirement:

If a plugin is configured for autoload, restarting Mediabot must bring it back completely — including its commands.

No Time-Turner required. 🕰️✨

---

🧩 What changed

MB698 strengthens the plugin/script subsystem around four areas:

plugins.SCRIPTS

The sample configuration and documentation now clearly describe the plugin script directory and its role in plugin discovery.

The configuration contract is explicit instead of being something an administrator needs to infer from the source code.

---

🔐 Explicit AUTOLOAD gate

Boot-time loading now respects the plugin v2 autoload contract.

A plugin is not simply executed because a file happens to exist in the scripts directory.

The loader evaluates the expected metadata and only loads plugins that are meant to participate in automatic startup.

That keeps startup predictable and avoids turning the scripts directory into an accidental execution bucket.

---

🧙 Command registry restoration

The most important runtime issue discovered during the MB698-P validation was not actually loading the plugin itself.

The plugin could return after restart, while its public command was still missing from Mediabot’s live command registry.

That was the real bug.

The registration bridge has now been corrected so that commands declared through the plugin v2 mechanism become available again when the plugin is loaded during boot.

In other words:

configuration
    ↓
plugin discovery
    ↓
AUTOLOAD decision
    ↓
plugin load
    ↓
command declaration
    ↓
live command registry

The whole chain now survives a restart.

---

🧪 Live proof

The change was not validated only with synthetic unit tests.

A temporary second plugin was introduced on the development instance to exercise the real boot path.

During that validation Mediabot reported:

Plugin autoload: loaded 2 plugin(s)

The temporary plugin was then removed and the original state restored bit-for-bit.

After another boot:

Plugin autoload: loaded 1 plugin(s)

This demonstrated both sides of the contract:

• a newly eligible plugin is discovered and loaded;
• removing it restores the original runtime state cleanly;
• the existing plugin remains operational;
• no temporary script remains deployed afterward.

Final live state:

service      = active/running
restarts     = 0
scripts_live = ABSENT

---

🧪 New regression protection

MB698 adds:

t/cases/912_mb698_plugin_v2_boot_autoload.t

The new test protects the plugin v2 boot/autoload behaviour so this lifecycle cannot quietly regress later.

During the final documentation pass, two older repository contracts also did exactly what they were supposed to do and caught inconsistencies before release.

One protected the historical cookbook heading:

## 10. Plugin v2: declare your commands in a sidecar manifest

The second enforces that a numbered MB repository contract has a corresponding entry in the [Unreleased] changelog.

Rather than weakening those sentinels, the documentation was corrected.

That’s precisely why those tests exist. 🛡️

---

📚 Documentation

The plugin documentation has been expanded in:

plugins/scripts/README.md
plugins/scripts/COOKBOOK.md
mediabot.sample.conf
CHANGELOG.md

It now covers the plugin v2 boot lifecycle more explicitly, including:

• the scripts location;
• sidecar manifests;
• AUTOLOAD behaviour;
• command declaration;
• persistence across restart;
• runtime registration expectations.

The goal is that somebody writing a plugin should be able to understand the contract from the documentation rather than reverse-engineering PluginManager.pm.

---

🧹 Final validation

The last validation round was deliberately performed in increasing scope.

Targeted regressions

PASSED : 63/63

Fast validation lane

334/334 files
6142/6142 tests
PASSED

Complete suite

795/795 files
16053/16053 tests
PASSED

Full-suite runtime:

216s reported by the test runner
240s total validation wrapper duration

And finally:

RC_PATCH=0
RC_TARGETED=0
RC_FAST=0
RC_FULL=0
RC_DIFF=0

No regression was detected.

---

📦 Commit

Published on master:

8991b31
MB698: teach plugin v2 sidecars to return after reboot — no Time-Turner required

Result:

9 files changed
303 insertions(+)
24 deletions(-)

Version:

3.4dev-20260825_095833

The local repository and GitHub were verified immediately afterward:

HEAD -> master
origin/master -> 8991b31

git status --short
# clean

git status -sb
## master...origin/master

---

🏰 What MB698 gives us

The plugin v2 mechanism is now considerably closer to being a genuine extension interface rather than merely a way to execute additional code.

A plugin can declare what it provides, be selected for automatic startup, return after a Mediabot restart, and have its commands restored into the running bot.

That lifecycle is now documented, exercised live and protected by regression tests.

There are fewer hidden incantations required to write a plugin — which is generally a good sign in software engineering, even if Hogwarts might disagree. 🧙‍♂️

---

🚧 Next gate: fresh Debian 13

One important thing remains deliberately unclaimed by MB698:

a clean Debian 13 installation is still a mandatory manual gate.

The development instance and complete regression suite are green, but that does not replace validating the installation and plugin behaviour from a fresh operating-system environment.

So the next step is:

Fresh Debian 13
    ↓
clean installation
    ↓
configuration
    ↓
plugin v2/autoload verification
    ↓
full validation

Only after that gate do we move on.

No premature victory banner. No mysterious Platform 9¾ shortcut. 🚂

---

MB698 / MB698-P: CLOSED ✅

🪄 Mischief managed.