docs+code: note staged is npm-only + per-package assumption (per-target when multi-target lands)

Author: theoephraim

docs/configuration.md

@@ -108,6 +108,8 @@ Requirements:
 - npm >= 11.15.0
 - The package must already exist on the npm registry (first publish cannot be staged)
 
+Staging is an **npm-registry feature** — it only applies to packages published through the standard npm flow. Packages that publish via a `publishCommand` (jsr, cargo, anything custom) have no staging equivalent, so they publish live as usual. In a mixed release, npm packages stage while custom-target packages go live immediately; each finalizes independently. Staged tracking also relies on **GitHub releases** (the staged state and finalize step live in the draft release), so it needs `gh` available — there's no staged flow without a GitHub release to track it on.
+
 ```json
 {
   "publish": {

packages/bumpy/src/commands/publish.ts

@@ -602,6 +602,11 @@ async function runPublishFlow(
 
       const { registry, repoSlug } = registryByPkg.get(release.name) || {};
       let changed = false;
+      // `published`/`staged`/`failed` are per-package (see PublishResult), so every target
+      // of the package takes the same status. That's correct while each package has exactly
+      // one target (see publishTargetsByPkg above). If a package ever publishes to a mix of
+      // stageable (npm) and live (jsr/cargo) targets in one run, this loop must switch to a
+      // per-target result so it can mark "npm staged, jsr success" independently.
       for (const targetName of targets) {
         // Skip already-succeeded targets
         if (info.metadata.targets[targetName]?.status === 'success') continue;

packages/bumpy/src/core/publish-pipeline.ts

@@ -260,7 +260,15 @@ export async function publishPackages(
       }
 
       // Staged publishing only applies to the standard npm flow (not custom commands),
-      // and never to snapshots (opts.noStage).
+      // and never to snapshots (opts.noStage). Staging is an npm-registry feature — no
+      // other publish target (jsr, cargo, custom commands) has an equivalent.
+      //
+      // NOTE: this is a per-*package* decision because bumpy currently gives each package
+      // exactly one publish target (see publishTargetsByPkg in commands/publish.ts). If a
+      // future multi-target model lets one package publish to npm (stageable) AND another
+      // target (live) in the same run, this — and PublishResult below — must become
+      // per-target: a package could be "npm staged, jsr live" at once, which a per-package
+      // staged/published split can't express.
       const isStaged =
         publishConfig.npmStaged && publishConfig.publishManager === 'npm' && !pkgConfig.publishCommand && !opts.noStage;