ci: comment on validate-pr-base failure, drop conventional-commit skip label, document workflow

Workflow changes:
- validate-pr-base now posts (or updates) an explanatory PR comment when
  it fails, telling the contributor exactly how to resolve: either
  re-target the PR to `next` or add the `target-main` label. The comment
  is removed automatically when the check passes (re-target, label, or
  bot exemption).
- validate-pr-title no longer honors the `skip-conventional-commit-check`
  label. Conventional Commits is enforced unconditionally so the
  release-please changelog stays consistent.

Docs:
- CONTRIBUTING.md gains (or updates) a "Contribution workflow" section
  covering the branch model and conventional commits, with the new CI
  enforcement notes and the `target-main` label escape hatch.
- CLAUDE.md gains a short "Contribution workflow" section pointing
  to the same guidance for Claude Code sessions.

Author: declan-scale

.github/workflows/lint-pr.yaml

@@ -14,7 +14,6 @@ jobs:
   validate-pr-title:
     name: Validate PR title (Conventional Commits)
     runs-on: ubuntu-latest
-    if: ${{ !contains(github.event.pull_request.labels.*.name, 'skip-conventional-commit-check') }}
     steps:
       - name: Check Conventional Commits format
         env:
@@ -39,35 +38,82 @@ jobs:
             echo "    feat: add new endpoint"
             echo "    fix(client): handle empty response"
             echo "    chore!: drop python 3.11 support"
-            echo ""
-            echo "  Add the 'skip-conventional-commit-check' label to bypass this check."
           } >&2
           exit 1
 
   validate-pr-base:
     name: Validate PR base branch
     runs-on: ubuntu-latest
-    if: github.event.pull_request.base.ref == 'main'
     permissions:
-      pull-requests: read
+      pull-requests: write
     steps:
-      - name: Check base branch
+      - name: Validate base branch and manage PR comment
         env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
           PR_AUTHOR: ${{ github.event.pull_request.user.login }}
+          PR_BASE: ${{ github.event.pull_request.base.ref }}
           HAS_LABEL: ${{ contains(github.event.pull_request.labels.*.name, 'target-main') }}
         run: |
-          # Exempt automated PRs (Stainless codegen, release-please, dependabot, etc.)
+          MARKER='<!-- lint-pr-validate-base -->'
+
+          # Find any existing marker comment so we can update or delete it.
+          existing_id=$(gh api "repos/$REPO/issues/$PR_NUMBER/comments" \
+            --jq ".[] | select(.body | contains(\"$MARKER\")) | .id" | head -n1)
+
+          delete_comment() {
+            if [ -n "$existing_id" ]; then
+              gh api -X DELETE "repos/$REPO/issues/comments/$existing_id" >/dev/null 2>&1 || true
+            fi
+          }
+
+          # PR doesn't target main — nothing to enforce.
+          if [ "$PR_BASE" != "main" ]; then
+            delete_comment
+            echo "PR base is '$PR_BASE'; check passes."
+            exit 0
+          fi
+
+          # Exempt automated PRs (Stainless codegen, release-please, dependabot, etc.).
           case "$PR_AUTHOR" in
             stainless-app|stainless-app\[bot\]|release-please\[bot\]|github-actions\[bot\]|dependabot\[bot\])
+              delete_comment
               echo "PR is from automation ($PR_AUTHOR); allowing PR targeting main."
               exit 0
               ;;
           esac
 
+          # Per-PR opt-out via label.
           if [ "$HAS_LABEL" = "true" ]; then
+            delete_comment
             echo "Found 'target-main' label; allowing PR targeting main."
             exit 0
           fi
 
-          echo "::error title=PR should target 'next'::PRs should target the 'next' branch by default. The 'main' branch is reserved for release-please and Stainless automation. If this PR is an intentional hotfix or automation exception, add the 'target-main' label to bypass this check, or re-target the PR base to 'next'."
+          # Failure: post or update an explanatory PR comment, then fail the check.
+          body_file=$(mktemp)
+          {
+            echo "$MARKER"
+            echo
+            echo "**This PR is targeting \`main\`, but PRs should target the \`next\` branch by default.**"
+            echo
+            echo "The \`main\` branch is reserved for release-please and Stainless automation. To resolve, pick one of:"
+            echo
+            echo "- **Re-target the PR to \`next\`** (recommended). On the PR page, click **Edit** next to the title and change the base branch to \`next\`."
+            echo "- **Add the \`target-main\` label** if this is an intentional exception (e.g. an urgent hotfix). The check will re-run and pass."
+            echo
+            echo "See \`CONTRIBUTING.md\` for the full branch model."
+          } > "$body_file"
+
+          if [ -n "$existing_id" ]; then
+            gh api -X PATCH "repos/$REPO/issues/comments/$existing_id" \
+              -F body=@"$body_file" >/dev/null
+            echo "Updated existing PR comment ($existing_id)."
+          else
+            gh pr comment "$PR_NUMBER" --repo "$REPO" --body-file "$body_file" >/dev/null
+            echo "Posted new PR comment."
+          fi
+
+          echo "::error title=PR should target 'next'::See the PR comment for resolution steps. Re-target to 'next' or add the 'target-main' label."
           exit 1

CLAUDE.md

@@ -2,6 +2,17 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Contribution workflow
+
+- This repository is a Stainless-generated SDK. Open PRs against the `next` branch (not `main`).
+  Stainless watches `next` and release-please opens release PRs from `next` → `main`.
+- PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/) — the
+  `Validate PR title (Conventional Commits)` CI check enforces this on every PR.
+- The `Validate PR base branch` CI check fails on PRs targeting `main` from non-automation accounts
+  and posts a comment with resolution steps. Add the `target-main` label only for genuine
+  exceptions (e.g. an urgent hotfix).
+- See `CONTRIBUTING.md` for the full workflow.
+
 ## Development Commands
 
 ### Package Management in the top level repo

CONTRIBUTING.md

@@ -32,6 +32,39 @@ Alternatively if you don't want to install `Rye`, you can stick with the standar
 $ pip install -r requirements-dev.lock
 ```
 
+## Contribution workflow
+
+This repository is generated and released by [Stainless](https://www.stainless.com/). To keep the
+release pipeline working, contributions need to follow the branch model and commit conventions below.
+
+### Branch model
+
+- Always open PRs against the `next` branch — not `main`. Stainless watches `next` to produce SDK
+  builds and the automated version-bump PR.
+- Typical flow:
+  1. Pull the latest `next` locally and branch off it.
+  2. Make and push your changes, then open a PR targeting `next`.
+  3. Get the PR reviewed and merged into `next`.
+  4. Stainless will open (or update) a release PR bumping the version — review and merge that PR
+     to ship to `main`/PyPI. A new release PR will not be cut while a previous one is still open,
+     so unblock pending release PRs before expecting a new one.
+- Do not merge generated code directly into `next` via PR. Let the generator produce those changes.
+- The `Validate PR base branch` CI check fails on PRs targeting `main` from non-automation accounts
+  and posts a comment with resolution steps. If you genuinely need to PR directly to `main` (e.g. an
+  urgent hotfix), add the `target-main` label to bypass the check.
+
+### Conventional commits
+
+Commit messages and PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/),
+because the changelog and release notes are derived from them. The `Validate PR title (Conventional Commits)`
+CI check enforces this on every PR. Common prefixes:
+
+- `feat(api): ...` — new functionality
+- `fix(types): ...` — bug fixes
+- `docs(readme): ...` — documentation-only changes (required for manual README/docs overrides to be
+  picked up by the generator)
+- `chore(internal): ...` — internal changes that don't affect users
+
 ## Modifying/Adding code
 
 Most of the SDK is generated code. Modifications to code will be persisted between generations, but may