Align Node and pnpm versions across docs and CI

[kylymo]

Plan 004: Align the Node and pnpm support contract

Executor: follow every step and verification gate. Modify only listed files. Stop and report if a STOP condition occurs.

Status

• Priority: P2
• Effort: S
• Risk: LOW
• Depends on: none
• Category: dx/CI
• Planned at: commit c16bc4f, 2026-07-16

Why this matters

The project declares Node ^24.x and pnpm 10.20.0 in package.json, while the README says Node 20.x and pnpm 9+, CI installs Node 22 and latest pnpm, and AGENTS.md says Node 24.x. Contributors can get different dependency/runtime behavior from CI and from the documented setup.

Current state

• package.json:5-6 declares Node 24.x and pnpm 10.20.0.
• README.md:47 documents Node 20.x and pnpm 9+.
• .github/workflows/ci.yml:15-22 installs Node 22 and pnpm latest.
• AGENTS.md documents Node 24.x and pnpm 10.x.
• Audit environment had Node 22.22.1 and no pnpm, so lint/test could not start.

Commands and expected results

Purpose	Command	Expected result
Install	corepack enable && corepack prepare pnpm@10.20.0 --activate && pnpm install --frozen-lockfile	dependencies install from lockfile
Lint	pnpm run lint	exit 0
Typecheck	pnpm run typecheck	exit 0
Tests	pnpm run test	exit 0

Scope

In scope:

• README.md
• .github/workflows/ci.yml
• package.json or AGENTS.md only if the chosen support contract requires it
• Optional .nvmrc/.node-version if repository convention accepts one

Out of scope:

• Dependency upgrades unrelated to runtime alignment
• Application source changes

Steps

Step 1: Choose and document one supported matrix

Use the package manifest and lockfile as the source of truth unless maintainers intentionally choose another tested version. Record exact Node major and pnpm version.

Verify: README, CI, and agent guidance state the same versions.

Step 2: Pin CI to the chosen versions

Configure setup-node and pnpm action/corepack to use the exact supported versions rather than latest.

Verify: CI YAML inspection and a CI run on the default branch.

Step 3: Add a local version check

Add .nvmrc or .node-version and document the corepack activation/install sequence if useful.

Verify: Fresh checkout follows README commands without version ambiguity.

Test plan

Run install, lint, typecheck, and tests on the supported Node/pnpm matrix. Confirm frozen-lockfile install succeeds.

Done criteria

• One exact runtime/package-manager contract is documented
• CI uses that contract
• Fresh checkout setup is reproducible
• Verification commands pass

STOP conditions

• Nuxt or a critical dependency demonstrably requires a different Node major; update the contract based on the tested requirement rather than forcing manifest values.
• CI cannot use the selected pnpm setup action; choose a supported equivalent and document it.

Maintenance notes

Dependabot and future Node upgrades should update manifest, CI, README, and version file together.

Issue body

Problem

Node/pnpm versions disagree across package.json, README, CI, and AGENTS.md. CI also installs pnpm: latest, weakening reproducibility.

Evidence

• package.json:5-6
• README.md:47
• .github/workflows/ci.yml:15-22
• AGENTS.md runtime guidance

Acceptance Criteria

• Select and document one tested Node major and exact pnpm version.
• Pin CI to those versions.
• Align README and repository guidance.
• Verify fresh install, lint, typecheck, and tests.

Verification limitation

The audit host could not run pnpm commands because pnpm was not installed.