docs: update SDK reference for PlugwerkInstaller PluginManager-lifecycle SPI (plugwerk#424)

[bigpuritz]

Context

Upstream PR plugwerk/plugwerk#425 reshapes the PlugwerkInstaller SPI in the next beta release. Documentation that describes install / uninstall / download semantics needs updating before the upstream beta is published, otherwise the published docs will mislead readers.

What changed in the SPI

• download(pluginId, version, targetDir): Path — now does release-info lookup + SHA-256 verification + atomic move + cleanup-on-failure. Smart bits used to live inline in install. Throws on failure.
• install(pluginId, version): InstallResult — composes download(...) → pluginManager.loadPlugin → startPlugin. After successful return the plugin is live in PF4J. Reinstall semantics: same version → no-op success; different version → upgrade in place (stop + unload old → load + start new). Failure between download and start rolls back the artifact.
• uninstall(pluginId): UninstallResult (was InstallResult) — stops + unloads via PluginManager, then deletes the artifact file. New parallel result type UninstallResult carries only pluginId (no version).
• Wire-up: PlugwerkInstallerImpl now requires a PluginManager — PlugwerkPluginImpl.connect() reads it from the PF4J wrapper, embedders calling PlugwerkMarketplaceImpl.create(config, pluginManager) directly must pass one.

What needs updating in this repo

• SDK reference section — replace any "install means download + verify + place file" wording with "install means download + verify + load + start". Same for uninstall.
• Code snippets demonstrating the install flow — drop any explicit pluginManager.loadPlugin(...) / startPlugin(...) calls that follow installer.install(...). They are now redundant (done internally) and would fail with duplicate-id errors.
• Result type docs — add UninstallResult to the API reference; clarify that it has no version field (uninstall does not know it).
• PlugwerkMarketplaceImpl.create signature — update embedded code samples that show programmatic construction without PF4J: the second parameter is now pluginManager: PluginManager (required, not optional).
• Reinstall behaviour — document the same-version no-op and the different-version auto-upgrade. Worth a callout box because it is a non-obvious behaviour change.
• Failure / rollback — document that a load/start failure removes the partial artifact (atomic semantics).

Coordination

Track the upstream PR: plugwerk/plugwerk#425. Doc changes should ship in the same release as the SDK change (or at most one day later) so readers do not see stale snippets.

Acceptance

• All installer.install / installer.uninstall snippets compile against the new SPI
• UninstallResult has its own reference entry
• Reinstall + rollback semantics are documented explicitly
• No remaining mention of "install only places the file" or similar pre-#424 wording

[bigpuritz]

Heads-up: PR plugwerk/plugwerk#427 (fixes plugwerk/plugwerk#426) adds one more small change to the doc-update list — PlugwerkPlugin.connect(config) becomes connect(config, pluginManager). Every code snippet in the SDK reference that shows plugin.connect(config) needs the second parameter:

// Before
plugin.connect(config).use { marketplace -> ... }

// After
plugin.connect(config, pluginManager).use { marketplace -> ... }

Background: PF4J 3.15 deprecates the entire Plugin#wrapper injection path; threading PluginManager through the SPI signature keeps the SDK off the deprecated API surface. Full rationale in plugwerk/plugwerk#427.