chore: upgrade yarn to 4.17.0 and update tooling docs

.github/dependabot.yml

@@ -7,10 +7,15 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
     groups:
       npm-minor-patch:
         patterns: ["*"]
         update-types: ["minor", "patch"]
+    ignore:
+      - dependency-name: "@types/node"
+        update-types: ["version-update:semver-major"]
 
   - package-ecosystem: "github-actions"
     directory: "/"
@@ -20,3 +25,5 @@ updates:
       actions-minor-patch:
         patterns: ["*"]
         update-types: ["minor", "patch"]
+    cooldown:
+      default-days: 7

.github/workflows/ci.yml

@@ -14,55 +14,60 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+      - run: corepack enable
       - uses: actions/setup-node@v6
         with:
           node-version-file: .node-version
           cache: yarn
-      - run: yarn install --frozen-lockfile
+      - run: yarn install
       - run: yarn format:check
 
   lint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+      - run: corepack enable
       - uses: actions/setup-node@v6
         with:
           node-version-file: .node-version
           cache: yarn
-      - run: yarn install --frozen-lockfile
+      - run: yarn install
       - run: yarn lint:check
 
   typecheck:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+      - run: corepack enable
       - uses: actions/setup-node@v6
         with:
           node-version-file: .node-version
           cache: yarn
-      - run: yarn install --frozen-lockfile
+      - run: yarn install
       - run: yarn typecheck
 
   test:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+      - run: corepack enable
       - uses: actions/setup-node@v6
         with:
           node-version-file: .node-version
           cache: yarn
-      - run: yarn install --frozen-lockfile
+      - run: yarn install
       - run: yarn test
 
   build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+      - run: corepack enable
       - uses: actions/setup-node@v6
         with:
           node-version-file: .node-version
           cache: yarn
-      - run: yarn install --frozen-lockfile
+      - run: yarn install
       - run: yarn build
       - uses: actions/upload-artifact@v7
         with:
@@ -75,11 +80,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+      - run: corepack enable
       - uses: actions/setup-node@v6
         with:
           node-version-file: .node-version
           cache: yarn
-      - run: yarn install --frozen-lockfile
+      - run: yarn install
       # publint resolves the package `exports` against the packed tarball, which
       # references ./dist/*. Reuse the build job's output instead of rebuilding.
       - uses: actions/download-artifact@v8

.github/workflows/publish.yml

@@ -15,12 +15,13 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@v7
+      - run: corepack enable
       - uses: actions/setup-node@v6
         with:
           node-version-file: .node-version
           registry-url: https://registry.npmjs.org
           cache: yarn
-      - run: yarn install --frozen-lockfile
+      - run: yarn install
       - run: yarn lint:check
       - run: yarn typecheck
       - run: yarn build

.gitignore

@@ -1,2 +1,17 @@
-dist
-node_modules
+# Build artifacts
+dist/
+
+# Dependency artifacts
+node_modules/
+
+# IDE artifacts
+.idea/
+
+# Yarn
+# https://yarnpkg.com/getting-started/qa#which-files-should-be-gitignored
+.yarn/*
+!.yarn/releases
+!.yarn/patches
+!.yarn/plugins
+!.yarn/sdks
+!.yarn/versions

.prettierignore

@@ -0,0 +1 @@
+.yarn/

.yarnrc.yml

@@ -0,0 +1,11 @@
+enableGlobalCache: true
+
+enableImmutableInstalls: true
+
+enableScripts: false
+
+nodeLinker: node-modules
+
+npmMinimalAgeGate: 1w
+
+yarnPath: .yarn/releases/yarn-4.17.0.cjs

CLAUDE.md

@@ -8,7 +8,7 @@ Dual-target ESM TypeScript library `@proof.com/proof-vc-common`. Browser entry e
 2. **Prompt before publishing.** Never bump version, push tags, create a Release, or trigger the publish workflow without explicit confirmation. Publishes are permanent.
 3. **Run `yarn check-all` before any commit or push.** Composes format, lint, typecheck, publint.
 4. **Keep `yarn publint` on `--pack npm`.** `--pack auto` picks yarn-1 mode and reports false-positive errors.
-5. **Don't lower `engines.node` below `>=22.0.0`.** `@sd-jwt/*` requires Node 20; Node 20 is past EOL.
+5. **Don't lower `engines.node` below `>=24.0.0`.** Node 24 is the active LTS; older LTS lines (20, 22) are EOL or near it. `@sd-jwt/*` requires Node 20+.
 6. **Never use `eslint-disable` as a workaround.** If a lint rule fires, fix the underlying code or surface the rule to the user for a config decision — do not silence it inline. Same applies to `@ts-ignore` / `@ts-expect-error` and other suppression comments.
 
 ## Browser Graph
@@ -112,7 +112,12 @@ The Release triggers `publish.yml`: check suite → tag must match `package.json
 
 Never `git push --follow-tags` to `main`: the commit is rejected but the tag still pushes, stranding it on an unmerged commit. Delete a stray tag with `git push --delete origin vX.Y.Z`.
 
+## Tooling (Yarn 4)
+
+- Yarn is pinned via `packageManager: [email protected]` (`.yarn/releases/yarn-4.17.0.cjs`). Run `corepack enable` so the project yarn is used; CI does the same.
+- `.yarnrc.yml` config: `nodeLinker: node-modules`, immutable installs (`enableImmutableInstalls: true` - no `--frozen-lockfile` needed), `enableScripts: false` (no postinstall scripts - a dep needing a build step at install won't run it), `npmMinimalAgeGate: 1w` (deps published <1 week ago won't install; matches the dependabot 7-day cooldown).
+- `yarn.lock` is the only lockfile.
+
 ## Notes
 
-- `yarn.lock` is the only lockfile (no `package-lock.json`).
 - Scope is `@proof.com` (with the dot), not `@proof`.

CONTRIBUTING.md

@@ -2,8 +2,8 @@
 
 ## Requirements
 
-- `node` >= 22.0.0
-- `yarn`
+- `node` >= 24.0.0 (active LTS)
+- `yarn` 4 - run `corepack enable`; the version is pinned via `packageManager` in `package.json`.
 
 ## Design Principles
 
@@ -21,8 +21,10 @@ Cryptographic operations (e.g. VC signature verification) are only done in node
 - `yarn build`
 - `yarn format`
 - `yarn lint`
-- `yarn typcheck`
+- `yarn typecheck`
+- `yarn test`
 - `yarn publint`
+- `yarn check-all`
 
 ## Pull Requests
 

package.json

@@ -60,17 +60,18 @@
     "@sd-jwt/sd-jwt-vc": "^0.19.0"
   },
   "devDependencies": {
-    "@types/node": "^26.0.1",
-    "eslint": "^10.4.0",
+    "@types/node": "^24.13.2",
+    "eslint": "^10.5.0",
     "eslint-plugin-unused-imports": "^4.4.1",
-    "prettier": "^3.8.3",
+    "prettier": "^3.8.4",
     "prettier-plugin-packagejson": "^3.0.2",
     "publint": "^0.3.21",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.4"
+    "typescript-eslint": "^8.61.1"
   },
+  "packageManager": "[email protected]",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
   "publishConfig": {
     "access": "public"