How upgrade, hide, disable and uninstall fit together

Who does what, when

Action	By	When	Verify afterwards
Upload a new version	Developer	Code, content, schema or permissions change	New version number, new signature, review
Hide a version	Developer owner	Stop offering that version	Existing installations and support
Upgrade an installation	Customer’s installation manager	Apply an authorised, compatible version	Confirm new permissions, check configuration and real calls
Disable	Customer’s installation manager (with a reason)	Pause what the installation provides	Pages gone, calls refused, no new events
Uninstall	Customer’s installation manager (with a reason)	Revoke the installation	Authorisation revoked; callbacks and data handled as agreed

Shipping an upgrade

Bump metadata.version above every reviewed version.
Make sure spec.compatibility.control_api covers the target control planes; ones that do not match cannot install or upgrade to it and keep their last compatible version.
Any permission change sends the version to human review, and customers confirm new permissions when upgrading.
Release notes say what changed, the minimum control plane version, whether permissions were added, how configuration migrates and how to recover from a failure.

A failed upgrade leaves the installation in upgrade_failed_lkg_preserved with the last good version kept. That does not replace your own data migration and rollback; how to roll back depends on the kind and supported versions, so document recovery steps and never ask customers to edit a database.

After disable and uninstall

After disabling or revoking permissions, new events and replays are authorisation-checked too. Your service must recognise the revocation, stop using revoked API keys and installation identities, not retry refused requests forever, and handle data you hold as agreed with the customer.

A complete delivery verifies at least: a first install, an upgrade, use by an ordinary user and by an administrator, a dependency outage, revoked permissions, repeated requests, the last good version after a failed upgrade, and pages, calls and events all stopping after uninstall.

Troubleshooting

Symptom	Check first	Next step
Cannot open “My plugins”	Onboarding status, current entity, team role	The owner checks the application and member roles
Key verification fails	Expired challenge, partial copy, wrong key	Get a new challenge and sign again
Namespace conflict	Claimed by another publisher, reserved prefix	Use your own namespace
Signature or digest mismatch	Same pack run? Edited after signing?	Pack and sign again from the sources
Tool exits 0 without output	Did it print the check and output lines?	Run again from the real path given by pwd -P and check the files
Version already exists	Version list and detail	Continue with it if created; bump the version to change files
Approved but customers cannot see it	Published? Channel, compatibility, price plan	Check each one; do not keep changing files
Fetched but nothing works	Confirmed, enabled, configured? Current role	Verify with the target role where it mounts
Free plugin cannot be fetched	An active zero-price plan?	The owner adds one under “Pricing”
Calls refused	Installation state, approved permissions, credential type and scope	Follow the operation’s auth; never switch to a more privileged account

When contacting support give the plugin ID, version, time, request_id, error code and redacted screenshots. Never send passwords, private keys, API or webhook secrets, or raw customer data.