Fix/plugin audit findings (#2031)

* fix(plugins): enforce manifest apiVersion at install and activation

* test(plugins): exercise the absent-apiVersion default

* feat(plugins): generate the core-event catalog into host-facts

* docs(plugins): explain the packing.listBags write-permission binding

* test(plugins): cover apiVersion upload refusal; tidy docblocks and generator header

* fix(plugin-sdk): validate settings options and oauth like the host

* fix(plugin-sdk): model the full manifest shape and stop dropping fields

* fix(plugin-sdk): drop non-string routeProfiles icons like the host

* docs(plugin-sdk): document host limits, oauth contract, and ignored asUserId

* feat(plugin-sdk): enforce daily budgets and meta quotas in the mock host

* feat(plugin-sdk): expose the generated core-event catalog

* feat(plugin-sdk): scaffold trek range >=3.4.0 <5.0.0 ahead of TREK 4.0

* feat(plugin-sdk): scaffold the oauth broker settings for oauth:client plugins

* chore(plugin-sdk): fix stale mirror docs and the colliding permissions export

* docs(plugin-sdk): add the rate-limit string; restore trek docblock; match host meta sizing

* feat(plugin-sdk): raise the scaffold trek floor to 4.0.0

* docs(wiki): bring the plugin pages in line with the current runtime

* docs: bring the workspace CLAUDE.md guides up to date and make them committable

* feat(plugin-sdk): roll back failed publishes, add unrelease, sync the fork, retro-sign updates

* docs(wiki): document the publish rollback, unrelease, fork sync, and retro-signing

* chore(plugin-sdk): 1.6.0

plugin-sdk/src/cli/help.ts

@@ -18,7 +18,7 @@ export const VERSION_LINE = (v: string): string => `trek-plugin-sdk ${v}`;
 export const PATH_COMMANDS = ['create', 'dev', 'status', 'publish'] as const;
 
 /** Real, supported, and not what a newcomer needs to see first. */
-export const OTHER_COMMANDS = ['validate', 'pack', 'shot', 'keygen', 'sign', 'entry', 'preflight', 'submit', 'release'] as const;
+export const OTHER_COMMANDS = ['validate', 'pack', 'shot', 'keygen', 'sign', 'entry', 'preflight', 'submit', 'release', 'unrelease'] as const;
 
 export interface CommandHelp {
   /** One line, for the top-level list. */
@@ -85,7 +85,7 @@ you like.`,
 
   publish: {
     summary: 'release + open the registry PR',
-    usage: 'trek-plugin publish [dir] --repo <owner/name> --tag <vX.Y.Z> [--sign]',
+    usage: 'trek-plugin publish [dir] --repo <owner/name> --tag <vX.Y.Z> [--sign] [--keep-release]',
     body: `The whole release, in order:
 
   1. check       every registry gate that can be checked locally
@@ -98,6 +98,12 @@ Step 1 comes first for a reason: a GitHub release is effectively immutable, beca
 pins its sha256. If a check fails, NOTHING is packed, tagged, pushed or released — so you can fix
 it and re-run against the same version.
 
+And when a LATER step fails, publish rolls back exactly what the run created — the release, the
+pushed tag, the local tag — so the same tag is free to re-run against once you have fixed the
+problem. Pass --keep-release to leave them in place instead (the error then prints the manual
+cleanup). Anything that existed before the run is never touched. A leftover tag from an earlier
+failed run is recognised (no release for it, not on HEAD) and moved to HEAD rather than reused.
+
 In a terminal it OFFERS TO SIGN, and creates a key for you if you have none. A signature proves the
 artifact came from you, not just that its bytes match what the registry saw. You can add signing
 later — publishing unsigned now and signing at v1.4.0 breaks nobody — but you can never take it
@@ -217,6 +223,19 @@ hand, or to re-check a release you have already cut.
     body: `Packs, cuts the GitHub release, and prints the registry entry — but does NOT open the registry PR.
 For when you want to release now and submit later. \`publish\` is the whole thing.`,
   },
+  unrelease: {
+    summary: 'delete a stranded tag + release (never a published one)',
+    usage: 'trek-plugin unrelease <vX.Y.Z> [dir] --repo <owner/name> [--registry owner/name] [--yes]',
+    body: `Undoes a release that never made it into the registry: deletes the GitHub release, the remote
+tag, and the local tag — each reported, each skipped when already gone. For when a publish
+failed halfway (though \`publish\` now rolls its own failures back), or you changed your mind
+before the registry PR merged.
+
+The one hard rule: a version that IS published in the registry is immutable — the registry pins
+the artifact's sha256, so deleting its release breaks install/update for everyone who has it.
+unrelease checks the published index first and refuses those outright, with no override. If the
+registry cannot be reached to check, it refuses unless you pass --yes.`,
+  },
 };
 
 export function topLevelHelp(version: string): string {