From 78da671ea73579804c614cd933a318a950b7be58 Mon Sep 17 00:00:00 2001
From: sjmiller609 <7516283+sjmiller609@users.noreply.github.com>
Date: Mon, 10 Aug 2026 20:23:42 +0000
Subject: [PATCH 1/2] docs: simplify the SDK release flow

---
 .github/workflows/stlc-generate.yml  |  6 +++---
 docs/runbooks/sdk-generation-stlc.md | 16 ++++++++--------
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/stlc-generate.yml b/.github/workflows/stlc-generate.yml
index 4d7ae4c8..3515a3c5 100644
--- a/.github/workflows/stlc-generate.yml
+++ b/.github/workflows/stlc-generate.yml
@@ -9,9 +9,9 @@
 # each SDK repo and opens a do-not-merge draft PR per repo — never main, no
 # seal-back, no docs publish. See the runbook.
 # On push to main: rebuilds and pushes to each staging repo's main. The staging
-# promotion workflow fast-forwards production main, where release-please opens
-# the version + changelog PR. Merging that PR publishes the package, and
-# production releases fast-forward back into staging.
+# promotion workflow advances the public SDK's `next` branch, and release
+# automation opens or updates one versioned PR from `next` to `main`. Merging
+# that PR publishes the package, and production releases sync back to staging.
 #
 # Operator commands and recovery notes are in docs/runbooks/sdk-generation-stlc.md.
 name: Generate SDKs with stlc
diff --git a/docs/runbooks/sdk-generation-stlc.md b/docs/runbooks/sdk-generation-stlc.md
index 9b794681..6228fb9e 100644
--- a/docs/runbooks/sdk-generation-stlc.md
+++ b/docs/runbooks/sdk-generation-stlc.md
@@ -9,18 +9,18 @@ Hypeman's Go and TypeScript SDKs are generated by
    internal SDK staging repositories and posts one build-manifest comment.
 2. Merging the config PR validates the integrated SDKs and pushes staging
    `main` only after bootstrap, lint, tests, and clean-worktree checks pass.
-3. Each staging repo opens or updates one `stainless/release` PR against its
-   public production repo. Merge it with a merge commit; never squash or rebase.
-4. Release-please opens the version and changelog PR in production. Merging it
-   publishes the package.
+3. Each staging repo advances its public production repo's `next` branch.
+4. Release automation opens or updates one versioned PR from `next` to `main`.
+   New SDK changes accumulate in that PR until it is merged. Merge it with a
+   merge commit to publish the package; the next SDK change opens a new PR.
 5. The scheduled sync fast-forwards production commits back into staging.
 
 ## Normal API changes
 
 Update `openapi.yaml` and `stainless.yaml`, then open a PR. Review the generated
-preview branches and manifest diagnostics before merging. The public SDK
-promotion PRs are created or updated automatically; publishing requires merging
-them with merge commits, then merging the release-please PRs.
+preview branches and manifest diagnostics before merging. Each public SDK gets
+one versioned release PR; publishing requires merging that PR with a merge
+commit.
 
 Every merged SDK-affecting PR becomes a releasable SDK commit automatically.
 Explicit `feat:`, `fix:`, `perf:`, and `revert:` titles are preserved; other
@@ -70,5 +70,5 @@ rerun full SDK validation.
 ## Final hosted cutover
 
 Remove hosted-only secrets and uninstall the Stainless GitHub App only after a
-complete preview → staging → promotion → release-please → publish → back-sync
+complete preview → staging → `next` → release PR → publish → back-sync
 round trip succeeds for both SDKs.

From 88d4381e5e4be85fe327efee70245e64306303fa Mon Sep 17 00:00:00 2001
From: sjmiller609 <7516283+sjmiller609@users.noreply.github.com>
Date: Mon, 10 Aug 2026 21:34:50 +0000
Subject: [PATCH 2/2] Document SDK promotion recovery PRs

---
 docs/runbooks/sdk-generation-stlc.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/runbooks/sdk-generation-stlc.md b/docs/runbooks/sdk-generation-stlc.md
index 6228fb9e..f36f6207 100644
--- a/docs/runbooks/sdk-generation-stlc.md
+++ b/docs/runbooks/sdk-generation-stlc.md
@@ -13,6 +13,8 @@ Hypeman's Go and TypeScript SDKs are generated by
 4. Release automation opens or updates one versioned PR from `next` to `main`.
    New SDK changes accumulate in that PR until it is merged. Merge it with a
    merge commit to publish the package; the next SDK change opens a new PR.
+   If promotion finds a Git conflict, it opens a draft recovery PR against
+   `next`; resolve and merge it, then rerun the staging promotion workflow.
 5. The scheduled sync fast-forwards production commits back into staging.
 
 ## Normal API changes