Version: 3.4dev-20260818_054835

MB663 is a deliberately quiet round.

No new spell was added to the bot. No database chamber was opened. No runtime creature was disturbed.

Instead, we finally wrote down how some of Mediabot’s most important operational magic is supposed to be used.

🗺️ The Doctor is no longer hidden in the castle

tools/mediabot_doctor.pl already existed as a serious read-only diagnostic tool, but it was barely visible from the main README.

MB663 fixes that.

The README now explains how to run the Doctor against a real instance:

perl tools/mediabot_doctor.pl --conf=mediabot.conf

and documents its useful modes:

--strict
--json
--domain

It also explains the three operational verdicts:

READY
DEGRADED
UNSAFE

Most importantly, the documentation makes the contract explicit:

The Doctor diagnoses. It does not repair.

No migrations, configuration edits, service restarts or deployment changes are performed by the Doctor.

📜 The missing MB646 migration scroll

The Achievement persistence work from MB646 was already implemented and tested, but the complete operational upgrade procedure was still scattered across the project.

MB663 closes that gap.

docs/DB_MIGRATIONS.md now documents the real sequence for upgrading an existing instance:

Doctor
→ stop instance
→ database backup
→ MB646 migration
→ schema / migration verification
→ restart
→ Doctor

It also documents the difference between two situations that may look similar but are operationally very different.

An old pre-MB646 instance can still run using the legacy JSON Achievement state.

That does not mean the new code is safe to restart against an unmigrated database.

The Doctor will correctly report the missing required MB646 schema as:

UNSAFE

until the migration has been applied.

🧙 Deployment families stay in their own houses

The documentation now also describes the archive recovery rule introduced with MB646.

When importing old Achievement state, Mediabot only considers archives belonging to the same deployment family.

For example:

mediabot3
mediabot3.old.20260801_120000

belong together.

But:

mediabot_v3.*

does not belong to that family and must be ignored.

No Slytherin archive sneaking into Gryffindor’s dormitory.

🗝️ Legacy JSON remains safe and idempotent

The runbook also explains what happens to the old live Achievement JSON file.

After a successful import:

var/achievements.json
→ var/achievements.json.migrated-<timestamp>

Historical archive files remain untouched.

If the import fails, the database transaction is rolled back and the live JSON file is not falsely marked as migrated.

Already-populated MB646 databases also avoid repeating the historical archive scan unnecessarily.

🧪 Validation

The Doctor-specific regression remains green:

PASSED : 229/229
RC=0

The normal fast validation lane also passed:

PASSED : 5175/5175
RC=0
Runtime : 177s

And immediately before this documentation round, the complete MB662 checkpoint passed:

PASSED : 13667/13667
RC=0
Runtime : 894s

That last number is also a reminder that the full suite is still nearly fifteen minutes long. The fast lane makes everyday development much more practical, but the cost of the complete suite remains an engineering concern.

✨ What MB663 changes

README.md
docs/DB_MIGRATIONS.md
CHANGELOG.md
VERSION

And what it deliberately does not change:

no runtime code
no database schema
no migration
no configuration
no service
no systemd behaviour

Sometimes the most useful magic is simply making sure everyone knows where the spellbook is — and what happens before they open it.