docs(ci): replace hardcoded versions with config files

.github/actions/setup-environment/action.yaml

@@ -4,7 +4,7 @@ description: Setup Node.js and cache dependencies consistently
 runs:
   using: "composite"
   steps:
-    - name: Show Node.js environment info
+    - name: Show environment info
       shell: bash
       run: |
         echo "=== Pre-installed Node.js versions ==="
@@ -13,17 +13,27 @@ runs:
         which node && node --version || echo "No default Node.js found"
         echo "=== .nvmrc content ==="
         cat .nvmrc 2>/dev/null || echo "No .nvmrc file found"
+        echo "=== .java-version content ==="
+        cat .java-version 2>/dev/null || echo "No .java-version file found"
+        echo "=== Current Java ==="
+        which java && java --version || echo "No default Java found"
+    - name: Setup Java
+      uses: actions/setup-java@v4
+      with:
+        distribution: 'temurin'
+        java-version-file: '.java-version'
+        cache: 'maven'
     - uses: actions/setup-node@v5
       with:
         node-version-file: '.nvmrc'
         registry-url: 'https://registry.npmjs.org'
-    - name: Show final Node.js version
+    - name: Show final versions
       shell: bash
       run: |
+        echo "=== Final Java version after setup ==="
+        which java && java --version
+        which mvn && mvn --version || echo "Maven not found"
         echo "=== Final Node.js version after setup ==="
         which node && node --version
         npm --version
-    - name: Update npm to latest version
-      shell: bash
-      run: npm install -g npm@11.6.2
     - uses: './.github/actions/node-cache'

.github/workflows/sync-apis.yml

@@ -19,12 +19,6 @@ jobs:
       with:
         token: ${{ secrets.BOT_GH_TOKEN }}
     - uses: './.github/actions/setup-environment'
-    - name: Install Java and Maven
-      uses: actions/setup-java@v4
-      with:
-        distribution: 'temurin'
-        java-version: '21'
-        cache: 'maven'
     - run: npm install
     - name: Generate clients
       run: npm run nx:reset && npm run generate

.java-version

@@ -0,0 +1 @@
+21

AGENTS.md

@@ -21,12 +21,12 @@ This is an Nx monorepo that auto-generates TypeScript API clients for Red Hat Hy
 
 | Layer | Technology |
 |-------|-----------|
-| Language | TypeScript 5.6+, Node.js 20.19.5 |
-| Monorepo | Nx 22.6.5 |
+| Language | TypeScript (see `package.json`), Node.js (see `.nvmrc`) |
+| Monorepo | Nx (see `package.json`) |
 | HTTP Client | Axios |
 | Code Generation | Custom Java OpenAPI generator (Maven), Mustache templates |
-| Testing | Jest 30 (unit + integration), Prism mock server |
-| Linting | ESLint 9 + Prettier |
+| Testing | Jest (unit + integration), Prism mock server |
+| Linting | ESLint + Prettier |
 | CI/CD | GitHub Actions |
 | Release | Nx Release (independent per package, conventional commits) |
 | Module System | Dual CJS + ESM builds |
@@ -96,10 +96,34 @@ npm run nx:reset         # Reset Nx daemon (if it crashes)
 
 ### Common Pitfalls
 
-1. **Editing generated code** — Changes in `src/` will be overwritten. Use templates instead.
-2. **Stale Nx cache** — If builds seem wrong, run `npm run build:no-cache` or `npm run nx:reset`.
-3. **Wrong spec URL domain** — Use `console.redhat.com`, not `cloud.redhat.com` (returns 404).
-4. **Missing Java/Maven** — The custom generator requires Java 21 + Maven. `npm install` triggers `mvn clean package`.
-5. **Pre-commit hook runs tests** — Husky runs `npm test` before every commit. Fix failing tests first.
-6. **Package-lock.json mismatch** — Use the exact Node version from `.nvmrc` (20.19.5) when running `npm install`.
-7. **Shared package changes** — `@redhat-cloud-services/javascript-clients-shared` is a runtime dependency of all clients. Changes propagate everywhere.
+1. **Wrong Node version** — Project requires Node version in `.nvmrc`. Check version match at session start:
+   ```bash
+   cat .nvmrc
+   node --version
+   ```
+   If mismatch, switch version:
+   ```bash
+   nvm use                    # Switch to .nvmrc version
+   # Or if version not installed:
+   nvm install                # Install + switch to .nvmrc version
+   ```
+   After switching Node versions, clean install:
+   ```bash
+   rm -r .nx node_modules packages/*/node_modules
+   nvm use
+   npm install
+   ```
+
+2. **Editing generated code** — Changes in `src/` will be overwritten. Use templates instead.
+
+3. **Stale Nx cache** — If builds seem wrong, run `npm run build:no-cache` or `npm run nx:reset`.
+
+4. **Wrong spec URL domain** — Use `console.redhat.com`, not `cloud.redhat.com` (returns 404).
+
+5. **Missing Java/Maven** — The custom generator requires Java (see `.java-version`) + Maven. `npm install` triggers `mvn clean package`.
+
+6. **Pre-commit hook runs tests** — Husky runs `npm test` before every commit. Fix failing tests first.
+
+7. **Package-lock.json mismatch** — Use the exact Node version from `.nvmrc` when running `npm install`.
+
+8. **Shared package changes** — `@redhat-cloud-services/javascript-clients-shared` is a runtime dependency of all clients. Changes propagate everywhere.

CLAUDE.md

@@ -1,5 +1,26 @@
 @AGENTS.md
 
+## Session Startup Checklist
+
+**Always check Node version matches `.nvmrc` at session start:**
+
+```bash
+cat .nvmrc
+node --version
+```
+
+If mismatch:
+```bash
+nvm use           # Switch to .nvmrc version (or nvm install if not installed)
+```
+
+If Node version changed, clean reinstall:
+```bash
+rm -r .nx node_modules packages/*/node_modules
+nvm use
+npm install
+```
+
 ## Build & Test Commands
 
 ```bash
@@ -24,8 +45,8 @@ Husky is configured:
 
 ## CI Requirements
 
-- Node.js version must match `.nvmrc` (20.19.5)
-- Java 21 + Maven required for generator builds
+- Node.js version must match `.nvmrc`
+- Java (version in `.java-version`) + Maven required for generator builds
 - `npm ci` is used in CI (not `npm install`)
 - Only affected packages are linted/tested/built (`nx affected`)
 

CONTRIBUTING.md

@@ -2,20 +2,44 @@
 
 ## Prerequisites
 
-- Node.js (version in `.nvmrc`, currently 20.19.5)
+- Node.js (version specified in `.nvmrc`)
 - npm 7.0+
-- Java 21 + Maven (for the custom OpenAPI generator)
+- Java (version specified in `.java-version`) + Maven (for the custom OpenAPI generator)
 - Git
 
 ## Setup
 
 ```bash
 git clone https://github.com/RedHatInsights/javascript-clients.git
 cd javascript-clients
-nvm use           # Switch to correct Node version
+
+# Verify Node version matches .nvmrc
+cat .nvmrc
+node --version
+
+# Switch to correct Node version (or install if missing)
+nvm use           # If version installed
+# OR
+nvm install       # If version not installed (installs + switches)
+
 npm install       # Install npm deps + build Maven generator
 ```
 
+### Switching Node Versions
+
+If you need to switch Node versions after initial setup:
+
+```bash
+# Clean all caches and node_modules
+rm -r .nx node_modules packages/*/node_modules
+
+# Switch to .nvmrc version
+nvm use
+
+# Reinstall dependencies
+npm install
+```
+
 ## Development Workflow
 
 ### Adding a New Client

README.md

@@ -15,6 +15,32 @@ We are using Java to install and build this generator. Please install Java and p
 
 ### Troubleshooting
 
+#### Node version mismatch
+
+This project uses nvm to manage Node.js versions. The required version is in `.nvmrc`.
+
+**Check version match:**
+```bash
+cat .nvmrc
+node --version
+```
+
+**Switch to correct version:**
+```bash
+nvm use           # If version already installed
+# OR
+nvm install       # If version not installed
+```
+
+**After switching Node versions, clean reinstall:**
+```bash
+rm -r .nx node_modules packages/*/node_modules
+nvm use
+npm install
+```
+
+This prevents `package-lock.json` mismatches and stale Nx cache issues.
+
 #### Publish to local registry 
 
 You can publish a package to a local registry to test that the import works. 
@@ -41,16 +67,17 @@ NPM_CONFIG_REGISTRY=http://127.0.0.1:4873 npx tsc
 
 #### CI fails due to mismatch between package.json and package-lock.json
 
-The Ubuntu 24.04 container running the Github Actions uses node 20.19.5.
-Therefore, make sure to be running the same node version when running `npm install`.
+The Ubuntu 24.04 container running GitHub Actions uses the Node version from `.nvmrc`.
+Therefore, make sure to be running the same Node version when running `npm install`.
 
 ```sh
 # option 1: using nvm on local 
-nvm use 20.19.5'
+nvm use
 npm install
 
-# option 2: using container very similar to the github action
-podman run --rm -it --userns=keep-id -v .:/workspace:Z -w /workspace -e PATH="/opt/acttoolcache/node/20.19.5/x64/bin:$PATH" catthehacker/ubuntu:act-24.04 npm install
+# option 2: using container very similar to the github action (check .nvmrc for version)
+# Replace NODE_VERSION with value from .nvmrc
+podman run --rm -it --userns=keep-id -v .:/workspace:Z -w /workspace -e PATH="/opt/acttoolcache/node/NODE_VERSION/x64/bin:$PATH" catthehacker/ubuntu:act-24.04 npm install
 ```
 
 #### NX Daemon