Merge pull request #14293 from meteor/3.4.1-preparation

Add AI skills for release management (changelog, version-bump, docs-gap)
2026-05-02 03:01:46 -04:00 · 2026-04-01 14:12:08 +02:00
parent 22d602a41e 6f4e4dd1b8
commit d131192559
12 changed files with 959 additions and 14 deletions
--- a/.github/skills/changelog/SKILL.md
+++ b/.github/skills/changelog/SKILL.md
@@ -103,6 +103,7 @@ N/A
 - Format: `## vX.Y.Z, YYYY-MM-DD`
 - Comma + space separator
 - Always H2
+- Update the date to the current date whenever the changelog is modified

 ### Highlights

@@ -203,6 +204,18 @@ meteor update --release <VERSION>

 ---

+## Branching Model & Comparison Baseline
+
+Meteor releases are prepared on **`release-<VERSION>`** branches (e.g., `release-3.4.1`). The main development branch is **`devel`**.
+
+- **Changelog scope** = all changes on `release-<VERSION>` that are not on `devel`
+- **PR base** = PRs merged with base `release-<VERSION>`
+- **Commit diff** = `git log devel..release-<VERSION>` or `git log devel..HEAD` when on the release branch
+
+When generating or updating a changelog, always compare against `devel` to determine what is new in the release. PRs merged into `devel` that were then merged into the release branch via a branch merge (e.g., `Merge branch 'devel' into release-X.Y`) are included — they are part of the release diff.
+
+---
+
 ## Generating a Changelog from PRs

 Use merged PRs targeting the release branch.
@@ -252,11 +265,27 @@ When the changelog file already exists with content:
    * **Features** — new APIs, new packages, new capabilities
    * **Improvements** — enhancements, optimizations, DX upgrades to existing behavior
    * **Fixes** — bug fixes, correctness patches
-* Exclude:
-    * Release tooling only
-    * Docs-only PRs
-    * CI/test-only PRs
-    * Dependabot PRs unless user-facing
+
+### Inclusion & Exclusion Rules
+
+**Include only PRs that touch release-relevant directories:**
+
+* `tools/` — CLI and build system
+* `packages/` — core Meteor packages
+* `npm-packages/` — published `@meteorjs/*` packages
+* `scripts/` — dev bundle build scripts (e.g., Node.js version bumps)
+
+A PR that touches files **only** outside these directories is not a release change and must be excluded from the changelog.
+
+**Exclude PRs that are:**
+
+* Release tooling only (e.g., changelog generation, version bumps)
+* Docs-only — touching only `docs/`, `v3-docs/`, `guide/`, or markdown files outside release directories
+* CI/test-infrastructure-only — touching only `.github/workflows/`, test harness setup, or E2E infrastructure without changing runtime behavior
+* Dependabot PRs unless they bump a dependency that ships in the Meteor release (e.g., Node.js upgrade)
+* Internal refactors with no user-facing impact (e.g., renaming internal variables, reformatting)
+
+**When a PR touches both release and non-release directories**, include it — the release-relevant changes take priority for categorization.

 ### Breaking Change Detection

--- a/.github/skills/docs-gap/SKILL.md
+++ b/.github/skills/docs-gap/SKILL.md
@@ -0,0 +1,273 @@
+---
+name: docs-gap
+description: Use when analyzing release branch changes for missing user-facing documentation. Compares the release branch against devel, filters for user-facing changes, scans v3-docs/docs/ for coverage, and produces a gap report (.md file) with prioritized documentation opportunities. Does NOT write documentation — only identifies gaps and outputs a plan for later action.
+---
+
+# Documentation Gap Analysis
+
+Analyze release changes and identify missing user-facing documentation. Produces a gap report as a `.md` file for later action — does **not** write the documentation itself.
+
+---
+
+## Branching Model
+
+Releases are prepared on **`release-<VERSION>`** branches. The main development branch is **`devel`**.
+
+- **Change scope** = all changes on `release-<VERSION>` that are not on `devel`
+- Always compare against `devel` to determine what is new in the release
+- Use `git log devel..HEAD` when on the release branch
+
+This is the same branching model used by the [changelog](../changelog/SKILL.md) and [version-bump](../version-bump/SKILL.md) skills.
+
+---
+
+## Step 1: Gather Release Changes
+
+Fetch merged PRs targeting the release branch:
+
+**Primary — `gh` CLI:**
+
+```bash
+gh pr list --repo meteor/meteor \
+  --base release-<VERSION> \
+  --state merged \
+  --limit 200 \
+  --json number,title,labels,author,body,url
+```
+
+**Fallback — git log:**
+
+```bash
+git log --oneline devel..HEAD --merges | grep -oP '#\K[0-9]+'
+```
+
+Then fetch details per PR with `gh pr view`.
+
+---
+
+## Step 2: Filter to Release-Relevant Changes
+
+Apply the same inclusion rules as the changelog skill.
+
+**Include only PRs that touch:**
+
+* `tools/` — CLI and build system
+* `packages/` — core Meteor packages
+* `npm-packages/` — published `@meteorjs/*` packages
+* `scripts/` — dev bundle build scripts
+
+**Exclude PRs that are:**
+
+* Docs-only (touching only `docs/`, `v3-docs/`, `guide/`)
+* CI/test-infrastructure-only (`.github/workflows/`, E2E harness)
+* Release tooling only (version bumps, changelog generation)
+* Dependabot PRs unless they bump a user-visible dependency
+* Internal refactors with no user-facing impact
+
+---
+
+## Step 3: Classify Changes for Documentation Potential
+
+Not all release changes need documentation. Classify each included PR:
+
+### High Priority (likely needs docs)
+
+| Change Type | Signal | Expected Doc Section |
+|-------------|--------|---------------------|
+| New package | New `packages/*/package.js` created | `packages/` — new article |
+| New CLI command or option | Changes to `tools/cli/commands.js` adding new commands/flags | `cli/` — update or new section |
+| New skeleton or template | New entries in `tools/static-assets/` | `about/` — getting started update |
+| New integration or bundler feature | Changes to `packages/rspack/`, `packages/tools-core/`, `npm-packages/meteor-rspack/` | `about/modern-build-stack/` — update or new article |
+| Breaking change | PR title/body mentions "breaking", "removed", "renamed" | Relevant section + migration note |
+
+### Medium Priority (may need docs)
+
+| Change Type | Signal | Expected Doc Section |
+|-------------|--------|---------------------|
+| New feature in existing package | New exports, new methods, new options | `packages/` — update existing article |
+| Behavior change | Changed defaults, new error messages | `packages/` or `troubleshooting/` |
+| Performance improvement (user-actionable) | New config option or recommended pattern | `performance/` |
+
+### Low Priority (usually no docs needed)
+
+| Change Type | Signal | Expected Doc Section |
+|-------------|--------|---------------------|
+| Bug fix | Fix to existing behavior, no API change | Usually none — unless the bug was a known issue in `troubleshooting/` |
+| Internal optimization | No user-visible change | None |
+| Type definition fix | `.d.ts` changes only | None |
+
+**Skip low-priority items** in the gap report unless they fix a documented known issue.
+
+---
+
+## Step 4: Scan Existing Documentation for Coverage
+
+For each high and medium priority change, search `v3-docs/docs/` for existing coverage.
+
+### Search Strategy
+
+For each PR, extract keywords from:
+- PR title (e.g., "Rspack CSS delegation", "TypeScript Tailwind skeleton")
+- Package name (e.g., `accounts-base`, `rspack`)
+- Feature name (e.g., `swc.config.ts`, `getUserIdsInRoleAsync`)
+
+Then search:
+
+```bash
+# Search by feature keyword
+grep -rl "<keyword>" v3-docs/docs/ --include="*.md"
+
+# Search by package name
+grep -rl "<package-name>" v3-docs/docs/ --include="*.md"
+```
+
+### Documentation Scope (In-Scope Sections)
+
+Only scan and report on **user-facing** documentation sections:
+
+| Section | Path | What It Covers |
+|---------|------|---------------|
+| About / Quick Start | `v3-docs/docs/about/` | Getting started, install, concepts, modern build stack |
+| Packages | `v3-docs/docs/packages/` | Official package guides |
+| CLI | `v3-docs/docs/cli/` | Command-line reference |
+| Tutorials | `v3-docs/docs/tutorials/` | Step-by-step framework guides |
+| Troubleshooting | `v3-docs/docs/troubleshooting/` | Common issues and solutions |
+| Performance | `v3-docs/docs/performance/` | Optimization guides |
+| Community Packages | `v3-docs/docs/community-packages/` | Third-party package docs |
+
+### Out-of-Scope Sections (Do NOT Report Gaps For)
+
+| Section | Path | Why Excluded |
+|---------|------|-------------|
+| API Reference | `v3-docs/docs/api/` | Auto-generated from JSDoc — separate concern |
+| Generators | `v3-docs/docs/generators/` | Build tooling for the doc site |
+| JSDoc | `v3-docs/docs/jsdoc/` | JSDoc configuration |
+| Components | `v3-docs/docs/components/` | Vue components for doc site |
+| Data / Search / Public | `v3-docs/docs/data/`, `search/`, `public/` | Site infrastructure |
+
+### Coverage Assessment
+
+For each change, classify as:
+
+- **Documented** — existing docs cover the feature adequately (file path + relevant section)
+- **Partially documented** — feature is mentioned but not fully explained (file path + what's missing)
+- **Not documented** — no docs found for this change
+
+---
+
+## Step 5: Produce the Gap Report
+
+Output a `.md` file at `docs/plans/<DATE>-docs-gap-<VERSION>.md` with this structure:
+
+````markdown
+# Documentation Gap Report: v<VERSION>
+
+**Generated:** <DATE>
+**Branch:** release-<VERSION> vs devel
+**PRs analyzed:** <COUNT>
+**Gaps found:** <COUNT>
+
+---
+
+## Already Documented
+
+Changes that have adequate documentation coverage.
+
+| PR | Change | Doc File | Notes |
+|----|--------|----------|-------|
+| [PR#NNN](url) | Description | `v3-docs/docs/path/file.md` | Covered in section X |
+
+---
+
+## Partially Documented
+
+Changes mentioned in docs but needing updates.
+
+| PR | Change | Doc File | What's Missing |
+|----|--------|----------|---------------|
+| [PR#NNN](url) | Description | `v3-docs/docs/path/file.md` | Missing: new option X, updated example |
+
+---
+
+## Not Documented
+
+Changes with no corresponding documentation.
+
+### High Priority
+
+| PR | Change | Suggested Action |
+|----|--------|-----------------|
+| [PR#NNN](url) | Description | Create `v3-docs/docs/section/file.md` — describe X for end users |
+
+### Medium Priority
+
+| PR | Change | Suggested Action |
+|----|--------|-----------------|
+| [PR#NNN](url) | Description | Update `v3-docs/docs/section/file.md` — add section about Y |
+
+---
+
+## Summary
+
+- **Total user-facing changes:** N
+- **Documented:** N
+- **Partially documented:** N
+- **Not documented:** N (high: N, medium: N)
+````
+
+---
+
+## Prioritization
+
+Rank gaps in this order:
+
+1. **New features / new packages** — users cannot discover these without docs
+2. **Breaking changes** — users need migration guidance
+3. **New CLI commands/options** — users need to know they exist
+4. **New integrations / build features** — expanding ecosystem
+5. **Behavior changes** — users may be surprised
+6. **Performance improvements** — only if user-actionable (e.g., new config)
+
+Bug fixes and internal optimizations generally do not need documentation.
+
+---
+
+## Writing Guidelines for Suggested Actions
+
+When describing what documentation to write in the gap report, keep suggestions **user-friendly**:
+
+**Do:**
+- Frame from the user's perspective ("How to use X", "Getting started with Y")
+- Suggest practical examples and code snippets
+- Reference existing doc patterns in the same section
+- Suggest updating existing articles before creating new ones
+
+**Don't:**
+- Suggest documenting internal implementation details
+- Suggest documenting private APIs or internal methods
+- Frame documentation as technical specs
+- Suggest documentation for changes only relevant to Meteor contributors
+
+### Preserving Style and Integration
+
+When the gap report is used to write documentation, the new content must feel native to the existing docs — not bolted on. Each suggested action in the report should include guidance on how to integrate cleanly:
+
+- **Read the target file first.** Before suggesting where to add content, note the writing style, heading levels, use of components (e.g., `<ApiBox>`), code example format, and tone.
+- **Match the surrounding pattern.** If nearby sections use a brief intro paragraph followed by a code block and a tip, follow the same structure. If they use bullet lists, use bullet lists.
+- **Find the right spot.** Place new content next to related existing content — not appended at the end. For example, a new API method goes next to similar methods; a new framework section goes alongside the other framework sections.
+- **Use the same components.** If the doc uses `<ApiBox>`, `:::warning`, `:::info`, code groups, or other VitePress/Vue components, use them for new content too.
+- **Preserve categorization.** New package docs go in `packages/`, new CLI options go in `cli/`, new getting-started content goes in `about/`. Do not create new top-level sections unless no existing section fits.
+
+---
+
+## Review Checklist
+
+Before finalizing the gap report:
+
+- [ ] All high and medium priority PRs have been assessed
+- [ ] Each "Not Documented" item has a concrete suggested action (file path + description)
+- [ ] "Partially Documented" items specify what exactly is missing
+- [ ] No low-priority items (pure bug fixes, internal refactors) are included unless they fix a documented known issue
+- [ ] All doc file paths in "Already Documented" are verified to exist
+- [ ] Suggested new articles align with the existing doc structure and naming conventions
+- [ ] Gap report is saved to `docs/plans/<DATE>-docs-gap-<VERSION>.md`
--- a/.github/skills/version-bump/SKILL.md
+++ b/.github/skills/version-bump/SKILL.md
@@ -0,0 +1,428 @@
+---
+name: version-bump
+description: Use when bumping Meteor package versions for beta, RC, or official releases. Covers the two version schemes (meteor-tool vs all other packages), the update-semver automation tool, manual files the tool does not handle, and the full lifecycle from beta through official release. Applies to packages/*/package.js, scripts/admin/, npm-packages/meteor-installer/, and .meteor/versions in test apps.
+---
+
+# Meteor Version Bump Rules
+
+Guidelines for bumping package versions across the Meteor repository for beta, RC, and official releases.
+
+---
+
+## Branching Model
+
+Releases are prepared on **`release-<VERSION>`** branches (e.g., `release-3.4.1`). The main development branch is **`devel`**.
+
+- **Changed packages** = packages with diffs between `devel` and the release branch
+- Always compare against `devel` to determine which packages need version bumps
+- The release branch name determines the **track number** used in prerelease suffixes
+
+### Track Number Derivation
+
+The track number is the release branch digits concatenated (dots removed):
+
+| Branch | Track Number |
+|--------|-------------|
+| `release-3.4` | `340` |
+| `release-3.4.1` | `341` |
+| `release-3.5` | `350` |
+
+### Detecting Changed Packages
+
+```bash
+git diff devel --dirstat=files -- ./packages/
+```
+
+This is the same comparison used by the `update-semver` automation tool via `scripts/admin/update-semver/get-diff.sh`.
+
+---
+
+## Prerequisites
+
+Before bumping versions:
+
+1. You must be on a `release-*` branch
+2. All changes intended for the release must be merged
+3. Confirm the release type with the user: **beta**, **RC**, or **official**
+
+---
+
+## Version Format Reference
+
+### Two Distinct Schemes
+
+**1. `meteor-tool`** — simple semver prerelease (no track number):
+
+| Stage | Format | Example |
+|-------|--------|---------|
+| Beta | `X.Y.Z-beta.N` | `3.4.0-beta.0` |
+| RC | `X.Y.Z-rc.N` | `3.4.0-rc.0` |
+| Official | `X.Y.Z` | `3.4.0` |
+
+**2. All other packages** — encode the track number in the prerelease tag:
+
+| Stage | Format | Example (track `340`) |
+|-------|--------|-----------------------|
+| Beta | `X.Y.Z-beta<TRACK>.N` | `3.2.0-beta340.0` |
+| RC | `X.Y.Z-rc<TRACK>.N` | `3.2.0-rc340.0` |
+| Official | `X.Y.Z` | `3.2.0` |
+
+### Version Transitions
+
+| Transition | meteor-tool | Other packages |
+|------------|------------|----------------|
+| Stable to first beta | `3.3.1` -> `3.4.0-beta.0` | `3.1.2` -> `3.2.0-beta340.0` |
+| Beta to next beta | `3.4.0-beta.0` -> `3.4.0-beta.1` | `3.2.0-beta340.0` -> `3.2.0-beta340.1` |
+| Beta to first RC | `3.4.0-beta.14` -> `3.4.0-rc.0` | `3.2.0-beta340.14` -> `3.2.0-rc340.0` |
+| RC to next RC | `3.4.0-rc.0` -> `3.4.0-rc.1` | `3.2.0-rc340.0` -> `3.2.0-rc340.1` |
+| RC to official | `3.4.0-rc.4` -> `3.4.0` | `3.2.0-rc340.4` -> `3.2.0` |
+
+---
+
+## Version Bump Magnitude
+
+When creating the **first beta** for a release, each changed package needs a version bump from its current stable version. The magnitude depends on the nature of changes.
+
+For subsequent betas, RCs, and official releases, the base version (`X.Y.Z`) stays the same — only the prerelease suffix changes.
+
+### Magnitude Rules
+
+| Magnitude | When to use | Examples |
+|-----------|------------|---------|
+| **Patch** | Bug fixes, performance improvements, type fixes, internal refactors with no API changes | Fix passwordValidator precedence, remove redundant await, TypeScript type corrections |
+| **Minor** | New public APIs, new exported functions/methods, new user-facing features or capabilities | New `getUserIdsInRoleAsync` method, new CSS auto-delegation feature, new test assertion methods |
+| **Major** | Breaking changes, removed APIs, renamed exports, changed function signatures | Removed public method, renamed package export, async migration of sync API |
+
+### How to Assess Each Package
+
+For each changed package, Claude should analyze the diff to determine the bump magnitude:
+
+```bash
+git diff devel -- packages/<name>/
+```
+
+**Check for minor bump signals:**
+- New functions or methods exported in `package.js` (`api.export`, `api.addFiles` for new files)
+- New public methods added to existing classes (e.g., new assertion methods, new query helpers)
+- New configuration options or capabilities that users can opt into
+- Significant new features even without new exports (e.g., new bundler capabilities)
+
+**Check for patch bump signals:**
+- Changes only to existing function bodies (bug fixes, optimizations)
+- TypeScript type corrections (`.d.ts` changes only)
+- Removed redundant code with no behavior change
+- Test-only changes alongside minor runtime fixes
+- Documentation or JSDoc updates
+
+**Check for major bump signals:**
+- Removed or renamed exports in `package.js`
+- Changed function signatures (new required parameters, changed return types)
+- Removed public methods from classes
+- Behavior changes that could break existing user code
+
+### Presenting the Decision
+
+When proposing version bumps to the user, always present a table with the **reason** for each bump decision:
+
+```markdown
+| Package | Current | Bump | New Version | Reason |
+|---------|---------|------|-------------|--------|
+| roles | 1.0.2 | minor | 1.1.0-betaXXX.0 | **New public API:** `getUserIdsInRoleAsync` added |
+| webapp | 2.1.1 | patch | 2.1.2-betaXXX.0 | Removed Vary header — bug fix, no new APIs |
+```
+
+Always get user confirmation before applying the bumps.
+
+### Build Plugin Cascading Rule
+
+When a package in the **build plugin chain** is bumped, its dependent build plugins must also be bumped — even if they have no code changes. This is because build plugins compile user code, and a change in an upstream compiler dependency can affect the compiled output.
+
+**The build plugin chain:**
+
+```
+babel-compiler
+├── ecmascript      (registerBuildPlugin, uses babel-compiler)
+├── typescript       (registerBuildPlugin, uses babel-compiler)
+└── minifier-js      (registerBuildPlugin, uses babel-compiler)
+```
+
+**Rule:** If `babel-compiler` is in the bump list, also bump `ecmascript`, `typescript`, and `minifier-js` (patch, unless they have their own changes warranting a higher bump).
+
+This rule applies only to build plugin dependencies (`registerBuildPlugin` + `api.use` of the upstream package). It does **not** apply to:
+- Umbrella/wrapper packages that `api.imply` a bumped package (e.g., `ddp` implying `ddp-server`)
+- The `accounts-*` family that implies `accounts-base`
+- Packages that only use a bumped package at runtime via `api.use`
+
+When presenting the bump table, mark cascading bumps clearly:
+
+```markdown
+| Package | Current | Bump | New Version | Reason |
+|---------|---------|------|-------------|--------|
+| babel-compiler | 7.13.0 | patch | 7.13.1-betaXXX.0 | Bug fix in compilation |
+| typescript | 5.9.3 | patch | 5.9.4-betaXXX.0 | **Cascade:** depends on babel-compiler (build plugin) |
+| ecmascript | 0.17.0 | patch | 0.17.1-betaXXX.0 | **Cascade:** depends on babel-compiler (build plugin) |
+| minifier-js | 3.1.0 | patch | 3.1.1-betaXXX.0 | **Cascade:** depends on babel-compiler (build plugin) |
+```
+
+---
+
+## Files Touched Per Release Type
+
+| File | Beta | RC | Official |
+|------|------|----|----------|
+| `packages/*/package.js` | Yes | Yes | Yes |
+| `scripts/admin/meteor-release-experimental.json` | Yes | Yes | No |
+| `scripts/admin/meteor-release-official.json` | No | No | Yes |
+| `.meteor/versions` in test apps | Yes | Yes | Yes |
+| `npm-packages/meteor-installer/config.js` | No | No | Yes |
+| `npm-packages/meteor-installer/package.json` + lock | No | No | Yes |
+| `v3-docs/` (changelog, docs with version refs) | Yes | Yes | Yes |
+
+---
+
+## Preferred Approach: AI-Driven Analysis
+
+Claude should perform the version bump process directly rather than relying on the `update-semver` script. The AI approach is preferred because:
+
+1. **Magnitude decisions require context** — the script defaults everything to patch, missing minor/major bumps for new APIs or breaking changes
+2. **Branch name dependency** — the script requires being on a `release-*` branch and will fail on preparation branches
+3. **Incomplete coverage** — the script only handles `packages/*/package.js`, not release files, `.meteor/versions`, npm installer, or docs
+4. **Transparency** — AI analysis shows reasoning for each bump decision, making review easier
+
+### AI Workflow
+
+1. Detect changed packages: `git diff devel --dirstat=files -- ./packages/`
+2. For each package, read the diff and current version from `package.js`
+3. Classify the bump magnitude (patch/minor/major) based on change analysis
+4. Present the full table with reasons to the user for confirmation
+5. Apply all `package.js` version edits
+6. Handle the manual files (release JSON, `.meteor/versions`, etc.)
+
+### Deriving the Version
+
+Given a current stable version and the release branch track number:
+
+- **Patch bump beta:** `X.Y.Z` → `X.Y.(Z+1)-beta<TRACK>.0`
+- **Minor bump beta:** `X.Y.Z` → `X.(Y+1).0-beta<TRACK>.0`
+- **Major bump beta:** `X.Y.Z` → `(X+1).0.0-beta<TRACK>.0`
+- **meteor-tool:** same logic but suffix is `-beta.0` (no track number)
+
+---
+
+## Fallback: `update-semver` Script
+
+Located at `scripts/admin/update-semver/`. Use only when on a `release-*` branch and a quick default-patch bump is acceptable.
+
+**Limitations:**
+- Requires `release-*` branch name (fails on other branches)
+- Defaults all packages to patch (no magnitude analysis)
+- Only updates `packages/*/package.js` — does not touch release files, `.meteor/versions`, npm installer, or docs
+
+### Usage
+
+```bash
+cd scripts/admin/update-semver
+
+# Auto-bump all changed packages for beta (all patch)
+npm run bump-experimental-beta
+
+# Auto-bump all changed packages for RC
+npm run bump-experimental-rc
+
+# Bump specific packages with specific magnitudes
+node index.js accounts-password.minor babel-compiler.minor
+```
+
+---
+
+## Release Type: Beta
+
+### Step 1: Analyze and bump package versions
+
+1. Detect changed packages: `git diff devel --dirstat=files -- ./packages/`
+2. For each changed package, analyze the diff to determine patch/minor/major
+3. Present the bump table with reasons to the user
+4. After confirmation, edit each `packages/*/package.js` `Package.describe` version
+5. Apply the correct beta suffix: `X.Y.Z-beta<TRACK>.0` for packages, `X.Y.Z-beta.0` for meteor-tool
+
+### Step 2: Update experimental release file
+
+Edit `scripts/admin/meteor-release-experimental.json`:
+
+```json
+{
+  "track": "METEOR",
+  "version": "X.Y-beta.N",
+  "recommended": false,
+  "official": false,
+  "description": "Meteor experimental release"
+}
+```
+
+- Version format: `X.Y-beta.N` (short form, no patch component)
+- Both `recommended` and `official` are `false`
+
+### Step 3: Update `.meteor/versions` in test apps
+
+Known locations under `tools/modern-tests/apps/` (e.g., `solid`, `svelte`, `vue`):
+
+```bash
+find tools/ -name "versions" -path "*/.meteor/*"
+```
+
+In each file, update only packages that are at prerelease versions (or newly added packages). Leave already-stable package versions untouched.
+
+> **Note:** The set of packages at prerelease versions can grow between beta and RC as more changes are merged to the release branch.
+
+### Step 4: Update documentation and changelog
+
+Use the [changelog skill](../changelog/SKILL.md) to create or update the changelog entry at `v3-docs/docs/generators/changelog/versions/<VERSION>.md`.
+
+Update the version header date to the current date. Update the **Bumped Meteor Packages** section in the changelog with all packages that were bumped. Use the version that matches the current release stage — beta versions for beta releases, RC versions for RC releases, and final versions (no prerelease suffix) for official releases. Format: one package per line, `name@version`. Include `meteor-tool@<version>` when applicable.
+
+Update any documentation files that reference specific package versions (e.g., rspack installation commands).
+
+---
+
+## Release Type: RC (Release Candidate)
+
+### Step 1: Bump package versions
+
+Update the prerelease suffix in each `packages/*/package.js` from beta to RC (or increment RC):
+
+The transitions are:
+- `beta<TRACK>.N` -> `rc<TRACK>.0` (first RC)
+- `rc<TRACK>.N` -> `rc<TRACK>.N+1` (subsequent RCs)
+- `beta.N` -> `rc.0` (meteor-tool, first RC)
+- `rc.N` -> `rc.N+1` (meteor-tool, subsequent RCs)
+
+### Step 2: Update experimental release file
+
+Edit `scripts/admin/meteor-release-experimental.json`:
+
+```json
+{
+  "track": "METEOR",
+  "version": "X.Y-rc.N",
+  "recommended": false,
+  "official": false,
+  "description": "Meteor experimental release"
+}
+```
+
+### Step 3: Update `.meteor/versions` in test apps
+
+Same rule as beta: update only packages at prerelease versions.
+
+### Step 4: Update documentation and changelog
+
+Update the version header date to the current date. Update changelog and any docs referencing RC versions. Update the **Bumped Meteor Packages** section with the current RC versions.
+
+---
+
+## Release Type: Official
+
+Official releases follow a **two-step process** (typically two separate commits).
+
+### Commit 1: Packages and release config
+
+#### Step 1: Strip prerelease suffixes from all packages
+
+For every `packages/*/package.js` that has an RC version, remove the `-rc<TRACK>.N` or `-rc.N` suffix:
+
+- `3.2.0-rc340.4` -> `3.2.0`
+- `3.4.0-rc.4` -> `3.4.0` (meteor-tool)
+
+#### Step 2: Update official release file
+
+Edit `scripts/admin/meteor-release-official.json`:
+
+```json
+{
+  "track": "METEOR",
+  "version": "X.Y",
+  "recommended": false,
+  "official": true,
+  "description": "The Official Meteor Distribution"
+}
+```
+
+- For `.0` releases: short form `X.Y` (e.g., `3.4`)
+- For patch releases: `X.Y.Z` (e.g., `3.4.1`)
+- `official` must be `true`
+
+#### Step 3: Update `.meteor/versions` in test apps
+
+Strip prerelease suffixes from packages that were at RC versions. Leave stable versions untouched.
+
+#### Step 4: Update changelog and docs
+
+- Set the release date in the changelog
+- Replace all RC version references with final versions
+- Update the **Bumped Meteor Packages** section with final versions (no prerelease suffixes)
+- Update `v3-docs/docs/history.md` with the full release entry
+
+### Commit 2: npm installer
+
+This is a **separate commit** after the packages commit.
+
+#### Step 1: Update installer config
+
+Edit `npm-packages/meteor-installer/config.js`:
+
+```js
+const METEOR_LATEST_VERSION = 'X.Y';
+```
+
+- For `.0` releases: short form without patch (e.g., `'3.4'`)
+- For patch releases: full version (e.g., `'3.4.1'`, `'3.3.2'`)
+
+#### Step 2: Update installer package.json
+
+Edit `npm-packages/meteor-installer/package.json`:
+
+```json
+{
+  "version": "X.Y.Z"
+}
+```
+
+Full semver form required by npm (e.g., `"3.4.0"`, `"3.4.1"`).
+
+#### Step 3: Update package-lock.json
+
+Run `npm install` in `npm-packages/meteor-installer/` to regenerate the lock file, or manually update the version field.
+
+---
+
+## Checklist
+
+### Beta Release
+
+- [ ] Detect changed packages (`git diff devel --dirstat=files -- ./packages/`)
+- [ ] Analyze each package diff and determine bump magnitude (patch/minor/major)
+- [ ] Present bump table with reasons to user and get confirmation
+- [ ] Apply version bumps to all `packages/*/package.js`
+- [ ] Update `scripts/admin/meteor-release-experimental.json` version to `X.Y.Z-beta.N`
+- [ ] Update `.meteor/versions` in test apps (prerelease packages only)
+- [ ] Update changelog at `v3-docs/docs/generators/changelog/versions/`
+- [ ] Update docs referencing package versions
+
+### RC Release
+
+- [ ] Update prerelease suffix from beta to RC (or increment RC) in all `packages/*/package.js`
+- [ ] Update `scripts/admin/meteor-release-experimental.json` version to `X.Y.Z-rc.N`
+- [ ] Update `.meteor/versions` in test apps (prerelease packages only)
+- [ ] Update changelog
+- [ ] Update docs referencing package versions
+
+### Official Release
+
+- [ ] Strip RC suffixes from all `packages/*/package.js`
+- [ ] Update `scripts/admin/meteor-release-official.json` (version `X.Y`, `official: true`)
+- [ ] Update `.meteor/versions` in test apps (strip prerelease suffixes)
+- [ ] Finalize changelog (set date, replace RC versions with final)
+- [ ] Update `v3-docs/docs/history.md`
+- [ ] **Separate commit:** Update `npm-packages/meteor-installer/config.js` (`'X.Y'`)
+- [ ] **Separate commit:** Update `npm-packages/meteor-installer/package.json` (`"X.Y.0"`)
+- [ ] **Separate commit:** Update `npm-packages/meteor-installer/package-lock.json`
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -51,6 +51,8 @@ Load these for detailed context on specific topics:
 | [e2e-coverage](.github/skills/e2e-coverage/SKILL.md) | Updating the E2E test coverage report when apps/skeletons change |
 | [ai-context](.github/skills/ai-context/SKILL.md) | Creating, updating, or maintaining AI documentation files |
 | [changelog](.github/skills/changelog/SKILL.md) | Writing, reviewing, or editing changelog entries for releases |
+| [version-bump](.github/skills/version-bump/SKILL.md) | Bumping package versions for beta, RC, and official releases |
+| [docs-gap](.github/skills/docs-gap/SKILL.md) | Analyzing release changes for missing user-facing documentation |

 ## Package Domains

--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -14,3 +14,5 @@ Load these for detailed context on specific topics:
 | [e2e-coverage](.github/skills/e2e-coverage/SKILL.md) | Updating the E2E test coverage report when apps/skeletons change |
 | [ai-context](.github/skills/ai-context/SKILL.md) | Creating, updating, or maintaining AI documentation files |
 | [changelog](.github/skills/changelog/SKILL.md) | Writing, reviewing, or editing changelog entries for releases |
+| [version-bump](.github/skills/version-bump/SKILL.md) | Bumping package versions for beta, RC, and official releases |
+| [docs-gap](.github/skills/docs-gap/SKILL.md) | Analyzing release changes for missing user-facing documentation |
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -286,3 +286,95 @@ Good commit messages are very important and you should make sure to explain what
 * A commit description which clearly explains the change if it's not super-obvious by the title.  Some description always helps!
 * Reference related issues and pull-requests by number in the description body (e.g. "#9999").
 * Add "Fixes" before the issue number if the addition of that commit fully resolves the issue.
+
+## Release Process
+
+Meteor releases follow a lifecycle: **beta** -> **RC (release candidate)** -> **official**. Releases are prepared on `release-<VERSION>` branches (e.g., `release-3.4.1`) and compared against the `devel` branch.
+
+Three AI skills support this process. They are defined as markdown files under `.github/skills/` and can be used by any AI coding assistant that supports reading project context. Trigger them from any session on a release branch.
+
+### AI Skills for Releases
+
+| Skill | Purpose | Skill File |
+|-------|---------|------------|
+| [changelog](.github/skills/changelog/SKILL.md) | Generate and update changelog entries from merged PRs | `v3-docs/docs/generators/changelog/versions/` |
+| [version-bump](.github/skills/version-bump/SKILL.md) | Bump package versions for beta, RC, or official releases | `packages/*/package.js`, release config files |
+| [docs-gap](.github/skills/docs-gap/SKILL.md) | Identify missing user-facing documentation for release changes | Produces a gap report in `docs/plans/` |
+
+### Preparing a Beta Release
+
+A beta is the first prerelease for a new version. It bumps all changed packages with a `-betaXXX.0` suffix.
+
+**Step 1 — Update the changelog:**
+
+```
+Update the changelog for 3.4.1 from the current branch compared to devel.
+Check all merged PRs and complete with the missing fixes and features.
+```
+
+**Step 2 — Bump versions:**
+
+```
+Apply the version-bump skill for a beta.0 release on this branch against devel.
+```
+
+Claude will analyze each changed package, determine patch vs minor bumps based on the diff, present a table with reasons, and apply after confirmation.
+
+**Step 3 — Check for documentation gaps:**
+
+```
+Run the docs-gap skill to analyze what documentation is missing for this release.
+```
+
+### Preparing an RC Release
+
+An RC transitions beta versions to release candidate. The base version stays the same, only the suffix changes.
+
+**Step 1 — Update the changelog** (same as beta, catches any new PRs merged since the last beta).
+
+**Step 2 — Bump versions:**
+
+```
+Apply the version-bump skill to move from beta to RC on this branch.
+```
+
+### Preparing an Official Release
+
+An official release strips all prerelease suffixes and updates the release config and npm installer.
+
+**Step 1 — Finalize the changelog:**
+
+```
+Finalize the changelog for 3.4.1 — set the release date and replace any
+RC version references with final versions.
+```
+
+**Step 2 — Bump versions:**
+
+```
+Apply the version-bump skill for an official release on this branch.
+```
+
+This is a two-commit process: packages and release config first, npm installer second.
+
+**Step 3 — Verify documentation coverage:**
+
+```
+Run the docs-gap skill and apply any missing documentation for this release.
+```
+
+### Other Useful Prompts
+
+```
+# Separate Rspack improvements from other changes in the changelog
+Update the changelog separating Rspack improvements from other contributions.
+
+# Override a specific package bump magnitude
+The roles package should be a minor bump because it adds getUserIdsInRoleAsync.
+
+# Generate the gap report without applying fixes
+Run the docs-gap skill to produce a gap report only — don't write any docs yet.
+
+# Check which packages changed vs devel
+What packages have changed on this branch compared to devel?
+```
--- a/v3-docs/docs/about/install.md
+++ b/v3-docs/docs/about/install.md
@@ -22,6 +22,7 @@ And it will prompt you to choose a project name and frontend framework.
 - Meteor supports Windows 7 / Windows Server 2008 R2 and up.
 - Apple M1 is natively supported from Meteor 2.5.1 onward (for older versions, rosetta terminal is required).
 - If you are using Meteor <= 3.0.4 and you are on a Mac M1 (Arm64 version) you need to have Rosetta 2 installed, as Meteor uses it for running MongoDB. Check how to install it [here](https://osxdaily.com/2020/12/04/how-install-rosetta-2-apple-silicon-mac/). *No longer needed in Meteor 3.1*.
+- As of Meteor 3.4.1, the dev-bundle fast path works correctly on Apple Silicon, improving startup performance on arm64 Macs.
 - Disabling antivirus (Windows Defender, etc.) will improve performance.
 - For compatibility, Linux binaries are built with CentOS 6.4 i386/amd64.

--- a/v3-docs/docs/about/modern-build-stack/rspack-bundler-integration.md
+++ b/v3-docs/docs/about/modern-build-stack/rspack-bundler-integration.md
@@ -245,6 +245,22 @@ With this, Meteor will process these files, merge stylesheets, generate the fina

 Keep in mind: compiling styles with the Meteor compilers triggers Meteor HMR, which is slower than Rspack HMR. Migrating to compile styles with Rspack as part of the app code ensures the fastest HMR for style changes in development.

+### Server-Only Apps
+
+Meteor-Rspack supports apps without a client entry point. If your app only defines a `server` entry in `meteor.mainModule`, Rspack runs only for the server build and Meteor skips client-side bundling through Rspack.
+
+``` json
+{
+  "meteor": {
+    "mainModule": {
+      "server": "server/main.js"
+    }
+  }
+}
+```
+
+This is useful for API servers, microservices, or background workers that don't serve a client UI. Rspack still handles server-side bundling, including dependency resolution and tree-shaking.
+
 ### Nested Imports

 Nested imports are a feature of Meteor’s bundler, not supported in standard bundlers. Meteor introduced them during a time when bundling standards were still evolving and experimented with its own approach. This feature comes from the [`reify` module](https://github.com/benjamn/reify/tree/main) and works with Babel transpilation. SWC doesn't support them since they were never standardized.
@@ -327,6 +343,12 @@ Learn more in the [official Rspack and React integration guide](https://rspack.r

 > Use `meteor create --react` to start with a preconfigured Rspack React app.

+### Preact
+
+If your project uses [Preact](https://preactjs.com/) instead of React, Meteor detects it automatically. When Preact is installed, Meteor skips adding React-specific dependencies (such as `react-refresh`), so your Preact setup is not affected by the Rspack integration.
+
+No additional configuration is needed — just install the `rspack` package as usual and ensure Preact is listed in your `package.json` dependencies.
+
 ### React Compiler

 Meteor-Rspack supports React Compiler. To enable it, install the required dependencies and add the new configuration to Meteor’s `rspack.config.js` file.
--- a/v3-docs/docs/api/meteor.md
+++ b/v3-docs/docs/api/meteor.md
@@ -749,6 +749,8 @@ function is rerun with the new value, assuming it didn't throw an error at the p
 If you call [`observe`](./collections.md#Mongo-Cursor-observe) or [`observeChanges`](./collections.md#Mongo-Cursor-observeChanges) in your
 publish handler, this is the place to stop the observes.

+As of Meteor 3.4.1, `onStop` callbacks can be `async` functions. The server awaits all async `onStop` callbacks before completing session cleanup, which prevents resource leaks from unawaited asynchronous teardown logic.
+
 <ApiBox name="Subscription#error" />
 <ApiBox name="Subscription#stop" />
 <ApiBox name="Subscription#connection" />
--- a/v3-docs/docs/cli/index.md
+++ b/v3-docs/docs/cli/index.md
@@ -78,6 +78,11 @@ $env:SERVER_NODE_OPTIONS = '--inspect' | meteor run
 SERVER_NODE_OPTIONS=--inspect-brk meteor run
 ```

+Quoted values are supported, which is useful when an option contains special characters:
+```bash
+SERVER_NODE_OPTIONS='--max-old-space-size=4096 --inspect' meteor run
+```
+
 ### Port Configuration Example

 ```bash
--- a/v3-docs/docs/generators/changelog/versions/3.4.1.md
+++ b/v3-docs/docs/generators/changelog/versions/3.4.1.md
@@ -1,20 +1,61 @@
-## v3.4.1, 2026-02-09
+## v3.4.1, 2026-03-31

 ### Highlights

+#### Rspack Improvements
+
+- Enable automatic CSS delegation to Rspack, [PR#14257](https://github.com/meteor/meteor/pull/14257)
+- Add support for `swc.config.ts` configuration files, [PR#14150](https://github.com/meteor/meteor/pull/14150), [PR#14233](https://github.com/meteor/meteor/pull/14233)
+- Support running multiple Rspack instances, [PR#14165](https://github.com/meteor/meteor/pull/14165)
+- Support server-only apps with Rspack, [PR#14171](https://github.com/meteor/meteor/pull/14171)
+- Serve `sw.js` files during development (HMR), [PR#14255](https://github.com/meteor/meteor/pull/14255)
+- Simplify Rspack build logs, [PR#14158](https://github.com/meteor/meteor/pull/14158)
+- Track local dependencies in `rspack.config.js` for cache invalidation, [PR#14111](https://github.com/meteor/meteor/pull/14111)
+- Fix tools-core error on certain environments and support `NODE_ENV` override, [PR#14166](https://github.com/meteor/meteor/pull/14166)
+- Ensure consistent POSIX-style paths to fix Windows Blaze issues, [PR#14210](https://github.com/meteor/meteor/pull/14210)
+- Inherit `TOOL_NODE_FLAGS` in Rspack processes, [PR#14131](https://github.com/meteor/meteor/pull/14131)
+- Skip Rspack HMR proxy middleware setup on Cordova, [PR#14226](https://github.com/meteor/meteor/pull/14226)
+- Add `skipLibCheck` to avoid Rspack CLI type failure, [PR#14094](https://github.com/meteor/meteor/pull/14094)
+- Check if Preact is installed before adding React dependencies, [PR#14268](https://github.com/meteor/meteor/pull/14268)
+
+#### Features
+
+- Add `getUserIdsInRoleAsync` methods with tests, [PR#14030](https://github.com/meteor/meteor/pull/14030)
+- Add TypeScript + Tailwind skeleton, [PR#14237](https://github.com/meteor/meteor/pull/14237)
+- Revamp `meteor create` examples with dynamic fetching, `--from-branch`, and `--from-dir` options, [PR#14266](https://github.com/meteor/meteor/pull/14266)
+
+#### Improvements
+
+- Update to Node v22.22.1, [PR#14219](https://github.com/meteor/meteor/pull/14219)
+- Refactor `callback-hook` package with deduplication and bug fix in `clear`, [PR#13861](https://github.com/meteor/meteor/pull/13861)
+- Cache regex patterns in `utils.js` for improved performance, [PR#14062](https://github.com/meteor/meteor/pull/14062)
+- Add optional `cookies` property to `CategorizedRequest` type, [PR#14085](https://github.com/meteor/meteor/pull/14085)
 - Add support for dots in minimongo key names, [PR#13975](https://github.com/meteor/meteor/pull/13975)
- Fix operator precedence bug in `passwordValidator` that could reject valid passwords, [PR#14075](https://github.com/meteor/meteor/pull/14075)
+- Use concurrency-safe iteration in Minimongo async methods, [PR#13927](https://github.com/meteor/meteor/pull/13927)
+- Constrain TypeScript extension types to `Document` in collection extensions, [PR#14105](https://github.com/meteor/meteor/pull/14105)
+- Remove redundant `await` on returned promises in accounts-base, [PR#14017](https://github.com/meteor/meteor/pull/14017), [PR#14186](https://github.com/meteor/meteor/pull/14186)
+- Remove `import React from 'react'` from project skeletons, [PR#14041](https://github.com/meteor/meteor/pull/14041)
+- Add IntelliJ IDEs icon, [PR#14059](https://github.com/meteor/meteor/pull/14059)
+- Update OAuth configuration instructions, [PR#13947](https://github.com/meteor/meteor/pull/13947)
+
+#### Fixes
+
+- Fix operator precedence bug in `passwordValidator` that could reject valid passwords, [PR#14075](https://github.com/meteor/meteor/pull/14075), [PR#14169](https://github.com/meteor/meteor/pull/14169)
+- Await async `onStop` callbacks in DDP server to fix session memory leak, [PR#14236](https://github.com/meteor/meteor/pull/14236)
+- Handle deleted PostCSS dependency files gracefully, [PR#14128](https://github.com/meteor/meteor/pull/14128)
+- Fix `meteor node` using wrong Node.js version after git branch switch, [PR#14144](https://github.com/meteor/meteor/pull/14144)
+- Enable dev-bundle fast path on Apple Silicon Macs, [PR#14146](https://github.com/meteor/meteor/pull/14146)
+- Fix Cordova platforms detection to avoid modern/legacy mismatch, [PR#14113](https://github.com/meteor/meteor/pull/14113)
+- Remove `Vary: User-Agent` header from hashed assets, [PR#14122](https://github.com/meteor/meteor/pull/14122)
+- Handle quoted values in `SERVER_NODE_OPTIONS`, [PR#14225](https://github.com/meteor/meteor/pull/14225)
+- Skip CSS fragment identifiers in module warnings, [PR#14079](https://github.com/meteor/meteor/pull/14079)
+- Lazy-load `vscode-nsfw` to support RHEL 8 environments, [PR#14058](https://github.com/meteor/meteor/pull/14058)
+- Fix `Cursor` transform types in `mongo.d.ts`, [PR#13774](https://github.com/meteor/meteor/pull/13774)
 - Do not throw error on `forgotPassword` when `ambiguousErrorMessages` is set, [PR#14060](https://github.com/meteor/meteor/pull/14060)
 - Fix Watchman `RootResolveError` for symlinked packages, [PR#14045](https://github.com/meteor/meteor/pull/14045)
 - Fix `getUsersInRoleAsync` to handle assignment options correctly, [PR#14014](https://github.com/meteor/meteor/pull/14014)
- Use concurrency-safe iteration in Minimongo async methods, [PR#13927](https://github.com/meteor/meteor/pull/13927)
- Constrain TypeScript extension types to `Document` in collection extensions, [PR#14105](https://github.com/meteor/meteor/pull/14105)
- Remove redundant `await` on returned promises in accounts-base, [PR#14017](https://github.com/meteor/meteor/pull/14017)
- Remove `import React from 'react'` from project skeletons, [PR#14041](https://github.com/meteor/meteor/pull/14041)
 - Fix displaying Google Maps in mobile applications by preserving native globals in legacy polyfills
- Add IntelliJ IDEs icon, [PR#14059](https://github.com/meteor/meteor/pull/14059)
 - Remove unused `_processOneDataMessage` from DDP client
- Update OAuth configuration instructions, [PR#13947](https://github.com/meteor/meteor/pull/13947)
 - Fix bugs with test-in-console, [PR#13000](https://github.com/meteor/meteor/pull/13000)

 All Merged PRs@[GitHub PRs 3.4.1](https://github.com/meteor/meteor/pulls?q=is%3Apr+is%3Amerged+base%3Arelease-3.4.1)
@@ -41,7 +82,20 @@ If you find any issues, please report them to the [Meteor issues tracker](https:

 #### Bumped Meteor Packages

- roles@1.0.2
+- meteor-tool@3.4.1-beta.0
+- accounts-base@3.2.1-beta341.0
+- accounts-password@3.2.3-beta341.0
+- callback-hook@1.6.3-beta341.0
+- ddp-server@3.1.3-beta341.0
+- meteor@2.2.1-beta341.0
+- minimongo@2.0.6-beta341.0
+- mongo@2.2.1-beta341.0
+- roles@1.1.0-beta341.0
+- rspack@1.1.0-beta341.0
+- test-in-console@2.0.2-beta341.0
+- tinytest@1.4.0-beta341.0
+- tools-core@1.1.0-beta341.0
+- webapp@2.1.2-beta341.0

 #### Bumped NPM Packages

@@ -65,5 +119,18 @@ N/A
 - [@ReinaT5678](https://github.com/ReinaT5678)
 - [@zodern](https://github.com/zodern)
 - [@paritoshdey-dev](https://github.com/paritoshdey-dev)
+- [@dolgarev](https://github.com/dolgarev)
+- [@wreiske](https://github.com/wreiske)
+- [@welkinwong](https://github.com/welkinwong)
+- [@shamshad-ansari](https://github.com/shamshad-ansari)
+- [@ebroder](https://github.com/ebroder)
+- [@sblaisot](https://github.com/sblaisot)
+- [@Shresthap21](https://github.com/Shresthap21)
+- [@thenileshmishra](https://github.com/thenileshmishra)
+- [@slegarraga](https://github.com/slegarraga)
+- [@mvogttech](https://github.com/mvogttech)
+- [@dupontbertrand](https://github.com/dupontbertrand)
+- [@fredmaiaarantes](https://github.com/fredmaiaarantes)
+- [@imajus](https://github.com/imajus)

 ✨✨✨
--- a/v3-docs/docs/packages/roles.md
+++ b/v3-docs/docs/packages/roles.md
@@ -247,6 +247,28 @@ const users = await (await Roles.getUsersInRoleAsync("manager", {
 })).fetchAsync();
 ```

+<ApiBox name="Roles.getUserIdsInRoleAsync" hasCustomExample />
+
+Example:
+
+```js
+// Get all user IDs with the "admin" role
+const adminIds = await Roles.getUserIdsInRoleAsync("admin");
+
+// Get user IDs with specific roles in a scope
+const editorIds = await Roles.getUserIdsInRoleAsync(
+  ["editor", "writer"],
+  { scope: "blog" }
+);
+
+// Check across any scope
+const managerIds = await Roles.getUserIdsInRoleAsync("manager", {
+  anyScope: true,
+});
+```
+
+Unlike `getUsersInRoleAsync` which returns a cursor, `getUserIdsInRoleAsync` returns a `Promise<Array>` of user ID strings directly, making it useful when you only need the IDs without fetching full user documents.
+
 ## Checking Roles

 <ApiBox name="Roles.userIsInRoleAsync" hasCustomExample />