chore: upgrade yarn to 4.17.0 and update tooling docs

.github/dependabot.yml

@@ -7,6 +7,8 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
     groups:
       npm-minor-patch:
         patterns: ["*"]
@@ -16,15 +18,22 @@ updates:
     directory: "/site"
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
     groups:
       site-npm-minor-patch:
         patterns: ["*"]
         update-types: ["minor", "patch"]
+    ignore:
+      - dependency-name: "@types/node"
+        update-types: ["version-update:semver-major"]
 
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
     groups:
       actions-minor-patch:
         patterns: ["*"]

.github/workflows/ci.yml

@@ -14,44 +14,48 @@ 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
 
   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:
@@ -64,11 +68,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
@@ -81,6 +86,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
+      - run: corepack enable
       - uses: actions/setup-node@v6
         with:
           node-version-file: .node-version
@@ -91,8 +97,8 @@ jobs:
       # The site imports ../../src/index.ts, which re-exports from
       # @proof.com/proof-vc-common. That package only resolves from the root
       # node_modules, so the root install is required before the site checks.
-      - run: yarn install --frozen-lockfile
-      - run: yarn install --frozen-lockfile
+      - run: yarn install
+      - run: yarn install
         working-directory: site
       - run: yarn format:check
         working-directory: site

.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,15 @@
+enableGlobalCache: true
+
+enableImmutableInstalls: true
+
+enableScripts: false
+
+nodeLinker: node-modules
+
+npmMinimalAgeGate: 1w
+
+npmScopes:
+  proof.com:
+    npmMinimalAgeGate: 0
+
+yarnPath: .yarn/releases/yarn-4.17.0.cjs

CLAUDE.md

@@ -13,8 +13,8 @@ Browser-only ESM TypeScript package `@proof.com/proof-vc-web`. Ships one Web Com
 4. **Prompt before publishing.** Never bump the version, push tags, create a Release, or trigger the publish workflow without explicit confirmation — publishes are permanent.
 5. **Run `yarn check-all` before any commit or push.** It's this repo's "tests + lint": format, lint, typecheck, publint. `check-all` does **not** cover `site/` (root `tsconfig.json` excludes it). Since `site/` imports parent `src/` and pulls `proof-vc-common`, changes to `src/`, dependencies, or `site/` can break the site's CI even when `check-all` passes — so also run the site's checks before commit: `cd site && yarn format:check && yarn lint:check && yarn typecheck && yarn build`.
 6. **Keep `yarn publint` on `--pack npm`.** `--pack auto` picks yarn-1 mode and reports false-positive "file not published" errors.
-7. **Don't lower `engines.node` below `>=22.0.0`.** Matches proof-vc-common.
-8. **Never silence lint with `eslint-disable`.** Fix the underlying issue, not the warning. The only sanctioned exception is a reviewed config override (e.g. the per-file `no-namespace` rule for `src/react.ts` in `eslint.config.js`) — not inline disable comments.
+7. **Don't lower `engines.node` below `>=24.0.0`.** Matches the repo's pinned Node toolchain (`.node-version`).
+8. **Never silence lint with `eslint-disable`.** Fix the underlying issue, not the warning. The only sanctioned exception is a reviewed config override (e.g. the per-file `no-namespace` rule for `src/react.ts` in `eslint.config.mjs`) — not inline disable comments.
 
 ## Essential Commands
 
@@ -32,6 +32,8 @@ Browser-only ESM TypeScript package `@proof.com/proof-vc-web`. Ships one Web Com
 
 Run tooling through `yarn`, not `npx` — the binaries are local devDependencies. Use the script when one exists (`yarn format:check`); otherwise run the local binary directly (`yarn prettier --check <file>`).
 
+Yarn (Berry) is committed under `.yarn/releases/` and pinned via `yarnPath` in `.yarnrc.yml`. Any `yarn` on PATH — a Corepack shim or a global yarn 1.x from Homebrew — reads `yarnPath` and re-execs the committed binary, so everyone runs the pinned version automatically (`packageManager` in `package.json` is kept in sync for Corepack's sake). You only need `corepack enable` if a machine has no `yarn` at all; it ships one with Node, and `yarnPath` takes over from there. CI still runs `corepack enable` before `setup-node` to guarantee a yarn binary on the runner, but ordering no longer matters now that the global yarn 1.x delegates through `yarnPath` too. To bump Yarn, run `yarn set version <version>` — with `yarnPath` already set it rewrites the committed release and `.yarnrc.yml`, so no doc edits are needed. `site/` needs no `.yarnrc.yml` of its own — `yarn` run there walks up to the root config and resolves `yarnPath` to the same committed binary.
+
 ## Architecture
 
 ### Files
@@ -114,7 +116,7 @@ Use `src/react.ts` as the template:
 
 1. Create `src/<framework>.ts` with the framework's module augmentation.
 2. Add to `package.json` `exports`: `"./<framework>": { "types": "./dist/<framework>.d.ts" }`.
-3. If its TS rules trip `no-namespace`, add the file to the per-file ESLint override in `eslint.config.js`.
+3. If its TS rules trip `no-namespace`, add the file to the per-file ESLint override in `eslint.config.mjs`.
 4. If a `@types/...` package is needed at build, add it to `devDependencies` and as an optional peer.
 
 ### Adjust the seal icon
@@ -181,6 +183,8 @@ A 404 after a successful provenance step means npm rejected auth (it returns 404
 - `yarn.lock` is the only lockfile (no `package-lock.json`).
 - Scope is `@proof.com` (with the dot), not `@proof`.
 - CI runs on the Node version in `.node-version`.
-- `@proof.com/proof-vc-common` is `yarn link`-ed during local dev; `package.json` already depends on the published version, the link just shadows it.
+- `@proof.com/proof-vc-common` is `yarn link`-ed during local dev to shadow the published version `package.json` depends on. Berry's `yarn link` mutates `package.json` (`resolutions`) and the lockfile, so under `enableImmutableInstalls` run it with `--no-immutable` and don't commit the resulting `resolutions`/`yarn.lock` changes.
+- `.yarnrc.yml` hardens the toolchain: `enableScripts: false` (no dependency lifecycle scripts run — allow a specific package via `dependenciesMeta.<pkg>.built: true` if one ever legitimately needs a build step) and `npmMinimalAgeGate: 1w` (refuses npm versions younger than a week, mirroring the dependabot `cooldown`). The gate is overridden per-scope to `0` for first-party `@proof.com` packages (via `npmScopes`), so a freshly published `@proof.com/proof-vc-common` can be consumed immediately while third-party deps keep the week-long cooldown.
+- `enableImmutableInstalls: true` makes every `yarn install` lockfile-strict (CI **and** local): it never writes `yarn.lock`, and aborts with `YN0028` if the committed lockfile is out of sync with `package.json`. To intentionally update the lockfile locally (bump a dep, re-link `proof-vc-common`), run `yarn install --no-immutable`, then commit the updated `yarn.lock`.
 - `tsconfig.json` excludes `site`, `dist`, `node_modules` — don't remove from `exclude`; the site imports parent `src/`, which would otherwise cause `rootDir` failures.
 - `dist/` is build output; `tsc` overwrites but doesn't delete stale files. Don't add a clean step without asking.

CONTRIBUTING.md

@@ -2,8 +2,10 @@
 
 ## Requirements
 
-- `node` >= 22.0.0
-- `yarn`
+- `node` >= 24.0.0 (CI and local dev use the version pinned in `.node-version`, currently 24.14.1)
+- `yarn` (Berry) — pinned by the committed release under `.yarn/releases/`, referenced by `yarnPath`. Any `yarn` on your PATH delegates to it, so Homebrew's yarn 1.x works fine. If you have no `yarn` at all, run `corepack enable` once to get one — it ships with Node, and the pinned release takes over from there.
+
+Installs are immutable: a plain `yarn install` never modifies `yarn.lock` and fails if it is out of sync with `package.json`. After adding or bumping a dependency, run `yarn install --no-immutable` and commit the updated `yarn.lock`.
 
 ## Design Principles
 

eslint.config.js → eslint.config.mjs

@@ -1,8 +1,8 @@
 import tseslint from "typescript-eslint";
 import unusedImports from "eslint-plugin-unused-imports";
 
-export default tseslint.config(
-  { ignores: ["dist/**"] },
+export const baseConfig = tseslint.config(
+  { ignores: ["dist/**", ".yarn/**"] },
   ...tseslint.configs.recommended,
   {
     languageOptions: {
@@ -26,10 +26,11 @@ export default tseslint.config(
       ],
     },
   },
-  {
-    files: ["src/react.ts"],
-    rules: {
-      "@typescript-eslint/no-namespace": "off",
-    },
-  },
 );
+
+export default tseslint.config(...baseConfig, {
+  files: ["src/react.ts"],
+  rules: {
+    "@typescript-eslint/no-namespace": "off",
+  },
+});

package.json

@@ -70,8 +70,9 @@
       "optional": true
     }
   },
+  "packageManager": "yarn@4.17.0",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
   "publishConfig": {
     "access": "public"

site/.gitignore

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

site/.prettierignore

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

site/eslint.config.mjs

@@ -0,0 +1,3 @@
+import { baseConfig } from "../eslint.config.mjs";
+
+export default baseConfig;

site/package.json

@@ -14,7 +14,7 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@types/node": "^26.0.1",
+    "@types/node": "^24.13.2",
     "eslint": "^10.5.0",
     "eslint-plugin-unused-imports": "^4.4.1",
     "html-webpack-plugin": "^5.6.5",