@@ -16,8 +16,14 @@ Clause-②: no
 
 **What an operator sees.** The kernel reports `Plugin com.objectstack.engine.objectql failed to start`, and the cause is the package door's envelope: `code: 'NAMESPACE_CONFLICT'` (`NAMESPACE_CONFLICT_CODE` is exported), `status: 422`, and `conflicts[]` with `{ catalogType, name, incomingPackageId, existingHolder: { kind: 'environment' } }`. The message names the package that declares each name and the environment catalog that holds it.
 
-**The upgrade shape.** A deployment fails to boot after this release when an active, environment-wide `sys_metadata` row of type `permission` or `position` has the name of a permission set or position that a configured package declares. That includes a row saved over a package-held name before the packaged locks refused such saves, whether or not the row was bound to the package, and a row over one of the platform security plugin's own permission sets (`member_default`, `admin_full_access` and the rest it declares).
+**The upgrade shape.** A deployment fails to boot after this release when an active, environment-wide `sys_metadata` row of type `permission` or `position` (or the legacy plural `permissions` / `positions`, which the boot's load folds to the same types) has the name of a permission set or position that a configured package declares. That includes a row saved over a package-held name before the packaged locks refused such saves, whether or not the row was bound to the package, and a row over one of the platform security plugin's own permission sets (`member_default`, `admin_full_access` and the rest it declares).
 
-**The one-line fix: rename the item in the package, or rename or delete the environment's item, then restart.** To reach the environment's item through the metadata API, boot once without the package in the configuration, rename or delete the item (`DELETE /api/v1/meta/permission/<name>`, `DELETE /api/v1/meta/position/<name>`), and add the package back. For a name the platform security plugin declares, delete the environment-wide `sys_metadata` row of that type and name in the database. Nothing renames or removes either item automatically.
+**The one-line fix: rename the item in the package, or rename or delete the environment's item, then restart.**
+
+- **Before upgrading, for a permission set.** On the release you run now, a boot whose environment catalog overlays a package-declared permission set logs at `kernel:ready`: `[security] N package-declared permission set(s) are being shadowed by an environment overlay`, with the set names. Those are the permission sets this release refuses at boot. The audited **Discard Overlay** action on the set's record in Setup (`POST /api/v1/security/permission-sets/<id>/discard-overlay`, documented under "Declared ≠ enforced" on the Permission Sets page) removes the overlay and resyncs the set to the package's definition. So does `DELETE /api/v1/meta/permission/<name>`, which answers "Customization overlay deleted … reset to artifact default". Either works for the platform security plugin's own sets too, and neither touches the database. Positions have no such reading and no such action.
+- **After upgrading, for a package you can leave out.** Boot once without the package in the configuration, rename or delete the environment's item through the metadata API (`DELETE /api/v1/meta/permission/<name>`, `DELETE /api/v1/meta/position/<name>`), then add the package back.
+- **After upgrading, for a name the platform security plugin declares.** Back the database up, then delete the row in it. The rows that refuse the boot are the active, environment-wide ones of that name: `organization_id IS NULL` and `state = 'active'`, whatever their `package_id`, under the type or its legacy plural: `DELETE FROM sys_metadata WHERE organization_id IS NULL AND state = 'active' AND type IN ('permission', 'permissions') AND name = '<name>';` (for a position, `type IN ('position', 'positions')`). A draft row and an organization-scoped row are not loaded at boot and do not refuse it.
+
+No `os` command deletes a `sys_metadata` row offline: `os meta delete` and `os data delete` call a running server. Nothing renames or removes either item automatically.
 
 **What is NOT refused.** A stored definition under a built-in position name (`org_admin`, `everyone` and the other four): the platform declares its built-in positions itself, after this check, and the stored definition keeps answering first. The same package restarting with its own names. A package whose names the environment catalog does not hold, booting beside the environment's own items.
@@ -368,7 +368,9 @@ either can be live on one row, and they need different remedies:
   current artifact immediately. It refuses on any set that no installed code
   package ships (a set created in this environment, a clone, or a set saved
   into a writable runtime package), so it can never destroy a genuinely
-  environment-authored set.
+  environment-authored set. **Discard it before you upgrade:** from the
+  release that adds ADR-0048's cold-boot check, a deployment that still holds
+  such an overlay does not boot, so the action can no longer reach it.
 - **Provenance skip.** The record's `managed_by` column predates package
   provenance tracking (a legacy insert without `managed_by: 'package'` —
   typically a database first initialized on an older release line), so boot