docs: set bun/bunx as the canonical package manager everywhere

.agents/rules/development/package-versions.md

@@ -6,7 +6,7 @@ When creating new projects, test scripts, or reproduction repos:
 
 **NEVER** hardcode specific versions in `package.json`. Instead:
 
-1. Use `npm install <package>` or `bun add <package>` to get latest
+1. Use `bun add <package>` to get latest
 2. Or use `latest` tag: `"tsdown": "latest"`
 
 ## Why
@@ -31,9 +31,9 @@ When creating new projects, test scripts, or reproduction repos:
 ### ✅ CORRECT - Install fresh
 
 ```bash
-# Let npm/bun resolve latest
-npm init -y
-npm install -D tsdown typescript
+# Let bun resolve latest
+bun init -y
+bun add -D tsdown typescript
 
 # Or use latest tag
 bun add -D tsdown@latest typescript@latest

.agents/skills/link-workspace-packages/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: link-workspace-packages
-description: 'Link workspace packages in monorepos (npm, yarn, pnpm, bun). USE WHEN: (1) you just created or generated new packages and need to wire up their dependencies, (2) user imports from a sibling package and needs to add it as a dependency, (3) you get resolution errors for workspace packages (@org/*) like "cannot find module", "failed to resolve import", "TS2307", or "cannot resolve". DO NOT patch around with tsconfig paths or manual package.json edits - use the package manager''s workspace commands to fix actual linking.'
+description: 'Link workspace packages in monorepos (bun, npm, yarn, pnpm). USE WHEN: (1) you just created or generated new packages and need to wire up their dependencies, (2) user imports from a sibling package and needs to add it as a dependency, (3) you get resolution errors for workspace packages (@org/*) like "cannot find module", "failed to resolve import", "TS2307", or "cannot resolve". DO NOT patch around with tsconfig paths or manual package.json edits - use the package manager''s workspace commands to fix actual linking.'
 ---
 
 # Link Workspace Packages
@@ -13,9 +13,9 @@ Check whether there's a `packageManager` field in the root-level `package.json`.
 
 Alternatively check lockfile in repo root:
 
+- `bun.lock` / `bun.lockb` → **bun** ← this project
 - `pnpm-lock.yaml` → pnpm
 - `yarn.lock` → yarn
-- `bun.lock` / `bun.lockb` → bun
 - `package-lock.json` → npm
 
 ## Workflow
@@ -27,6 +27,22 @@ Alternatively check lockfile in repo root:
 
 ---
 
+## bun (this project's package manager)
+
+Supports `workspace:` protocol (pnpm-compatible).
+
+```bash
+cd packages/app && bun add @org/ui
+```
+
+Result in `package.json`:
+
+```json
+{ "dependencies": { "@org/ui": "workspace:*" } }
+```
+
+---
+
 ## pnpm
 
 Uses `workspace:` protocol - symlinks only created when explicitly declared.
@@ -81,47 +97,31 @@ npm resolves to local workspace automatically during install.
 
 ---
 
-## bun
+## Examples
 
-Supports `workspace:` protocol (pnpm-compatible).
+**Example 1: bun - link ui lib to app (this project)**
 
 ```bash
 cd packages/app && bun add @org/ui
 ```
 
-Result in `package.json`:
-
-```json
-{ "dependencies": { "@org/ui": "workspace:*" } }
-```
-
----
-
-## Examples
-
-**Example 1: pnpm - link ui lib to app**
+**Example 2: pnpm - link ui lib to app**
 
 ```bash
 pnpm add @org/ui --filter @org/app --workspace
 ```
 
-**Example 2: npm - link multiple packages**
-
-```bash
-npm install @org/data-access @org/ui --workspace @org/dashboard
-```
-
 **Example 3: Debug "Cannot find module"**
 
 1. Check if dependency is declared in consumer's `package.json`
 2. If not, add it using appropriate command above
-3. Run install (`pnpm install`, `npm install`, etc.)
+3. Run install (`bun install`, `pnpm install`, `npm install`, etc.)
 
 ## Notes
 
 - Symlinks appear in `<consumer>/node_modules/@org/<package>`
 - **Hoisting differs by manager:**
-  - npm/bun: hoist shared deps to root `node_modules`
+  - bun/npm: hoist shared deps to root `node_modules`
   - pnpm: no hoisting (strict isolation, prevents phantom deps)
   - yarn berry: uses Plug'n'Play by default (no `node_modules`)
 - Root `package.json` should have `"private": true` to prevent accidental publish

.agents/skills/monitor-ci/SKILL.md

@@ -131,6 +131,7 @@ When subagent returns `fix_available`, main agent compares `failedTaskIds` vs `v
 When verifiable (non-e2e) unverified tasks exist:
 
 1. **Detect package manager:**
+   - `bun.lock` / `bun.lockb` exists → `bunx nx` ← this project
    - `pnpm-lock.yaml` exists → `pnpm nx`
    - `yarn.lock` exists → `yarn nx`
    - Otherwise → `npx nx`

.agents/skills/nx-run-tasks/SKILL.md

@@ -5,7 +5,7 @@ description: Helps with running tasks in an Nx workspace. USE WHEN the user want
 
 You can run tasks with Nx in the following way.
 
-Keep in mind that you might have to prefix things with npx/pnpx/yarn if the user doesn't have nx installed globally. Look at the package.json or lockfile to determine which package manager is in use.
+Keep in mind that you might have to prefix things with `bunx` (bun — this project's package manager) or `npx`/`pnpx`/`yarn` for other projects. Look at the lockfile in the repo root to determine which package manager is in use: `bun.lock`/`bun.lockb` → `bunx nx`, `pnpm-lock.yaml` → `pnpm nx`, `yarn.lock` → `yarn nx`, otherwise → `npx nx`.
 
 For more details on any command, run it with `--help` (e.g. `nx run-many --help`, `nx affected --help`).
 

.github/copilot-instructions.md

@@ -5,7 +5,7 @@
 **Before every commit**, run:
 
 ```bash
-npx nx format:write
+bunx nx format:write
 ```
 
 This formats all changed files with Prettier via Nx. Failing to do this will cause CI to fail on the `nx format:check` step.
@@ -17,15 +17,15 @@ This applies to **all file types** — TypeScript, Markdown, JSON, YAML, etc.
 Before pushing changes, always run:
 
 ```bash
-npx nx format:write                # format all files (MUST be first)
-npx nx affected -t build --base=HEAD~1  # verify compilation
-npx nx affected -t test --base=HEAD~1   # run tests
-npx nx affected -t lint --base=HEAD~1   # check lint
+bunx nx format:write                # format all files (MUST be first)
+bunx nx affected -t build --base=HEAD~1  # verify compilation
+bunx nx affected -t test --base=HEAD~1   # run tests
+bunx nx affected -t lint --base=HEAD~1   # check lint
 ```
 
 ## Key Conventions
 
-- This is an **Nx monorepo** using **npm workspaces**
+- This is an **Nx monorepo** using **bun workspaces** — use `bun`/`bunx`, not `npm`, `pnpm` or `yarn`
 - Build tool: **tsdown**; Test runner: **Vitest** (some packages use Jest)
 - TypeScript strict ESM — no `require()`, no `__dirname`
 - See `AGENTS.md` for full project conventions and architecture

.github/prompts/monitor-ci.prompt.md

@@ -131,6 +131,7 @@ When subagent returns `fix_available`, main agent compares `failedTaskIds` vs `v
 When verifiable (non-e2e) unverified tasks exist:
 
 1. **Detect package manager:**
+   - `bun.lock` / `bun.lockb` exists → `bunx nx` ← this project
    - `pnpm-lock.yaml` exists → `pnpm nx`
    - `yarn.lock` exists → `yarn nx`
    - Otherwise → `npx nx`
@@ -285,17 +286,17 @@ This means the expected CI Attempt was never created - CI likely failed before N
    ```
 
 2. **If user configured auto-fix attempts** (e.g., `--auto-fix-workflow`):
-   - Detect package manager: check for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`
+   - Detect package manager: check for `bun.lock`/`bun.lockb` (→ bun), `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`
    - Run install to update lockfile:
 
      ```bash
-     pnpm install   # or npm install / yarn install
+     bun install   # or pnpm install / npm install / yarn install
      ```
 
    - If lockfile changed:
 
      ```bash
-     git add pnpm-lock.yaml  # or appropriate lockfile
+     git add bun.lock  # or appropriate lockfile
      git commit -m "chore: update lockfile"
      git push origin $(git branch --show-current)
      ```

.windsurf/rules/nx-monorepo-setup.md

@@ -7,19 +7,19 @@
 ### Core Commands
 
 ```bash
-npx nx build [package]           # Build (inferred from tsdown.config.ts)
-npx nx test [package]            # Test (inferred from vitest.config.ts)
-npx nx test:coverage [package]   # Test with coverage
-npx nx typecheck [package]       # Typecheck (inferred from tsconfig.json)
-npx nx lint [package]            # Lint (inferred from eslint config)
+bunx nx build [package]           # Build (inferred from tsdown.config.ts)
+bunx nx test [package]            # Test (inferred from vitest.config.ts)
+bunx nx test:coverage [package]   # Test with coverage
+bunx nx typecheck [package]       # Typecheck (inferred from tsconfig.json)
+bunx nx lint [package]            # Lint (inferred from eslint config)
 ```
 
 ### Package Creation Workflow
 
 **Step 1: Generate Base Package**
 
 ```bash
-npx nx g @nx/js:lib \
+bunx nx g @nx/js:lib \
   --name=[library-name] \
   --directory=packages/[name] \
   --importPath=@abapify/[library-name] \
@@ -112,7 +112,7 @@ export default defineConfig({
 For packages in `packages/plugins/`:
 
 ```bash
-npx nx g @nx/js:lib \
+bunx nx g @nx/js:lib \
   --name=oat \
   --directory=packages/plugins/oat \
   --importPath=@abapify/oat \
@@ -146,7 +146,7 @@ Just create `tsdown.config.ts` and the nx-tsdown plugin will automatically creat
 Check what targets were inferred:
 
 ```bash
-npx nx show project [package-name] --json | jq '.targets | keys'
+bunx nx show project [package-name] --json | jq '.targets | keys'
 ```
 
 You should see: `["build", "lint", "nx-release-publish", "test", "test:coverage", "test:watch", "typecheck"]`
@@ -155,7 +155,7 @@ You should see: `["build", "lint", "nx-release-publish", "test", "test:coverage"
 
 - **Cross-package**: `@abapify/[package-name]`
 - **Internal files**: `../relative/path` (no extensions for TS files)
-- **Workspace deps**: Use `*` (not `workspace:*`)
+- **Workspace deps**: Use `workspace:*` (bun supports this protocol)
 
 ## File Organization
 

AGENTS.md

@@ -7,32 +7,32 @@ AI agent conventions for the **abapify / adt-cli** monorepo.
 
 ## Repository at a Glance
 
-| Item             | Value                                                |
-| ---------------- | ---------------------------------------------------- |
-| Package manager  | **npm workspaces** — use `npm`, not `pnpm` or `yarn` |
-| Monorepo tooling | **Nx 22**                                            |
-| Language         | **TypeScript 5 strict ESM**                          |
-| Build tool       | **tsdown** (per package)                             |
-| Test runner      | **Vitest** (some packages use Jest)                  |
-| Lint             | **ESLint 10** + Prettier                             |
+| Item             | Value                                                              |
+| ---------------- | ------------------------------------------------------------------ |
+| Package manager  | **bun workspaces** — use `bun`/`bunx`, not `npm`, `pnpm` or `yarn` |
+| Monorepo tooling | **Nx 22**                                                          |
+| Language         | **TypeScript 5 strict ESM**                                        |
+| Build tool       | **tsdown** (per package)                                           |
+| Test runner      | **Vitest** (some packages use Jest)                                |
+| Lint             | **ESLint 10** + Prettier                                           |
 
 ## Essential Commands
 
 ```bash
 # Build
-npx nx build               # all packages
-npx nx build adt-cli       # single package
+bunx nx build               # all packages
+bunx nx build adt-cli       # single package
 
 # Test
-npx nx test                # all packages
-npx nx test adt-cli        # single package
-npx nx test adt-cli --watch  # watch mode
+bunx nx test                # all packages
+bunx nx test adt-cli        # single package
+bunx nx test adt-cli --watch  # watch mode
 
 # Type check
-npx nx typecheck
+bunx nx typecheck
 
 # Lint (auto-fix)
-npx nx lint
+bunx nx lint
 ```
 
 ## Monorepo Layout
@@ -73,12 +73,12 @@ npx nx lint
 
 - Cross-package imports: `@abapify/<package-name>`
 - Internal file imports: relative paths, no extension (`../utils/parse`)
-- `workspace:*` is **not** supported by npm — use `"*"` for local deps
+- `workspace:*` protocol is supported by bun — use it for local deps
 
 ## Creating a New Package
 
 ```bash
-npx nx g @nx/node:library --directory=packages/<name> --no-interactive
+bunx nx g @nx/node:library --directory=packages/<name> --no-interactive
 # then copy tsdown.config.ts from packages/sample-tsdown
 # set "build": "tsdown" in package.json
 ```
@@ -222,7 +222,7 @@ See `openspec/config.yaml` for project context and per-artifact rules.
 
 ```bash
 # Check if a file path appears in any Nx target outputs
-npx nx show project <package> --json | grep -i "xsd\|generated\|download"
+bunx nx show project <package> --json | grep -i "xsd\|generated\|download"
 ```
 
 | Pattern                               | Lifecycle           | Rule                                                   |
@@ -237,11 +237,11 @@ If an edit keeps "reverting": **stop**. Something is regenerating the file. Chec
 ## After Making Changes
 
 ```bash
-npx nx build <package>   # verify it compiles
-npx nx typecheck         # full type check
-npx nx test <package>    # run tests
-npx nx lint              # fix lint issues
-npx nx format:write      # REQUIRED before every commit — format all files with Prettier
+bunx nx build <package>   # verify it compiles
+bunx nx typecheck         # full type check
+bunx nx test <package>    # run tests
+bunx nx lint              # fix lint issues
+bunx nx format:write      # REQUIRED before every commit — format all files with Prettier
 ```
 
 <!-- nx configuration end-->

README.md

@@ -76,38 +76,38 @@ adt-cli  (Commander.js CLI, plugin loader)
 
 ## Development Setup
 
-**Requirements:** Node.js 18+, npm (not pnpm or yarn)
+**Requirements:** [Bun](https://bun.sh/) (not npm, pnpm or yarn)
 
 ```bash
 git clone https://github.com/abapify/adt-cli.git
 cd adt-cli
 
-npm install
+bun install
 
 # Build all packages
-npx nx build
+bunx nx build
 
 # Run all tests
-npx nx test
+bunx nx test
 
 # Type check
-npx nx typecheck
+bunx nx typecheck
 ```
 
 ### Common Commands
 
 ```bash
 # Build a specific package
-npx nx build adt-cli
+bunx nx build adt-cli
 
 # Test a specific package
-npx nx test adt-cli
+bunx nx test adt-cli
 
 # Lint everything
-npx nx lint
+bunx nx lint
 
 # Watch mode for a package
-npx nx test adt-cli --watch
+bunx nx test adt-cli --watch
 ```
 
 ## Repository Structure
@@ -153,7 +153,7 @@ adt-cli/
 ```bash
 git checkout -b feat/my-change
 # make changes
-npx nx build adt-cli && npx nx test adt-cli
+bunx nx build adt-cli && bunx nx test adt-cli
 git push origin feat/my-change
 # open pull request
 ```