docs: UPDATING-BUNDLES — the adapter/bundle half of an update

[Alexgodoroja]

Adds docs/UPDATING-BUNDLES.md, written from shipping io.pilot.bowmark v1.0.0 (#97) end to end.

Why

UPDATING.md documents the rules of an update — bump the version, re-sign with the same key, no downgrades — and stops there. It says nothing about producing and publishing the artifacts that update actually ships, and that is where the work was. There was no doc to follow for: building all four platforms from a rich submission, when to upload relative to the merge, verifying what the public URL serves rather than what the upload reported, running the new methods against the published artifact on both operating systems, or the broker step when an update changes HTTP routes.

The ordering rule leads, because it is the one that strands an update

For a rich submission the catalogue entry is derived from whatever is already live on the artifact registry for that id@version. Merge with nothing uploaded and the publish job fails loudly — but the submission PR is merged, the catalogue still points at the old version, and the app looks shipped while every user is on the previous release. So: build → verify → upload → verify the URLs → runtime e2e → then merge.

It also fixes a line that actively misleads

UPDATING.md told publishers:

make package        # rebuild EVERY platform, re-signed with your EXISTING key

make package builds one platform — the host's — and its tarball omits install.json. PUBLISHING-PLAYBOOK.md says so in Step 3 and separately says a single-platform bundle is rejected as "a build-host accident". A publisher following the update doc ships exactly that. Corrected, and pointed at the canonical builder.

Gotchas documented, all hit during #97

• A submission cannot carry a changelog. No changelog on SubListing and ToConfig does not map one, so a rich submission publishes the generated Released v<version> placeholder. The Bowmark publisher spotted this themselves and supplied the notes out-of-band; worth writing down so the next one does not have to.
• A republish reuses the existing store page, refreshing the runtime facts, demo and next-steps graph but keeping the description, tagline, method list and keywords. Correct for a version bump. For a pivot it ships a new demo beside prose describing methods that no longer exist.
• A retired upstream route fails quietly. Every signature and sha check still passes; only the calls break.
• The broker allow-list is registered config, not derived per call. When an update retires POST /v1/old for POST /v1/new, a stale allow-list refuses the new method and forwards the retired one to an endpoint that no longer exists. Both directions broken, neither visible in a build or a review gate.

Scope

Publisher-facing and deliberately ends at the merge: the catalogue entry and store page are referenced as the downstream steps and left to PUBLISHING-PLAYBOOK.md. No hosts, credentials, bucket names, registry paths or ops commands — the presigned upload flow already documented in R2-ARTIFACT-REGISTRY.md is the path publishers are pointed at.

Linked from UPDATING.md, PUBLISHING-PLAYBOOK.md and CLAUDE.md. Docs only; no code paths touched.