chore: drop root package-lock.json and standardize on yarn for pkg

package-lock.json was created by accident in #229 alongside the yarn
lockfile. pkg's canonical package manager is yarn (see yarn.lock); the
accidental npm lockfile drifts silently and confuses contributors.

- Remove package-lock.json and gitignore it at the repo root so it
  cannot reappear.
- Rewrite the dev-command references in CLAUDE.md, .claude/rules/*,
  .github/copilot-instructions.md and docs-site/development.md from
  "npm run <x>" to "yarn <x>", and spell out the split: pkg uses yarn,
  docs-site is the only place npm is used.

User-facing install instructions (README, guide/getting-started, guide/
migration, guide/api) are unchanged — end users still "npm install -g
@yao-pkg/pkg" and the CI recipe example still shows npm, since that
reflects how consumers package their own projects.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: robertsLando

.claude/rules/development.md

@@ -4,23 +4,27 @@ description: Build, lint, formatting, and TypeScript rules
 
 # Development
 
+## Package manager
+
+`pkg` uses **yarn** (see `yarn.lock`). **Never run `npm install` / `npm ci` / `npm run X` at the repo root** — it will create a spurious `package-lock.json`. `npm` is used only inside `docs-site/` (the VitePress site has its own `package-lock.json`).
+
 ## Build
 
 ```bash
-npm run build    # Required before testing — compiles lib/ to lib-es5/
-npm run start    # Watch mode with auto-rebuild
+yarn build    # Required before testing — compiles lib/ to lib-es5/
+yarn start    # Watch mode with auto-rebuild
 ```
 
 ## Lint & Format
 
 ```bash
-npm run lint         # Check both ESLint + Prettier
-npm run fix          # Auto-fix all issues
-npm run lint:code    # ESLint only
-npm run lint:style   # Prettier only
+yarn lint         # Check both ESLint + Prettier
+yarn fix          # Auto-fix all issues
+yarn lint:code    # ESLint only
+yarn lint:style   # Prettier only
 ```
 
-- Always run `npm run lint` before committing. Fix all issues — never push dirty code.
+- Always run `yarn lint` before committing. Fix all issues — never push dirty code.
 - Console statements are disallowed in production code but allowed in test files.
 
 ## TypeScript

.claude/rules/git-and-pr.md

@@ -18,9 +18,9 @@ description: Git workflow, commit conventions, and PR rules
 ## Before Committing
 
 1. Clean test artifacts from test directories (`*.exe`, `*-linux`, `*-macos`, `*-win.exe`).
-2. Run `npm run lint` and fix all issues.
+2. Run `yarn lint` and fix all issues.
 3. Show `git status --short` and get user approval before committing.
 
 ## Release
 
-Uses `release-it` with conventional commits (`npm run release`). This runs linting, generates changelog, creates a git tag, pushes to GitHub, and publishes to npm as `@yao-pkg/pkg`.
+Uses `release-it` with conventional commits (`yarn release`). This runs linting, generates changelog, creates a git tag, pushes to GitHub, and publishes to npm as `@yao-pkg/pkg`.

.claude/rules/project.md

@@ -10,7 +10,7 @@ This is `yao-pkg/pkg` — a maintained fork of the archived `vercel/pkg`.
 
 ## Repository Structure
 
-- `lib/` — TypeScript source (compiled to `lib-es5/` via `npm run build`)
+- `lib/` — TypeScript source (compiled to `lib-es5/` via `yarn build`)
 - `prelude/` — Bootstrap code injected into packaged executables
 - `dictionary/` — Package-specific configs for known npm packages
 - `test/` — Numbered test directories (`test-XX-name/`)

.claude/rules/testing.md

@@ -9,9 +9,9 @@ paths:
 ## Commands
 
 ```bash
-npm run build                          # Always build first
-npm run test:22                        # Test with Node.js 22
-npm run test:host                      # Test with host Node.js version
+yarn build                             # Always build first
+yarn test:22                           # Test with Node.js 22
+yarn test:host                         # Test with host Node.js version
 node test/test.js node22 no-npm test-50-*   # Run specific test pattern
 ```
 

.github/copilot-instructions.md

@@ -40,23 +40,23 @@ This is a TypeScript-based Node.js project that packages Node.js applications in
 Before running tests or making changes, always build the project:
 
 ```bash
-npm run build
+yarn build
 ```
 
 This compiles TypeScript from `lib/` to `lib-es5/` using the TypeScript compiler.
 
 For continuous development with auto-rebuild:
 
 ```bash
-npm run start
+yarn start
 ```
 
 ### Code Standards
 
 #### Required Before Each Commit
 
-- Run `npm run lint` to check both code style and ESLint rules
-- Run `npm run fix` to automatically fix formatting and linting issues
+- Run `yarn lint` to check both code style and ESLint rules
+- Run `yarn fix` to automatically fix formatting and linting issues
 - All changes must pass CI checks (linting, building, and tests)
 
 #### Commit and Push Workflow
@@ -69,8 +69,8 @@ npm run start
    - These files may remain if a test failed before cleanup
 
 2. **Verify no lint issues**:
-   - ALWAYS run `npm run lint` before committing
-   - Fix all linting errors with `npm run fix` or manually
+   - ALWAYS run `yarn lint` before committing
+   - Fix all linting errors with `yarn fix` or manually
    - NEVER commit or push with lint errors present
 
 3. **Request approval before commit/push**:
@@ -89,14 +89,14 @@ This workflow ensures code quality, prevents accidental commits of test artifact
 
 - Uses Prettier for code formatting
 - Single quotes for strings (configured in package.json)
-- Run `npm run lint:style` to check formatting
+- Run `yarn lint:style` to check formatting
 - Format files with: `prettier -w "{lib,prelude,test}/**/*.{ts,js}"`
 
 #### Linting
 
 - Uses ESLint with TypeScript support
 - Configuration: `eslint-config-airbnb-typescript` and `eslint-config-prettier`
-- Run `npm run lint:code` to check for linting issues
+- Run `yarn lint:code` to check for linting issues
 - Console statements are disallowed in production code (lint error), but allowed in test files and scripts
 
 ### Testing
@@ -105,15 +105,15 @@ The test suite is extensive and organized in numbered directories:
 
 ```bash
 # Build first (required)
-npm run build
+yarn build
 
 # Run all tests
-npm test
+yarn test
 
 # Run tests for specific Node.js version
-npm run test:20  # Test with Node.js 20
-npm run test:22  # Test with Node.js 22
-npm run test:host  # Test with host Node.js version
+yarn test:20  # Test with Node.js 20
+yarn test:22  # Test with Node.js 22
+yarn test:host  # Test with host Node.js version
 
 # Run specific test pattern
 node test/test.js node20 no-npm test-50-*
@@ -181,7 +181,7 @@ assert(__dirname === process.cwd());
 The project uses `release-it` with conventional commits:
 
 ```bash
-npm run release
+yarn release
 ```
 
 This interactive process:
@@ -284,9 +284,9 @@ The project uses GitHub Actions workflows:
 ## Important Notes for Copilot Coding Agent
 
 1. **NEVER commit without user approval**: Always show changes with `git status --short`, present a summary, and wait for explicit user confirmation before running `git commit` or `git push`
-2. **ALWAYS check lint before committing**: Run `npm run lint` before every commit and fix all issues - NEVER commit with lint errors
+2. **ALWAYS check lint before committing**: Run `yarn lint` before every commit and fix all issues - NEVER commit with lint errors
 3. **Clean test artifacts before staging**: Remove any test-generated executables (`*.exe`, `*-linux`, `*-macos`, `*-win.exe`) from test directories before committing
-4. **Always build before testing**: Run `npm run build` before running any tests
+4. **Always build before testing**: Run `yarn build` before running any tests
 5. **Use correct Node.js version**: The project requires Node.js >= 20.0.0
 6. **Use Yarn for package management**: This project uses `yarn`, not `npm`, for dependency management
 7. **Respect TypeScript compilation**: Edit `lib/*.ts` files, not `lib-es5/*.js` files

.gitignore

@@ -4,6 +4,9 @@
 # dependencies
 /node_modules
 
+# pkg uses yarn — a root package-lock.json is always accidental
+/package-lock.json
+
 # logs
 npm-debug.log
 

CLAUDE.md

@@ -3,12 +3,14 @@
 ## Quick Reference
 
 ```bash
-npm run build        # Build (required before testing)
-npm run lint         # Check lint + formatting
-npm run fix          # Auto-fix lint + formatting
-npm run start        # Watch mode (rebuild on change)
-npm run test:22      # Run tests for Node.js 22
+yarn build           # Build (required before testing)
+yarn lint            # Check lint + formatting
+yarn fix             # Auto-fix lint + formatting
+yarn start           # Watch mode (rebuild on change)
+yarn test:22         # Run tests for Node.js 22
 ```
 
+> `pkg` uses **yarn** for dependency management. `npm` is only used in `docs-site/` (the VitePress docs). Do not create a root `package-lock.json`.
+
 Detailed project rules are in `.claude/rules/` — they are loaded automatically.
 Shared instructions for GitHub Copilot are in `.github/copilot-instructions.md`.

docs-site/development.md

@@ -7,12 +7,16 @@ description: Local development setup for pkg itself — build, test, release —
 
 This document aims to help you get started with `pkg` development.
 
+::: tip Package manager
+`pkg` uses **yarn** for development. Run `yarn install` once, then `yarn build` / `yarn lint` / `yarn test:22` for everyday tasks. `npm` is only used inside `docs-site/` — never at the repo root, since that would create a spurious `package-lock.json`.
+:::
+
 ## Release Process
 
 In order to create release just run the command:
 
 ```bash
-npm run release
+yarn release
 ```
 
 This command will start an interactive process that will guide you through the release process using [release-it](https://github.com/release-it/release-it)
@@ -22,11 +26,11 @@ This command will start an interactive process that will guide you through the r
 Before running tests ensure you have build the project by running:
 
 ```bash
-npm run build
+yarn build
 ```
 
 > [!NOTE]
-> Remember to run again `npm run build` after changing source code (everything inside `lib` folder).
+> Remember to run again `yarn build` after changing source code (everything inside `lib` folder).
 
 Then you can use the following command to run tests:
 
@@ -88,7 +92,7 @@ Explaining the code above:
 
 ## Hacking on this docs site
 
-The documentation you're reading lives under `docs-site/` and is built with [VitePress](https://vitepress.dev). It's a separate npm workspace from `pkg` itself — its own `package.json` and lockfile.
+The documentation you're reading lives under `docs-site/` and is built with [VitePress](https://vitepress.dev). It's a separate package with its own `package.json` and `package-lock.json` — this is the **only** place `npm` is used in the repo; `pkg` itself uses `yarn`.
 
 ```bash
 cd docs-site