@connectedxm/admin 6.30.1 → 6.31.1

package/.claude/skills/ship-to-prod/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: ship-to-prod
+description: Open a release PR from `staging` to `main` in this repo. Handles the full flow — gathers commits, pulls Linear ticket references from commit messages and the PRs that merged into staging, drafts a title and body that match the repo's PR template, picks reviewers, and (after the user confirms) creates the PR with `gh pr create`. Use this whenever the user says anything along the lines of "open a staging PR", "release staging", "ship staging to prod", "cut a release", "PR staging", "promote staging", "merge staging into main", or any variant of opening/preparing a PR between the staging and main branches. Prefer this skill over running `gh pr create` directly — the manual flow misses Linear references, the version-bump check, and reviewer conventions.
+---
+
+# Staging → Main release PR
+
+Use this when the user wants to open a release PR from `staging` into `main` in the `connectedxm/admin-sdk` repo (npm package `@connectedxm/admin`). Production is `main` here — pushing to `main` triggers `publish.yml`, which publishes both `@connectedxm/admin` and the generated `@connectedxm/admin-sdk` (typescript-axios output of `sdks/typescript/`) to npm. The backend repo uses `prod`, but this SDK ships from `main`.
+
+## What you're producing
+
+A draft PR (or, on confirmation, an actual PR via `gh pr create`) with:
+
+1. **Base/head**: base `main`, head `staging` — never invent a feature branch
+2. **Title** that reflects what's in the diff (see "Writing the title")
+3. **Body** matching `.github/pull_request_template.md`, with Linear refs harvested from commits AND from any sub-PRs they reference, plus the Semantic Versioning section ticked
+4. **Reviewers** drawn from the repo's collaborators (excluding the PR author)
+
+The user has asked to **always confirm before creating** the PR. Show the draft, wait for the go-ahead, then call `gh pr create`.
+
+## Workflow
+
+### 1. Sync and check there's something to ship
+
+```bash
+git fetch origin main staging
+git log --oneline origin/main..origin/staging
+```
+
+If the log is empty, tell the user `staging` has nothing ahead of `main` — there's no PR to open. Stop.
+
+If `staging` is behind `origin/staging` locally, that's fine — the PR is opened against the remote refs, not your working copy. But mention it so the user knows.
+
+### 2. Check the version bump (hard gate)
+
+`version-check.yml` rejects any PR to `main` whose `package.json` version isn't strictly greater than main's, in plain `x.y.z` semver (no pre-release tags, no build metadata).
+
+```bash
+git show origin/main:package.json | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).version"
+git show origin/staging:package.json | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).version"
+```
+
+Compare the two. If staging's version is **not** strictly greater than main's, stop and tell the user — they need to land a version bump on staging first (recent precedent: `chore: bump version to X.Y.Z` PRs into staging) before this release PR can pass CI. Don't open the PR; don't bump for them.
+
+If the bump looks right, note which kind it is (major/minor/patch) — you'll tick the matching box in the body's Semantic Versioning section.
+
+### 3. Gather the commits
+
+```bash
+git log origin/main..origin/staging --pretty=format:'%H%x09%s%x09%b%x1e'
+```
+
+The `%x1e` (ASCII record separator) lets you split multi-line commit bodies cleanly. You want the subject AND the body — Linear references like `closes ENG-1901` usually live in the body, not the subject.
+
+Skip merge commits whose subject starts with `Merge branch 'staging'` — they're noise from local merges, not a unit of work.
+
+### 4. Resolve sub-PRs referenced in commit subjects
+
+Squash-merged PRs leave a trail like `feat(accounts): expose tier on account responses (#561)`. The `(#NNNN)` is a real PR with its own body that often holds the Linear reference. Pull each one:
+
+```bash
+gh api repos/connectedxm/admin-sdk/pulls/<NNNN> --jq '{title, body}'
+```
+
+Do this for every `(#NNNN)` you find in the commit subjects in step 3. These bodies feed into the Linear extraction below — and sometimes into the PR description summary, when the squashed commit message is terse.
+
+### 5. Extract Linear ticket references
+
+Linear refs in this repo look like `[A-Z]{2,5}-\d+` — the dominant prefix is `ENG`, with `CXM` and others appearing occasionally. They appear as:
+
+- `closes ENG-1234`
+- `ref CXM-1901`
+- bare `[ENG-1913]` in PR titles, e.g. `[ENG-1913] ci: gate auto-approve on AUTO_APPROVE_USERS allowlist`
+
+**Important: don't confuse `(#561)` (a GitHub PR number) with `ENG-1234` (a Linear ticket).** Only the latter goes in the Linear Issues section.
+
+**`linear-check.yml` is a hard gate.** It runs on every PR to `main` and requires at least one literal `ENG-\d+` somewhere in the PR body. If you can only find `CXM-…` refs, the workflow will fail — flag this to the user before opening so they can decide whether to add an `ENG-…` ref or update the workflow.
+
+Collect refs from:
+
+- the body of every commit in step 3
+- the title and body of every sub-PR resolved in step 4
+
+**Only include refs you actually saw in those sources for this PR.** Don't carry refs over from prior staging→main PRs, recent conversation context, or memory of past releases — even if a ticket "feels relevant," it doesn't go in the list unless it's literally present in the commits/PRs you just gathered. Re-listing a ticket that was already shipped in a previous release is a real failure mode and confuses Linear's auto-close on merge.
+
+Dedupe. Preserve the verb the user wrote when possible — if a sub-PR said `closes ENG-1901`, your output should say `closes ENG-1901`, not `ref`. Only fall back to `ref` if the original said `ref` or no verb at all.
+
+### 6. Pick reviewers
+
+There's no CODEOWNERS file in this repo. Build the candidate list at runtime:
+
+```bash
+gh api repos/connectedxm/admin-sdk/collaborators \
+  --jq '[.[] | select(.permissions.push == true) | .login]'
+gh api user --jq '.login'   # you, the PR author — exclude from candidates
+```
+
+Use the unfiltered `collaborators` endpoint — do **not** add `?affiliation=direct`, because that excludes org admins (e.g., `swiftoO` is an admin and won't appear with the direct filter). The unfiltered endpoint plus a `permissions.push == true` jq filter gives you the right candidate set.
+
+Take everyone with push permission, drop the author. Default to requesting all of them. If the user said something specific about reviewers in their prompt ("just Tyler", "skip Spencer"), honor that and don't ask.
+
+If only one candidate remains, just use them — don't bother the user about it.
+
+### 7. Write the title
+
+Look at what's actually in the diff before reaching for a template. The right title depends on the shape of the changes.
+
+**One dominant change:** copy the conventional-commit subject from the main commit/PR. Example: `feat(accounts): expose tier and tags on account responses`.
+
+**Several unrelated changes:** use a short generic title like `Staging Fixes` or a noun phrase that captures the theme. Look at recent staging→main PRs (`gh pr list --base main --head staging --state merged --limit 10`) to match the house style — they oscillate between conventional-commit and short noun phrases, both are fine.
+
+**Version-bump-only releases.** When the only thing in the diff is `chore: bump version to X.Y.Z`, a short title like `Release X.Y.Z` is fine.
+
+Keep it under ~70 characters.
+
+### 8. Write the body
+
+Use this exact template — it matches `.github/pull_request_template.md`:
+
+```markdown
+### Description
+
+<2-4 sentence summary of what's shipping. Group by theme if there are several unrelated changes — bullet list is fine when that's clearer than prose. Lead with SDK-visible changes (new hooks, new fields on response/params types, new error codes, OpenAPI schema changes), since this PR triggers an npm publish of both `@connectedxm/admin` and the generated `@connectedxm/admin-sdk`.>
+
+### Linear Issues
+
+- closes ENG-1234
+- ref CXM-1901
+  <one line per ticket; use the verb the source used. Must include at least one ENG-#### or linear-check.yml will fail.>
+
+### Testing
+
+<Generated testing plan — see "Writing the testing plan" below. Do NOT use the template's default `I have manually tested the changes / New integration tests have been added` checkboxes; replace them with concrete steps grounded in the actual diff.>
+
+### Semantic Versioning
+
+Indicate the appropriate version bump for this PR:
+
+- [ ] Breaking changes - Major version bump
+- [ ] New features / improvements - Minor version bump
+- [ ] Bug fixes - Patch version bump
+```
+
+**Tick the Semantic Versioning box** that matches the actual version delta you noted in step 2 (`X.Y.0` → minor, `X.Y.Z` patch bump only → patch, major version bump → major). If multiple things shipped, tick the highest-impact box (one breaking change makes the whole release major).
+
+**Writing the testing plan.** Replace the template's default Testing checkboxes with a per-PR plan derived from what actually changed. The reviewer should be able to read the plan and know exactly what to verify before merging triggers the npm publish. Aim for 3–7 concrete checkbox items.
+
+Walk the file diff (`git diff --name-only origin/main..origin/staging`) and turn it into specific verification steps. This is a TypeScript SDK consumed by other apps (notably `admin-web`), so most verification happens via type-check + a smoke pass from a consumer. Note: this repo also generates a second SDK in `sdks/typescript/` from `openapi.json` via `npm run generate` / `npm run generate:sdks` — interface and param changes can affect what shows up there too.
+
+- **Query files** (`src/queries/<resource>/use*.ts`) → "Confirm `useGet*` returns the new field/shape; spot-check the query key and that 401/403/404/460/461 routes through `onNotAuthorized` / `onNotFound` / `onModuleForbidden`."
+- **Mutation files** (`src/mutations/<resource>/use*.ts`) → "Run the mutation from a consumer app and confirm the listed query keys invalidate / `SET_*_QUERY_DATA` updates as expected; on failure confirm `onMutationError` fires."
+- **Interface changes** (`src/interfaces.ts`) → "Run `npm run lint` and `npx tsc` (configured `noEmit`); `npm pack` the SDK and install into `admin-web` — confirm the new fields surface in IDE completions and `tsc` is clean on the consumer side. Run `npm run generate` and spot-check `openapi.json` if the change should appear in the generated SDK."
+- **Param/input shape changes** (`src/params.ts`) → "Confirm callers in `admin-web` still type-check against the new params; if a field became required, the consumer-side update needs to land before publish."
+- **`ConnectedXMProvider` / context changes** (`src/ConnectedXMProvider.tsx`, `src/hooks/useConnectedXM.ts`) → "Mount a consumer with the updated provider and confirm `adminApiParams`, `organizationId`, `getToken`, `getExecuteAs`, and the `onNotAuthorized` / `onModuleForbidden` / `onNotFound` / `onMutationError` callbacks still wire through."
+- **`AdminAPI` / axios changes** (`src/AdminAPI.ts`) → "Confirm `GetAdminAPI(params)` returns an axios instance with the expected `baseURL`, `organization`, `authorization`, `api-key`, and `executeAs` headers (when set)."
+- **OpenAPI generator changes** (`scripts/generate.ts`, `scripts/generate-sdks.ts`) → "Run `npm run generate` and inspect `openapi.json` for the expected diff; if the SDK output is in scope, run `npm run generate:sdks` and confirm `sdks/typescript/` regenerates cleanly. Note: the `staging` → `main` PR triggers `generate-openapi.yml`, which re-runs the generator on the PR branch."
+- **Index/barrel changes** (`src/index.ts`, per-folder `index.ts`) → "If files were added/moved, confirm `npm run exports` was run on staging (per `.cursor/rules/index-exports.mdc` — don't hand-edit). Then `npm run build` and inspect `dist/index.d.ts` to confirm the new symbols are exported."
+- **CI workflow changes** (`.github/workflows/`) → "Confirm `tests.yml`, `linear-check.yml`, `version-check.yml`, `publish.yml`, `approve.yml`, or `generate-openapi.yml` pass on this branch."
+- **Publish gate** → "After merge, confirm `publish.yml` runs cleanly on `main` and both `@connectedxm/admin@X.Y.Z` and the generated `@connectedxm/admin-sdk@X.Y.Z` are live on npm."
+
+Group related items where it tightens the plan. If a single domain dominates the diff (e.g., the whole PR is account/auth polish), it's fine to have all 3–7 items in that domain. If you genuinely cannot derive a plan from the diff (rare — usually means something's wrong with how you read the commits), fall back to the original checkbox pair, but flag this to the user when presenting the draft.
+
+Format as a markdown checklist:
+
+```markdown
+### Testing
+
+- [ ] Run `npm run lint` and `npm run build` and confirm both pass cleanly.
+- [ ] `npm pack` the SDK and install into an `admin-web` checkout — confirm `tsc` passes on the consumer with the new types.
+- [ ] On a staging consumer, exercise the affected mutation/query and confirm the new fields land in the cache.
+- [ ] Run `npm run generate` and confirm `openapi.json` reflects the interface/param diff (CI's `generate-openapi.yml` will also run this on the PR branch).
+- [ ] After merge, confirm `publish.yml` succeeds and both `@connectedxm/admin@X.Y.Z` and `@connectedxm/admin-sdk@X.Y.Z` appear on npm.
+```
+
+If there are zero Linear references, omit the bullet list and write `- (none)` under the Linear Issues heading rather than deleting the section — keeps the template recognizable. (But: `linear-check.yml` requires at least one `ENG-####` in the body, so this case will fail CI. Flag it to the user before opening.)
+
+### 9. Show the draft and wait
+
+Print the title, body, reviewer list, AND the version delta from step 2 back to the user, clearly labelled. Ask whether to create the PR as drafted, modify, or cancel. Don't run `gh pr create` until they've said yes.
+
+The reason for confirming: the title and body are interpretive — you're summarizing several commits' worth of work. The user knows things you don't (which change is the headline feature, which is incidental cleanup, whether the Semantic Versioning box is right, whether something is already covered by another ticket). Five seconds of their attention up front beats editing the PR after the fact — especially since merging this PR triggers an npm publish.
+
+### 10. Create the PR
+
+After confirmation, use a HEREDOC for the body so newlines and markdown survive:
+
+```bash
+gh pr create \
+  --base main \
+  --head staging \
+  --title "<title>" \
+  --reviewer "<comma,separated,logins>" \
+  --body "$(cat <<'EOF'
+<body here>
+EOF
+)"
+```
+
+Return the PR URL from the command output so the user can click straight to it.
+
+## Things to watch out for
+
+- **`main`, not `prod`.** This repo's production branch is `main` (the backend repo uses `prod`). Don't paste backend instincts here — `gh pr create --base prod` will fail.
+- **Merging this PR publishes two packages to npm.** `publish.yml` runs on push to `main` and publishes both `@connectedxm/admin` (the source SDK) and `@connectedxm/admin-sdk` (the typescript-axios output regenerated from `openapi.json`). There is no manual gate. Take the testing plan seriously.
+- **The version bump is a hard gate.** If staging's `package.json` version isn't strictly greater than main's in plain `x.y.z` semver, `version-check.yml` will fail. Don't open the PR until the bump is on staging.
+- **`linear-check.yml` requires `ENG-####` in the body.** A `CXM-####`-only body will fail CI. If you only found `CXM` refs, surface that to the user before opening.
+- **`generate-openapi.yml` runs on the staging→main PR.** It regenerates `openapi.json` from the source. If the PR branch's `openapi.json` is stale relative to the source, expect this workflow to push a regen commit or fail. Don't be surprised by the extra activity on the PR.
+- **Don't paste `<!-- CURSOR_SUMMARY -->` blocks** from sub-PR bodies into the new PR body. Those are auto-generated by the Cursor Bugbot reviewer and re-including them looks weird.
+- **Don't include the HTML comment placeholders** from the PR template (`<!-- A brief description -->`) in your output — replace them with real content.
+- **Keep the Semantic Versioning section.** Don't drop it from the body — the template explicitly includes it. Tick the box that matches the actual version bump.
+- **`closes` vs `ref`**: `closes` auto-closes the Linear ticket on merge to `main`. `ref` just links it. Preserve whichever the source commit/PR used. When in doubt, `ref` is the safer default — it doesn't change ticket state.
+- **Bot reviews are not human reviews.** Don't infer reviewer preferences from `github-actions` or `cursor` reviews on past PRs — those are automated. Look at human reviewers (`authorAssociation: MEMBER`) only.
+- **The author isn't a reviewer.** GitHub will reject `--reviewer <self>`. Always exclude `gh api user --jq '.login'` from the list.
+
+## Why this exists
+
+Opening these PRs by hand consistently misses Linear references buried in sub-PR bodies, drops the Semantic Versioning section, and either skips the version-bump check or has to back-patch it after CI fails. Because merging this PR auto-publishes two npm packages, the cost of a botched release is higher than for an app deploy — there's no easy "revert" once a version is live. Hitting the gh API once per sub-PR, comparing versions up front, and templating the body is mechanical work that's easy to get wrong when done manually but easy to get right in a script-shaped flow.

package/.claude/skills/ship-to-staging/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: ship-to-staging
+description: Open a feature PR from the current branch into `staging` in this repo. Handles the full flow — detects the current branch, gathers commits, extracts the Linear ticket reference from the branch name and commit messages, drafts a title and body that match the repo's PR template, picks reviewers, pushes the branch if needed, and (after the user confirms) creates the PR with `gh pr create`. Use this whenever the user says anything along the lines of "open a PR to staging", "ship this branch", "PR this feature", "submit this", "merge this into staging", "open a feature PR", "create the staging PR for this", or any variant of opening a PR from a feature branch into staging. Prefer this skill over running `gh pr create` directly — the manual flow misses Linear references and reviewer conventions.
+---
+
+# Feature → Staging PR
+
+Use this when the user wants to open a PR from a feature branch into `staging` in the `connectedxm/admin-sdk` repo (npm package `@connectedxm/admin`). Typical case: one Linear ticket per branch, branch named like `ENG-1804` or `feat/eng-1234-cool-thing`.
+
+For the staging→main release flow, use `ship-to-prod` instead. (Production is `main` in this repo, not `prod`.)
+
+## What you're producing
+
+A PR (after confirmation) with:
+
+1. **Base/head**: base `staging`, head is the current feature branch — never `staging` or `main`
+2. **Title** that reflects the work in the diff (usually the dominant commit's conventional-commit subject)
+3. **Body** matching `.github/pull_request_template.md`, with the Linear ref harvested from the branch name and commit messages
+4. **Reviewers** drawn from the repo's collaborators (excluding the PR author)
+
+The user has asked to **always confirm before creating** the PR. Show the draft, wait for the go-ahead, then push (if needed) and call `gh pr create`.
+
+## Workflow
+
+### 1. Identify the branch and check there's something to ship
+
+```bash
+git rev-parse --abbrev-ref HEAD
+git fetch origin staging
+```
+
+If the current branch is `staging` or `main`, stop and tell the user — they probably wanted `ship-to-prod`, or they need to check out the feature branch first.
+
+```bash
+git log --oneline origin/staging..HEAD
+```
+
+If the log is empty, tell the user the current branch has nothing ahead of `staging` — there's no PR to open. Stop.
+
+If the branch already has an open PR against staging, mention it (`gh pr list --head <branch> --base staging --state open`) and ask whether to add commits to that one or close it first. Don't open a duplicate.
+
+### 2. Check push state
+
+```bash
+git rev-parse --verify --quiet "origin/<branch>" && \
+  git log --oneline "origin/<branch>..HEAD" || echo "branch not on origin"
+```
+
+Three possible states — note which applies:
+
+- **Branch not on origin** — needs `git push -u origin <branch>` before `gh pr create` will work.
+- **Local commits ahead of `origin/<branch>`** — needs `git push` so the PR includes them.
+- **Up to date** — nothing to push.
+
+Don't push yet. Bundle the push with the PR-create step after the user confirms the draft (step 8).
+
+### 3. Gather the commits
+
+```bash
+git log origin/staging..HEAD --pretty=format:'%H%x09%s%x09%b%x1e'
+```
+
+The `%x1e` (ASCII record separator) lets you split multi-line commit bodies cleanly. You want the subject AND the body — Linear refs like `closes ENG-1901` typically live in the body.
+
+Skip merge commits (`Merge branch 'staging'`, `Merge pull request #...`) — they're noise on a feature branch.
+
+Feature branches generally don't have squashed sub-PRs (they ARE the sub-PR), so you can skip the sub-PR resolution step that `ship-to-prod` uses.
+
+### 4. Extract the Linear ticket reference
+
+Linear refs in this repo look like `[A-Z]{2,5}-\d+` — the dominant prefix is `ENG`. The PR template still shows `closes CXM-…` as a placeholder, but recent merged PRs and the `linear-check.yml` workflow both expect `ENG-\d+`. `CXM` and other prefixes appear occasionally; preserve whatever the source actually used. Note that branches in this repo are often named just by ticket ID (e.g. `ENG-1804`). Look in this order:
+
+1. **Branch name** — `ENG-1804`, `fix/eng-1886-deletion`, or `feat/cxm-1234-cool-thing` → extract `ENG-1804` / `ENG-1886` / `CXM-1234`. Pattern: `([a-zA-Z]{2,5}-\d+)` (case-insensitive — uppercase it).
+2. **Commit subjects and bodies** — `closes ENG-1886`, `ref CXM-1234`, or bare ticket IDs.
+
+For the verb:
+
+- If a commit explicitly used `closes ENG-XXXX` or `ref ENG-XXXX`, preserve that verb.
+- If the ref came only from the branch name, default to `closes` — a feature PR is the canonical place to close its ticket.
+- When in real doubt, `ref` is safer (doesn't change ticket state on merge).
+
+Dedupe. The common case is a single ticket; if you find more than one, list each on its own line.
+
+If you find zero refs, ask the user before proceeding — feature branches almost always have a ticket, and a missing ref usually means the branch was named differently than usual or the ticket was forgotten. Don't fabricate one.
+
+Note: `linear-check.yml` only runs on PRs targeting `main`, so a missing Linear ref won't block a staging PR from opening. Still ask — the ref needs to land somewhere on the branch before the staging→main release PR is opened.
+
+### 5. Pick reviewers
+
+Same logic as `ship-to-prod` — there's no CODEOWNERS file:
+
+```bash
+gh api repos/connectedxm/admin-sdk/collaborators \
+  --jq '[.[] | select(.permissions.push == true) | .login]'
+gh api user --jq '.login'   # exclude self
+```
+
+Use the unfiltered `collaborators` endpoint (NOT `?affiliation=direct`, which excludes org admins like `swiftoO`). Filter by `permissions.push == true`, drop the author.
+
+Default to requesting all of them. If the user said something specific in their prompt ("just Tyler", "skip Spencer"), honor that. If only one candidate remains, just use them.
+
+### 6. Write the title
+
+For a feature branch, the title is usually obvious — copy the dominant commit's conventional-commit subject. Examples that work well:
+
+- `feat(accounts): expose tier and tags on account responses`
+- `fix(events/passes): preserve query key when search arg changes`
+- `chore(ci): gate auto-approve on AUTO_APPROVE_USERS allowlist`
+
+If the branch has many small commits with no clear headline, fall back to a noun phrase that captures the change (`Image upload on activation`, `Activity hook cleanup`). Keep it under ~70 characters.
+
+Don't include the Linear ticket in the title — it goes in the body.
+
+### 7. Write the body
+
+Use this exact template — it matches `.github/pull_request_template.md`:
+
+```markdown
+### Description
+
+<2-4 sentence summary of what's shipping and why. Pull from the dominant commit body where it's well-written; otherwise synthesize from the diff. Lead with the SDK-visible behavior change (new hook, new field on a response/params type, new query key, etc.), then root cause / approach if relevant.>
+
+### Linear Issues
+
+- closes ENG-1886
+  <one line per ticket; preserve the verb from the source (or default to `closes` for branch-only refs)>
+
+### Testing
+
+<Generated testing plan — see "Writing the testing plan" below. Do NOT use the template's default `I have manually tested the changes / New integration tests have been added` checkboxes; replace them with concrete steps grounded in the actual diff.>
+
+### Semantic Versioning
+
+Indicate the appropriate version bump for this PR:
+
+- [ ] Breaking changes - Major version bump
+- [ ] New features / improvements - Minor version bump
+- [ ] Bug fixes - Patch version bump
+```
+
+**The Semantic Versioning section.** Keep this section in the body — the staging→main release PR re-uses the bumped version. Tick the box that matches the diff:
+
+- New required fields, removed/renamed exports, changed function signatures → **major**.
+- New optional fields on response/params interfaces, new hooks/queries/mutations, new WS event handlers → **minor**.
+- Bug fixes, internal refactors, validation tightening that doesn't break callers → **patch**.
+
+If the user has already bumped `package.json` on this branch, that decides it — match the box to the bump that's actually in the diff. The version itself is enforced on the staging→main PR by `version-check.yml`, not here.
+
+**Writing the testing plan.** A feature PR's testing plan is tighter than a release's — usually 2–5 specific items. Walk the file diff (`git diff --name-only origin/staging..HEAD`) and turn it into concrete verification steps. This is a TypeScript SDK consumed by other apps (notably `admin-web`), so most verification happens via type-check + a smoke pass from a consumer. Note: this repo also generates a second SDK in `sdks/typescript/` from `openapi.json` via `npm run generate` / `npm run generate:sdks` — interface and param changes can affect what shows up there too.
+
+- **Query files** (`src/queries/<resource>/use*.ts`) → "Confirm `useGet*` returns the new field/shape; spot-check the query key and that 401/403/404/460/461 routes through the right `onNotAuthorized` / `onNotFound` / `onModuleForbidden` handler."
+- **Mutation files** (`src/mutations/<resource>/use*.ts`) → "Run the mutation from a consumer app and confirm the listed query keys invalidate / `SET_*_QUERY_DATA` updates as expected; on failure confirm `onMutationError` fires."
+- **Interface changes** (`src/interfaces.ts`) → "Run `npm run lint` and `npx tsc` (configured `noEmit`) on the SDK; then `npm pack` and install the tarball into a consumer (`admin-web`) — confirm the new fields surface in IDE completions and `tsc` is clean. If the change should appear in the generated SDK too, run `npm run generate` and spot-check `openapi.json`."
+- **Param/input shape changes** (`src/params.ts`) → "Confirm callers in `admin-web` still type-check against the new params; if a field became required, flag the consumer-side update needed."
+- **`ConnectedXMProvider` / context changes** (`src/ConnectedXMProvider.tsx`, `src/hooks/useConnectedXM.ts`) → "Mount a consumer with the updated provider and confirm `adminApiParams`, `organizationId`, `getToken`, `getExecuteAs`, and the `onNotAuthorized` / `onModuleForbidden` / `onNotFound` / `onMutationError` callbacks still wire through."
+- **`AdminAPI` / axios changes** (`src/AdminAPI.ts`) → "Confirm `GetAdminAPI(params)` returns an axios instance with the expected `baseURL`, `organization`, `authorization`, `api-key`, and `executeAs` headers (when set)."
+- **OpenAPI generator changes** (`scripts/generate.ts`, `scripts/generate-sdks.ts`) → "Run `npm run generate` and inspect `openapi.json` for the expected diff; if the SDK output is in scope, run `npm run generate:sdks` and check `sdks/typescript/`."
+- **Index/barrel changes** (`src/index.ts`, per-folder `index.ts`) → "If you added or moved files, run `npm run exports` to regenerate barrels (per `.cursor/rules/index-exports.mdc` — don't hand-edit). Then `npm run build` and inspect `dist/index.d.ts` to confirm the new symbols are exported."
+- **CI workflow changes** (`.github/workflows/`) → "Confirm `tests.yml` / `linear-check.yml` / `version-check.yml` / `publish.yml` / `approve.yml` / `generate-openapi.yml` pass on this branch."
+- **Local smoke** (when changes affect runtime, not just types) → "Run `npm run local` to produce a `.tgz`, install into `admin-web` (or another consumer), and walk the affected screen."
+
+Format as a markdown checklist:
+
+```markdown
+### Testing
+
+- [ ] Run `npm run lint` and `npx tsc` and confirm both pass cleanly.
+- [ ] `npm pack` the SDK, install the tarball into `admin-web`, and confirm the new field surfaces on `useGet<Resource>` / `useUpdate<Resource>` types in IDE completions.
+- [ ] On a staging consumer, exercise the affected mutation — confirm it succeeds and the cache update / `SET_*_QUERY_DATA` reflects the new fields.
+- [ ] Confirm `tests.yml` passes on the next push.
+```
+
+If there are zero Linear references (you flagged this in step 4 and the user proceeded anyway), write `- (none)` under the Linear Issues heading rather than deleting the section.
+
+### 8. Show the draft and wait
+
+Print the title, body, reviewer list, AND the push state from step 2 back to the user, clearly labelled. If a push is needed, state explicitly that creating the PR will push first. Ask whether to proceed, modify, or cancel. Don't run `git push` or `gh pr create` until they've said yes.
+
+The reason for confirming: the title and body are interpretive — you're summarizing the work. The user knows things you don't (whether the description undersells the change, whether the testing plan is missing a non-obvious manual step, which Semantic Versioning box is right). Five seconds of their attention up front beats editing the PR after the fact.
+
+### 9. Push the branch (if needed) and create the PR
+
+After confirmation:
+
+```bash
+# Only if step 2 said the branch needed pushing:
+git push -u origin <branch>   # first push
+# OR
+git push                      # subsequent push
+
+# Then:
+gh pr create \
+  --base staging \
+  --head <branch> \
+  --title "<title>" \
+  --reviewer "<comma,separated,logins>" \
+  --body "$(cat <<'EOF'
+<body here>
+EOF
+)"
+```
+
+`gh pr create` picks up the current branch as `--head` automatically when you're on it, but pass `--head` explicitly to be safe (avoids surprises if HEAD has moved).
+
+Return the PR URL from the command output so the user can click straight to it.
+
+## Things to watch out for
+
+- **Don't paste `<!-- CURSOR_SUMMARY -->` blocks** from anywhere into the new PR body. Auto-generated by the Cursor Bugbot reviewer — re-including them looks weird.
+- **Don't include the HTML comment placeholders** from the PR template (`<!-- A brief description -->`) in your output — replace them with real content.
+- **Keep the Semantic Versioning section.** This repo's PR template has it for a reason — the staging→main release PR re-uses the bump that landed on staging. Don't drop it from the body.
+- **Don't bump `package.json` automatically.** Version bumps are landed deliberately (sometimes in their own PR, sometimes alongside a feature). If the user hasn't bumped, don't do it for them — flag it in the draft and let them decide. `version-check.yml` enforces the bump on the staging→main PR, not here.
+- **`closes` vs `ref`**: `closes` auto-closes the Linear ticket on merge. For a feature → staging PR, `closes` is usually correct since this branch IS the work that closes the ticket. Preserve whichever the source commit used; default to `closes` only when the ref came from the branch name alone.
+- **Don't fabricate Linear refs.** If the branch name and commits genuinely have no ticket, ask the user — don't guess from conversation context or memory of past tickets.
+- **The author isn't a reviewer.** GitHub will reject `--reviewer <self>`. Always exclude `gh api user --jq '.login'` from the list.
+- **Don't push without confirmation.** Pushing exposes work to the team and triggers CI (`tests.yml`). Bundle it with PR creation behind the user's go-ahead.
+
+## Why this exists
+
+Feature → staging PRs follow the same template as release PRs but with a much simpler input — a single branch, usually a single ticket. Doing it by hand consistently misses the Linear ref (especially when it lives in the branch name only), the testing plan defaults to the empty template checkboxes, the Semantic Versioning section gets dropped, and reviewers get inconsistent. Templating the body and harvesting refs from the branch name is mechanical work that's easy to get right in a script-shaped flow.

package/dist/index.d.cts

@@ -480,6 +480,7 @@ interface BaseActivity {
     status: keyof typeof ActivityStatus;
     featured: boolean;
     pinned: boolean;
+    pinnedExplore: boolean;
     giphyId: string | null;
     imageId: string | null;
     videoId: string | null;
@@ -4823,6 +4824,8 @@ interface ActivityCreateInputs {
     message: string;
     entities?: ActivityEntityInputs[] | null;
     featured?: boolean;
+    pinned?: boolean;
+    pinnedExplore?: boolean;
     imageId?: string | null;
     videoId?: string | null;
     eventId?: string | null;
@@ -4839,6 +4842,7 @@ interface ActivityUpdateInputs {
     moderation?: keyof typeof ModerationStatus | null;
     featured?: boolean;
     pinned?: boolean;
+    pinnedExplore?: boolean;
     imageId?: string | null;
     videoId?: string | null;
     meetingId?: string | null;

package/dist/index.d.ts

@@ -480,6 +480,7 @@ interface BaseActivity {
     status: keyof typeof ActivityStatus;
     featured: boolean;
     pinned: boolean;
+    pinnedExplore: boolean;
     giphyId: string | null;
     imageId: string | null;
     videoId: string | null;
@@ -4823,6 +4824,8 @@ interface ActivityCreateInputs {
     message: string;
     entities?: ActivityEntityInputs[] | null;
     featured?: boolean;
+    pinned?: boolean;
+    pinnedExplore?: boolean;
     imageId?: string | null;
     videoId?: string | null;
     eventId?: string | null;
@@ -4839,6 +4842,7 @@ interface ActivityUpdateInputs {
     moderation?: keyof typeof ModerationStatus | null;
     featured?: boolean;
     pinned?: boolean;
+    pinnedExplore?: boolean;
     imageId?: string | null;
     videoId?: string | null;
     meetingId?: string | null;

package/openapi.json

@@ -93033,11 +93033,12 @@
         "type": "string",
         "enum": [
           "admin",
-          "people",
+          "account",
+          "thread",
+          "content",
           "activity",
-          "banner",
-          "chat",
-          "content"
+          "event",
+          "activation"
         ]
       },
       "SupportTicketType": {
@@ -93897,6 +93898,18 @@
           },
           "passId": {
             "type": "string"
+          },
+          "imageId": {
+            "type": "string",
+            "nullable": true
+          },
+          "image": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/BaseImage"
+              }
+            ],
+            "nullable": true
           }
         },
         "required": [
@@ -93905,7 +93918,9 @@
           "eventActivationId",
           "eventActivation",
           "earnedPoints",
-          "passId"
+          "passId",
+          "imageId",
+          "image"
         ]
       },
       "ActivationCompletion": {
@@ -93984,6 +93999,9 @@
             ],
             "nullable": true
           },
+          "imageUpload": {
+            "type": "boolean"
+          },
           "_count": {
             "type": "object",
             "properties": {
@@ -94008,6 +94026,7 @@
           "accessLevel",
           "sortOrder",
           "survey",
+          "imageUpload",
           "_count"
         ]
       },
@@ -94144,6 +94163,9 @@
           "pinned": {
             "type": "boolean"
           },
+          "pinnedExplore": {
+            "type": "boolean"
+          },
           "giphyId": {
             "type": "string",
             "nullable": true
@@ -94217,6 +94239,7 @@
           "status",
           "featured",
           "pinned",
+          "pinnedExplore",
           "giphyId",
           "imageId",
           "videoId",
@@ -112733,6 +112756,12 @@
           "featured": {
             "type": "boolean"
           },
+          "pinned": {
+            "type": "boolean"
+          },
+          "pinnedExplore": {
+            "type": "boolean"
+          },
           "imageId": {
             "type": "string",
             "nullable": true
@@ -112802,6 +112831,9 @@
           "pinned": {
             "type": "boolean"
           },
+          "pinnedExplore": {
+            "type": "boolean"
+          },
           "imageId": {
             "type": "string",
             "nullable": true
@@ -113846,6 +113878,9 @@
               }
             ],
             "nullable": true
+          },
+          "imageUpload": {
+            "type": "boolean"
           }
         },
         "required": [
@@ -113949,6 +113984,9 @@
               }
             ],
             "nullable": true
+          },
+          "imageUpload": {
+            "type": "boolean"
           }
         }
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@connectedxm/admin",
-  "version": "6.30.1",
+  "version": "6.31.1",
   "description": "Admin API javascript SDK",
   "author": "ConnectedXM Inc.",
   "type": "module",