chore(tooling): migrate 5chan to Yarn 4

.codex/skills/fix-merge-conflicts/SKILL.md

@@ -36,8 +36,8 @@ Open each conflicting file and remove conflict markers. Merge both sides logical
 
 | File type | Strategy |
 |-----------|----------|
-| `package.json` | Merge keys conservatively, then `yarn install` to regenerate `yarn.lock` |
-| `yarn.lock` | Never manually edit — regenerate with `yarn install` |
+| `package.json` | Merge keys conservatively, then `corepack yarn install` to regenerate `yarn.lock` |
+| `yarn.lock` | Never manually edit — regenerate with `corepack yarn install` |
 | Config files (`.json`, `.yaml`) | Preserve union of safe settings; don't delete required fields |
 | Markdown / text | Include both unique sections, deduplicate headings |
 | Binary files | Prefer current branch (ours) |
@@ -48,10 +48,10 @@ Open each conflicting file and remove conflict markers. Merge both sides logical
 Run all three checks. Fix any failures before proceeding.
 
 ```bash
-yarn build && yarn lint && yarn type-check
+corepack yarn build && corepack yarn lint && corepack yarn type-check
 ```
 
-If `package.json` was modified, run `yarn install` first.
+If `package.json` was modified, run `corepack yarn install` first.
 
 ### 4. Verify no remaining markers
 
@@ -78,6 +78,6 @@ git commit -m "chore: resolve merge conflicts"
 ## Deliverables
 
 - Clean working tree with all conflicts resolved
-- Passing `yarn build && yarn lint && yarn type-check`
+- Passing `corepack yarn build && corepack yarn lint && corepack yarn type-check`
 - One local commit: `chore: resolve merge conflicts`
 - Brief summary of files touched and notable resolution choices

.codex/skills/readme/SKILL.md

@@ -154,7 +154,7 @@ bundle install
 ### 3. Install JavaScript Dependencies
 
 \`\`\`bash
-yarn install
+corepack yarn install
 \`\`\`
 
 ### 4. Environment Setup
@@ -708,7 +708,7 @@ The master key doesn't match the credentials file. Either:
 rm -rf node_modules/.vite
 
 # Reinstall JS dependencies
-rm -rf node_modules && yarn install
+rm -rf node_modules && corepack yarn install
 \`\`\`
 
 ### Solid Queue Issues
@@ -761,4 +761,4 @@ Generate a complete README.md file with:
 - Clear section hierarchy
 - Linked table of contents for long documents
 
-Write the README directly to `README.md` in the project root.
+Write the README directly to `README.md` in the project root.

.cursor/skills/fix-merge-conflicts/SKILL.md

@@ -36,8 +36,8 @@ Open each conflicting file and remove conflict markers. Merge both sides logical
 
 | File type | Strategy |
 |-----------|----------|
-| `package.json` | Merge keys conservatively, then `yarn install` to regenerate `yarn.lock` |
-| `yarn.lock` | Never manually edit — regenerate with `yarn install` |
+| `package.json` | Merge keys conservatively, then `corepack yarn install` to regenerate `yarn.lock` |
+| `yarn.lock` | Never manually edit — regenerate with `corepack yarn install` |
 | Config files (`.json`, `.yaml`) | Preserve union of safe settings; don't delete required fields |
 | Markdown / text | Include both unique sections, deduplicate headings |
 | Binary files | Prefer current branch (ours) |
@@ -48,10 +48,10 @@ Open each conflicting file and remove conflict markers. Merge both sides logical
 Run all three checks. Fix any failures before proceeding.
 
 ```bash
-yarn build && yarn lint && yarn type-check
+corepack yarn build && corepack yarn lint && corepack yarn type-check
 ```
 
-If `package.json` was modified, run `yarn install` first.
+If `package.json` was modified, run `corepack yarn install` first.
 
 ### 4. Verify no remaining markers
 
@@ -78,6 +78,6 @@ git commit -m "chore: resolve merge conflicts"
 ## Deliverables
 
 - Clean working tree with all conflicts resolved
-- Passing `yarn build && yarn lint && yarn type-check`
+- Passing `corepack yarn build && corepack yarn lint && corepack yarn type-check`
 - One local commit: `chore: resolve merge conflicts`
 - Brief summary of files touched and notable resolution choices

.cursor/skills/readme/SKILL.md

@@ -154,7 +154,7 @@ bundle install
 ### 3. Install JavaScript Dependencies
 
 \`\`\`bash
-yarn install
+corepack yarn install
 \`\`\`
 
 ### 4. Environment Setup
@@ -708,7 +708,7 @@ The master key doesn't match the credentials file. Either:
 rm -rf node_modules/.vite
 
 # Reinstall JS dependencies
-rm -rf node_modules && yarn install
+rm -rf node_modules && corepack yarn install
 \`\`\`
 
 ### Solid Queue Issues
@@ -761,4 +761,4 @@ Generate a complete README.md file with:
 - Clear section hierarchy
 - Linked table of contents for long documents
 
-Write the README directly to `README.md` in the project root.
+Write the README directly to `README.md` in the project root.

.github/workflows/ci.yml

@@ -28,12 +28,13 @@ jobs:
         with:
           node-version: 22
           cache: 'yarn'
+      - run: corepack enable
 
       - name: Install dependencies
         run: |
           for i in 1 2 3; do
             echo "yarn install attempt $i"
-            yarn install --frozen-lockfile --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
+            yarn install --immutable --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
             sleep 5
             [ "$i" = "3" ] && exit 1
           done
@@ -160,12 +161,13 @@ jobs:
         with:
           node-version: 22
           cache: 'yarn'
+      - run: corepack enable
 
       - name: Install dependencies
         run: |
           for i in 1 2 3; do
             echo "yarn install attempt $i"
-            yarn install --frozen-lockfile --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
+            yarn install --immutable --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
             sleep 5
             [ "$i" = "3" ] && exit 1
           done
@@ -195,6 +197,7 @@ jobs:
         with:
           node-version: 22
           cache: 'yarn'
+      - run: corepack enable
 
       - name: Cache electron binaries
         uses: actions/cache@v4
@@ -207,7 +210,7 @@ jobs:
         run: |
           for i in 1 2 3; do
             echo "yarn install attempt $i"
-            yarn install --frozen-lockfile --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
+            yarn install --immutable --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
             sleep 5
             [ "$i" = "3" ] && exit 1
           done
@@ -258,6 +261,7 @@ jobs:
         with:
           node-version: 22
           cache: 'yarn'
+      - run: corepack enable
 
       - name: Install setuptools for native modules
         run: pip3 install --break-system-packages setuptools || pip3 install --user setuptools || true
@@ -273,7 +277,7 @@ jobs:
         run: |
           for i in 1 2 3; do
             echo "yarn install attempt $i"
-            yarn install --frozen-lockfile --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
+            yarn install --immutable --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
             sleep 5
             [ "$i" = "3" ] && exit 1
           done
@@ -324,6 +328,7 @@ jobs:
         with:
           node-version: 22
           cache: 'yarn'
+      - run: corepack enable
 
       - name: Install setuptools for native modules
         run: pip3 install --break-system-packages setuptools || pip3 install --user setuptools || true
@@ -339,7 +344,7 @@ jobs:
         run: |
           for i in 1 2 3; do
             echo "yarn install attempt $i"
-            yarn install --frozen-lockfile --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
+            yarn install --immutable --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
             sleep 5
             [ "$i" = "3" ] && exit 1
           done
@@ -390,6 +395,7 @@ jobs:
         with:
           node-version: 22
           cache: 'yarn'
+      - run: corepack enable
 
       - name: Cache electron binaries
         uses: actions/cache@v4
@@ -403,7 +409,7 @@ jobs:
         run: |
           for i in 1 2 3; do
             echo "yarn install attempt $i"
-            yarn install --frozen-lockfile --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
+            yarn install --immutable --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
             sleep 5
             [ "$i" = "3" ] && exit 1
           done

.github/workflows/release.yml

@@ -30,11 +30,12 @@ jobs:
         with:
           node-version: 22
           cache: 'yarn'
+      - run: corepack enable
       - name: Install dependencies
         run: |
           for i in 1 2 3; do
             echo "yarn install attempt $i"
-            yarn install --frozen-lockfile --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
+            yarn install --immutable --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
             sleep 5
             [ "$i" = "3" ] && exit 1
           done
@@ -71,11 +72,12 @@ jobs:
         with:
           node-version: 22
           cache: 'yarn'
+      - run: corepack enable
       - name: Install dependencies
         run: |
           for i in 1 2 3; do
             echo "yarn install attempt $i"
-            yarn install --frozen-lockfile --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
+            yarn install --immutable --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
             sleep 5
             [ "$i" = "3" ] && exit 1
           done
@@ -131,6 +133,7 @@ jobs:
         with:
           node-version: 22
           cache: 'yarn'
+      - run: corepack enable
       - name: Setup Python 3.12
         uses: actions/setup-python@v5
         with:
@@ -140,7 +143,7 @@ jobs:
         run: |
           for i in 1 2 3; do
             echo "yarn install attempt $i"
-            yarn install --frozen-lockfile --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
+            yarn install --immutable --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
             sleep 5
             [ "$i" = "3" ] && exit 1
           done
@@ -190,12 +193,13 @@ jobs:
         with:
           node-version: 22
           cache: 'yarn'
+      - run: corepack enable
       - name: Install dependencies
         shell: bash
         run: |
           for i in 1 2 3; do
             echo "yarn install attempt $i"
-            yarn install --frozen-lockfile --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
+            yarn install --immutable --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
             sleep 5
             [ "$i" = "3" ] && exit 1
           done
@@ -233,12 +237,13 @@ jobs:
         with:
           node-version: 22
           cache: 'yarn'
+      - run: corepack enable
       - run: sudo apt-get install -y apksigner zipalign
       - name: Install dependencies
         run: |
           for i in 1 2 3; do
             echo "yarn install attempt $i"
-            yarn install --frozen-lockfile --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
+            yarn install --immutable --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
             sleep 5
             [ "$i" = "3" ] && exit 1
           done
@@ -289,11 +294,12 @@ jobs:
         with:
           node-version: 22
           cache: 'yarn'
+      - run: corepack enable
       - name: Install dependencies
         run: |
           for i in 1 2 3; do
             echo "yarn install attempt $i"
-            yarn install --frozen-lockfile --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
+            yarn install --immutable --ignore-engines --network-timeout 100000 --network-concurrency 1 && break
             sleep 5
             [ "$i" = "3" ] && exit 1
           done

.gitignore

@@ -135,11 +135,12 @@ dev-dist
 # Stores VSCode versions used for testing VSCode extensions
 .vscode-test
 
-# yarn v2
-.yarn/cache
-.yarn/unplugged
-.yarn/build-state.yml
-.yarn/install-state.gz
+# yarn
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
 .pnp.*
 # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
 

.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

AGENTS.md

@@ -27,7 +27,7 @@ Only record items that are repo-specific, likely to recur, and have a concrete m
 | Situation | Required action |
 |---|---|
 | React UI logic changed (`src/components`, `src/views`, `src/hooks`, UI stores) | Follow React architecture rules below and run `yarn doctor` |
-| `package.json` changed | Run `yarn install` to keep `yarn.lock` in sync |
+| `package.json` changed | Run `corepack yarn install` to keep `yarn.lock` in sync |
 | Dependencies or import graph changed | Run `yarn knip` as an advisory manifest/import audit |
 | Translation key/value changed | Use `docs/agent-playbooks/translations.md` |
 | Bug report in a specific file/line | Start with git history scan from `docs/agent-playbooks/bug-investigation.md` before editing |
@@ -71,7 +71,7 @@ src/
 
 ### Package and Dependency Rules
 
-- Use `yarn`, never `npm`.
+- Use Corepack-managed Yarn 4, never `npm`. Run `corepack enable` once on a new machine before using `yarn`.
 - Pin exact dependency versions (`package@x.y.z`), never `^` or `~`.
 - Keep lockfile synchronized when dependency manifests change.
 
@@ -178,7 +178,7 @@ To bypass Portless: `PORTLESS=0 yarn start`
 ## Common Commands
 
 ```bash
-yarn install
+corepack yarn install
 yarn start                # http://5chan.localhost:1355
 yarn build
 yarn test

README.md

@@ -90,13 +90,13 @@ To have your board appear in a directory on the 5chan homepage:
 ### Prerequisites
 
 - Node.js v22 (Download from https://nodejs.org)
-- Yarn: `npm install -g yarn`
-- Portless is installed with project dependencies via `yarn install`
+- Corepack enabled for Yarn 4: `corepack enable`
+- Portless is installed with project dependencies via `corepack yarn install`
 
 ### Setup
 
 1. Clone the repository
-2. Install dependencies: `yarn install --frozen-lockfile`
+2. Install dependencies: `corepack yarn install`
 3. Start the web client: `yarn start`
 
 The dev server runs at http://5chan.localhost:1355 via [Portless](https://port1355.dev/), which gives each Bitsocial project a stable, named URL instead of a random port. To bypass Portless and use a plain Vite dev server: `PORTLESS=0 yarn start`

docs/agent-playbooks/hooks-setup.md

@@ -7,7 +7,7 @@ If your AI coding assistant supports lifecycle hooks, configure these for this r
 | Hook | Command | Purpose |
 |---|---|---|
 | `afterFileEdit` | `scripts/agent-hooks/format.sh` | Auto-format files after AI edits |
-| `afterFileEdit` | `scripts/agent-hooks/yarn-install.sh` | Run `yarn install` when `package.json` changes |
+| `afterFileEdit` | `scripts/agent-hooks/yarn-install.sh` | Run `corepack yarn install` when `package.json` changes |
 | `stop` | `scripts/agent-hooks/sync-git-branches.sh` | Prune stale refs and delete integrated temporary task branches |
 | `stop` | `scripts/agent-hooks/verify.sh` | Hard-gate build, lint, and type-check; keep `yarn audit` informational |
 
@@ -16,7 +16,7 @@ If your AI coding assistant supports lifecycle hooks, configure these for this r
 - Consistent formatting
 - Lockfile stays in sync
 - Build/lint/type issues caught early
-- Security visibility via `yarn audit`
+- Security visibility via `corepack yarn npm audit`
 - One shared hook implementation for both Codex and Cursor
 - Temporary task branches stay aligned with the repo's worktree workflow
 
@@ -46,20 +46,20 @@ exit 0
 
 cat > /dev/null  # consume stdin
 status=0
-yarn build || status=1
-yarn lint || status=1
-yarn type-check || status=1
-echo "=== yarn audit ===" && (yarn audit || true)  # informational
+corepack yarn build || status=1
+corepack yarn lint || status=1
+corepack yarn type-check || status=1
+echo "=== corepack yarn npm audit ===" && (corepack yarn npm audit || true)  # informational
 exit $status
 ```
 
-By default, `scripts/agent-hooks/verify.sh` exits non-zero when `yarn build`, `yarn lint`, or `yarn type-check` fails. Set `AGENT_VERIFY_MODE=advisory` only when you intentionally need signal from a broken tree without blocking the hook.
+By default, `scripts/agent-hooks/verify.sh` exits non-zero when `corepack yarn build`, `corepack yarn lint`, or `corepack yarn type-check` fails. Set `AGENT_VERIFY_MODE=advisory` only when you intentionally need signal from a broken tree without blocking the hook.
 
 ### Yarn Install Hook
 
 ```bash
 #!/bin/bash
-# Run yarn install when package.json is changed
+# Run Corepack-managed Yarn install when package.json is changed
 # Hook receives JSON via stdin with file_path
 
 input=$(cat)
@@ -71,8 +71,8 @@ fi
 
 if [ "$file_path" = "package.json" ]; then
   cd "$(dirname "$0")/../.." || exit 0
-  echo "package.json changed - running yarn install to update yarn.lock..."
-  yarn install
+  echo "package.json changed - running corepack yarn install to update yarn.lock..."
+  corepack yarn install
 fi
 
 exit 0

package.json

@@ -1,13 +1,14 @@
 {
   "name": "5chan",
   "version": "0.7.2",
+  "packageManager": "yarn@4.13.0",
   "description": "A Bitsocial client with an imageboard UI",
   "type": "module",
   "author": "Bitsocial Forge",
   "license": "GPL-2.0-only",
   "private": true,
   "dependencies": {
-    "@bitsocialnet/bitsocial-react-hooks": "https://github.com/bitsocialnet/bitsocial-react-hooks.git#206dc0ad2a422a6fbbf3fc0da4f128d1d0b2b4cd",
+    "@bitsocialnet/bitsocial-react-hooks": "https://codeload.github.com/bitsocialnet/bitsocial-react-hooks/tar.gz/206dc0ad2a422a6fbbf3fc0da4f128d1d0b2b4cd",
     "@capacitor/app": "7.0.1",
     "@capacitor/status-bar": "7.0.1",
     "@capawesome/capacitor-android-edge-to-edge-support": "7.2.2",
@@ -48,8 +49,8 @@
     "generate:assets": "node scripts/generate-asset-manifest.js",
     "sync:directories": "node scripts/sync-directories.js",
     "postinstall": "node scripts/patch-capacitor-cli-tar.cjs && node scripts/patch-bitsocial-react-hooks-esm.cjs",
-    "prebuild": "yarn sync:directories && yarn generate:assets",
-    "prestart": "yarn sync:directories && yarn generate:assets",
+    "prebuild": "corepack yarn sync:directories && corepack yarn generate:assets",
+    "prestart": "corepack yarn sync:directories && corepack yarn generate:assets",
     "start": "node scripts/start-dev.js",
     "build": "cross-env PUBLIC_URL=./ GENERATE_SOURCEMAP=false vite build",
     "build:preload": "vite build --config electron/vite.preload.config.js",
@@ -58,23 +59,23 @@
     "test:leaks": "vitest run --detectAsyncLeaks",
     "preview": "vite preview",
     "analyze-bundle": "cross-env PUBLIC_URL=./ GENERATE_SOURCEMAP=true vite build && npx source-map-explorer 'dist/assets/*.js'",
-    "electron": "yarn build:preload && yarn electron:before && electron .",
-    "electron:no-delete-data": "yarn build:preload && electron .",
-    "electron:start": "concurrently \"cross-env BROWSER=none yarn start\" \"wait-on http://5chan.localhost:1355 && yarn electron\"",
-    "electron:start:no-delete-data": "concurrently \"cross-env BROWSER=none yarn start\" \"wait-on http://5chan.localhost:1355 && yarn electron:no-delete-data\"",
+    "electron": "corepack yarn build:preload && corepack yarn electron:before && electron .",
+    "electron:no-delete-data": "corepack yarn build:preload && electron .",
+    "electron:start": "concurrently \"cross-env BROWSER=none corepack yarn start\" \"wait-on http://5chan.localhost:1355 && corepack yarn electron\"",
+    "electron:start:no-delete-data": "concurrently \"cross-env BROWSER=none corepack yarn start\" \"wait-on http://5chan.localhost:1355 && corepack yarn electron:no-delete-data\"",
     "electron:rebuild-native": "electron-rebuild -f -o better-sqlite3",
     "electron:verify-native": "node scripts/verify-electron-native-modules.js",
-    "electron:prepare-package": "yarn electron:rebuild-native && yarn electron:verify-native",
-    "electron:package": "yarn build && yarn build:preload && yarn electron:prepare-package && electron-forge package",
-    "electron:build": "yarn build && yarn build:preload && yarn electron:prepare-package && electron-forge make",
-    "electron:build:linux": "yarn build && yarn build:preload && yarn electron:prepare-package && electron-forge make --platform=linux",
-    "electron:build:mac": "yarn build && yarn build:preload && yarn electron:prepare-package && electron-forge make --platform=darwin",
-    "electron:build:windows": "yarn build && yarn build:preload && yarn electron:prepare-package && electron-forge make --platform=win32",
-    "electron:build:linux:x64": "yarn build && yarn build:preload && yarn electron:prepare-package && electron-forge make --platform=linux --arch=x64",
-    "electron:build:linux:arm64": "yarn build && yarn build:preload && yarn electron:prepare-package && electron-forge make --platform=linux --arch=arm64",
-    "electron:build:mac:x64": "yarn build && yarn build:preload && yarn electron:prepare-package && electron-forge make --platform=darwin --arch=x64",
-    "electron:build:mac:arm64": "yarn build && yarn build:preload && yarn electron:prepare-package && electron-forge make --platform=darwin --arch=arm64",
-    "electron:before": "yarn electron:before:delete-data",
+    "electron:prepare-package": "corepack yarn electron:rebuild-native && corepack yarn electron:verify-native",
+    "electron:package": "corepack yarn build && corepack yarn build:preload && corepack yarn electron:prepare-package && electron-forge package",
+    "electron:build": "corepack yarn build && corepack yarn build:preload && corepack yarn electron:prepare-package && electron-forge make",
+    "electron:build:linux": "corepack yarn build && corepack yarn build:preload && corepack yarn electron:prepare-package && electron-forge make --platform=linux",
+    "electron:build:mac": "corepack yarn build && corepack yarn build:preload && corepack yarn electron:prepare-package && electron-forge make --platform=darwin",
+    "electron:build:windows": "corepack yarn build && corepack yarn build:preload && corepack yarn electron:prepare-package && electron-forge make --platform=win32",
+    "electron:build:linux:x64": "corepack yarn build && corepack yarn build:preload && corepack yarn electron:prepare-package && electron-forge make --platform=linux --arch=x64",
+    "electron:build:linux:arm64": "corepack yarn build && corepack yarn build:preload && corepack yarn electron:prepare-package && electron-forge make --platform=linux --arch=arm64",
+    "electron:build:mac:x64": "corepack yarn build && corepack yarn build:preload && corepack yarn electron:prepare-package && electron-forge make --platform=darwin --arch=x64",
+    "electron:build:mac:arm64": "corepack yarn build && corepack yarn build:preload && corepack yarn electron:prepare-package && electron-forge make --platform=darwin --arch=arm64",
+    "electron:before": "corepack yarn electron:before:delete-data",
     "electron:before:delete-data": "node -e \"fs.rmSync('.plebbit', { recursive: true, force: true })\"",
     "android:build:icons": "cordova-res android --skip-config --copy --resources /tmp/plebbit-react-android-icons --icon-source ./android/icons/icon.png --splash-source ./android/icons/splash.png --icon-foreground-source ./android/icons/icon-foreground.png --icon-background-source '#ffffee'",
     "knip": "knip --production --include dependencies,unlisted,binaries --no-progress",
@@ -83,7 +84,7 @@
     "type-check": "tsgo --noEmit",
     "prettier": "oxfmt src/**/*.{js,ts,tsx} electron/**/*.{js,mjs}",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
-    "android:build": "yarn build && npx cap sync android && npx cap run android",
+    "android:build": "corepack yarn build && npx cap sync android && npx cap run android",
     "i18n:update": "node scripts/update-translations.js",
     "i18n:update:dry": "node scripts/update-translations.js --dry",
     "doctor": "react-doctor . -y",
@@ -93,7 +94,7 @@
     "smoke:upload-selectors": "node scripts/smoke-upload-selectors.js",
     "test:coverage": "vitest run --coverage.enabled --coverage.provider=istanbul --coverage.reporter=text --coverage.reporter=json --coverage.reporter=json-summary --coverage.reportsDirectory=./coverage",
     "test:coverage:changed": "vitest run --changed master --coverage.enabled --coverage.provider=istanbul --coverage.reporter=text --coverage.reporter=json --coverage.reporter=json-summary --coverage.reportsDirectory=./coverage",
-    "retest:quality": "yarn test && yarn build && yarn lint && yarn type-check && yarn doctor",
+    "retest:quality": "corepack yarn test && corepack yarn build && corepack yarn lint && corepack yarn type-check && corepack yarn doctor",
     "blotter": "node scripts/update-blotter.js",
     "blotter:check": "node scripts/update-blotter.js check",
     "blotter:release": "node scripts/update-blotter.js release",

public/llms.txt

@@ -78,12 +78,12 @@ These are condensed from `AGENTS.md`. If you are contributing code, follow the r
 Prerequisites:
 
 - Node.js 22
-- Yarn
+- Corepack enabled for Yarn 4 (`corepack enable`)
 
 Common setup:
 
 ```bash
-yarn install --frozen-lockfile
+corepack yarn install
 yarn start
 ```
 

scripts/agent-hooks/verify.sh

@@ -59,12 +59,12 @@ echo ""
 
 failures=0
 
-run_required_check "yarn build" yarn build || failures=1
-run_required_check "yarn lint" yarn lint || failures=1
-run_required_check "yarn type-check" yarn type-check || failures=1
+run_required_check "corepack yarn build" corepack yarn build || failures=1
+run_required_check "corepack yarn lint" corepack yarn lint || failures=1
+run_required_check "corepack yarn type-check" corepack yarn type-check || failures=1
 
-echo "=== yarn audit ==="
-yarn audit 2>&1 || true
+echo "=== corepack yarn npm audit ==="
+corepack yarn npm audit 2>&1 || true
 echo ""
 
 cleanup_generated_dir build

scripts/agent-hooks/yarn-install.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# afterFileEdit hook: Run yarn install when package.json is changed
+# afterFileEdit hook: Run Corepack-managed Yarn install when package.json is changed
 # Receives JSON via stdin: {"file_path": "...", "edits": [...]}
 
 input=$(cat)
@@ -13,8 +13,8 @@ fi
 if [ "$file_path" = "package.json" ]; then
   repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
   cd "$repo_root" || exit 0
-  echo "package.json changed - running yarn install to update yarn.lock..."
-  yarn install
+  echo "package.json changed - running corepack yarn install to update yarn.lock..."
+  corepack yarn install
 fi
 
 exit 0

vercel.json

@@ -44,8 +44,8 @@
       ]
     }
   ],
-  "installCommand": "HUSKY=0 YARN_CACHE_FOLDER=/tmp/yarn-cache yarn install --frozen-lockfile --network-timeout 600000 --network-concurrency 1 --child-concurrency 1",
-  "buildCommand": "yarn build",
+  "installCommand": "HUSKY=0 corepack yarn install --immutable",
+  "buildCommand": "corepack yarn build",
   "outputDirectory": "build",
   "framework": "vite"
 }

vitest.config.ts

@@ -3,6 +3,7 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
   test: {
     environment: 'jsdom',
+    setupFiles: ['./vitest.setup.ts'],
     coverage: {
       include: ['src/**/*.{ts,tsx}', 'electron/**/*.{js,mjs}'],
       exclude: [

vitest.setup.ts

@@ -0,0 +1,72 @@
+const storageState = new Map<string, string>();
+
+const storageProto = Storage.prototype;
+
+Object.defineProperties(storageProto, {
+  clear: {
+    configurable: true,
+    enumerable: false,
+    value: function clear() {
+      storageState.clear();
+    },
+    writable: true,
+  },
+  getItem: {
+    configurable: true,
+    enumerable: false,
+    value: function getItem(key: string) {
+      const normalizedKey = String(key);
+      return storageState.has(normalizedKey) ? storageState.get(normalizedKey) ?? null : null;
+    },
+    writable: true,
+  },
+  key: {
+    configurable: true,
+    enumerable: false,
+    value: function key(index: number) {
+      return Array.from(storageState.keys())[index] ?? null;
+    },
+    writable: true,
+  },
+  length: {
+    configurable: true,
+    enumerable: true,
+    get() {
+      return storageState.size;
+    },
+  },
+  removeItem: {
+    configurable: true,
+    enumerable: false,
+    value: function removeItem(key: string) {
+      storageState.delete(String(key));
+    },
+    writable: true,
+  },
+  setItem: {
+    configurable: true,
+    enumerable: false,
+    value: function setItem(key: string, value: string) {
+      storageState.set(String(key), String(value));
+    },
+    writable: true,
+  },
+});
+
+const localStorageMock = Object.create(storageProto) as Storage;
+
+Object.defineProperty(globalThis, 'localStorage', {
+  configurable: true,
+  enumerable: true,
+  value: localStorageMock,
+  writable: true,
+});
+
+if (typeof window !== 'undefined') {
+  Object.defineProperty(window, 'localStorage', {
+    configurable: true,
+    enumerable: true,
+    value: localStorageMock,
+    writable: true,
+  });
+}