feat: Bun is the package manager, in the docs and in this repo

Dockerfile

@@ -1,15 +1,26 @@
 # Build stage
+#
+# Bun is the package manager (docs/02-standards/bun.md), Node is the runtime —
+# so the builder is a Node image with the Bun binary copied in, not `oven/bun`.
+#
+# That is not cosmetic. `oven/bun` ships a *shim* named `node`, so `nest build`
+# runs under Bun there, and Nest's tsconfig-paths hook then leaves `#mcp` in the
+# emitted JS instead of rewriting it to a relative path. The image builds
+# cleanly and crashes on boot with `Cannot find module '#mcp'`. With a real Node
+# under the build, the aliases are rewritten as they always were.
 FROM node:20-alpine AS builder
 
+COPY --from=oven/bun:1-alpine /usr/local/bin/bun /usr/local/bin/bun
+
 WORKDIR /app
 
 # Copy package files
-COPY package*.json ./
+COPY package.json bun.lock ./
 COPY tsconfig*.json ./
 COPY nest-cli.json ./
 
-# Install dependencies
-RUN npm ci
+# Install dependencies — frozen, so a build can never quietly move the lockfile
+RUN bun install --frozen-lockfile
 
 # Copy source code
 COPY src ./src
@@ -18,7 +29,19 @@ COPY src ./src
 COPY docs ./docs
 
 # Build the application
-RUN npm run build
+RUN bun run build
+
+# Production dependencies, resolved apart from the dev ones above so only they
+# are carried into the runtime image
+FROM node:20-alpine AS deps
+
+COPY --from=oven/bun:1-alpine /usr/local/bin/bun /usr/local/bin/bun
+
+WORKDIR /app
+
+COPY package.json bun.lock ./
+
+RUN bun install --frozen-lockfile --production
 
 # Production stage
 FROM node:20-alpine
@@ -33,10 +56,10 @@ RUN addgroup -g 1001 -S nodejs && \
     adduser -S nestjs -u 1001
 
 # Copy package files
-COPY package*.json ./
+COPY package.json bun.lock ./
 
-# Install production dependencies only
-RUN npm ci --only=production && npm cache clean --force
+# Copy production dependencies resolved by Bun
+COPY --from=deps --chown=nestjs:nodejs /app/node_modules ./node_modules
 
 # Copy built application from builder stage
 COPY --from=builder --chown=nestjs:nodejs /app/dist ./dist

README.md

@@ -243,8 +243,8 @@ Do NOT guess conventions — always verify against MCP results first.
 ```bash
 git clone https://github.com/CleanSlice/mcp.git
 cd mcp
-npm install
-npm run dev
+bun install
+bun run dev
 ```
 
 Then point your MCP client to `http://localhost:8080/mcp`.

docs/00-quickstart/new-feature.md

@@ -469,7 +469,7 @@ After approval, I will detail the file structure.
 - [ ] Translations display correctly
 
 ### Next Steps
-1. Run `npm run build` to verify no errors
+1. Run `bun run build` to verify no errors
 2. Test the feature manually
 3. Add any additional functionality as needed
 

docs/00-quickstart/new-project.md

@@ -228,24 +228,25 @@ cd my-project
 
 ```bash
 # CORRECT - Use NestJS CLI
-npx @nestjs/cli new api --package-manager npm --skip-git
+bunx @nestjs/cli new api --skip-install --skip-git
+cd api && bun install
 
 # WRONG - DO NOT USE:
-# npx create-vite api          ❌ WRONG
-# npx create-react-app api     ❌ WRONG
-# npm init express api         ❌ WRONG
+# bunx create-vite api          ❌ WRONG
+# bunx create-react-app api     ❌ WRONG
+# bun create express api       ❌ WRONG
 ```
 
 ## Step 3: Initialize App (Nuxt)
 
 ```bash
 # CORRECT - Use Nuxt CLI
-npx nuxi init app
+bunx nuxi init app
 
 # WRONG - DO NOT USE:
-# npx create-vite app          ❌ WRONG
-# npx create-next-app app      ❌ WRONG
-# npx create-react-app app     ❌ WRONG
+# bunx create-vite app          ❌ WRONG
+# bunx create-next-app app      ❌ WRONG
+# bunx create-react-app app     ❌ WRONG
 ```
 
 ## Step 4: Create Slices Folders
@@ -439,7 +440,7 @@ import { AuthService, UserDto } from '#api';
 
 ### API Project (NestJS)
 
-- [ ] Run `npx @nestjs/cli new api --package-manager npm --skip-git`
+- [ ] Run `bunx @nestjs/cli new api --skip-install --skip-git`, then `bun install`
 - [ ] Create `api/src/slices/` folder
 - [ ] Configure Prisma ([api-prisma.md](../01-setup/api-prisma.md))
 - [ ] Setup Swagger ([api-swagger.md](../01-setup/api-swagger.md))
@@ -448,7 +449,7 @@ import { AuthService, UserDto } from '#api';
 
 ### App Project (Nuxt)
 
-- [ ] Run `npx nuxi init app`
+- [ ] Run `bunx nuxi init app`
 - [ ] Create `app/slices/` folder
 - [ ] Setup theme slice ([app-theme.md](../01-setup/app-theme.md))
 - [ ] Setup Pinia store ([app-store.md](../01-setup/app-store.md))
@@ -632,8 +633,8 @@ export default defineNuxtConfig({
 
 - **Create PLAN.md BEFORE starting any project setup**
 - **Get user approval before running any setup commands**
-- **Use `npx @nestjs/cli new api` for backend** - NestJS only
-- **Use `npx nuxi init app` for frontend** - Nuxt only
+- **Use `bunx @nestjs/cli new api` for backend** - NestJS only
+- **Use `bunx nuxi init app` for frontend** - Nuxt only
 - **Put ALL code in `slices/` folders** (`api/src/slices/`, `app/slices/`)
 - Create `domain/`, `data/`, `dtos/` folders in API slices
 - Create `Provider.vue` in every component folder

docs/00-quickstart/setup-api.md

@@ -247,7 +247,7 @@ Each slice can define its own Prisma schema fragment. The `prisma-import` tool m
 **Install:**
 
 ```bash
-npm install -D prisma-import
+bun add -d prisma-import
 ```
 
 **prisma/schema.prisma** (base):
@@ -287,20 +287,20 @@ model User {
 ```json
 {
   "scripts": {
-    "generate": "npx prisma-import --force",
-    "premigrate": "npx prisma-import --force",
-    "migrate": "dotenv -e .env.dev -- npx prisma migrate dev && dotenv -e .env.dev -- npx prisma generate",
-    "migrate:prod": "dotenv -e .env.prod -- npx prisma migrate deploy",
-    "studio": "dotenv -e .env.dev -- npx prisma studio"
+    "generate": "bunx prisma-import --force",
+    "premigrate": "bunx prisma-import --force",
+    "migrate": "dotenv -e .env.dev -- bunx prisma migrate dev && dotenv -e .env.dev -- bunx prisma generate",
+    "migrate:prod": "dotenv -e .env.prod -- bunx prisma migrate deploy",
+    "studio": "dotenv -e .env.dev -- bunx prisma studio"
   }
 }
 ```
 
 **Workflow:**
 
 1. Edit slice-specific `.prisma` files
-2. Run `npm run migrate` - merges schemas, creates migration, generates client
-3. Use `npm run studio` to view data in Prisma Studio
+2. Run `bun run migrate` - merges schemas, creates migration, generates client
+3. Use `bun run studio` to view data in Prisma Studio
 
 ## docker-compose.yml
 
@@ -538,7 +538,7 @@ import { PrismaService } from '#/setup/prisma/prisma.service';
 
 **Why `#` instead of `@`?**
 
-- `@` is commonly used for scoped npm packages (`@nestjs/common`)
+- `@` is commonly used for scoped packages (`@nestjs/common`)
 - `#` is unique and clearly indicates internal slice imports
 - Avoids confusion with external dependencies
 
@@ -553,7 +553,7 @@ These compiler options are required for NestJS decorators:
 
 ```bash
 # 1. Install dependencies
-npm install
+bun install
 
 # 2. Copy environment file
 cp .env.example .env.dev
@@ -562,10 +562,10 @@ cp .env.example .env.dev
 docker-compose up -d
 
 # 4. Run database migrations
-npm run migrate
+bun run migrate
 
 # 5. Start development server
-npm run start:dev
+bun run start:dev
 
 # 6. Open Swagger UI
 open http://localhost:3000/api

docs/00-quickstart/setup-app.md

@@ -191,7 +191,7 @@ export default defineNuxtConfig({
 **Reference:** [GitHub - setup/pinia](https://github.com/Dreamvention/cleanslice/tree/main/app/slices/setup/pinia)
 
 ```bash
-npm i @pinia/nuxt pinia
+bun add @pinia/nuxt pinia
 ```
 
 ```typescript
@@ -212,8 +212,8 @@ Stores in `{slice}/stores/` are auto-imported and available globally.
 **Reference:** [GitHub - setup/di](https://github.com/Dreamvention/cleanslice/tree/main/app/slices/setup/di)
 
 ```bash
-npm i inversify reflect-metadata tslib
-npm i -D @rollup/plugin-typescript
+bun add inversify reflect-metadata tslib
+bun add -d @rollup/plugin-typescript
 ```
 
 ```typescript
@@ -253,7 +253,7 @@ export default defineNuxtConfig({
 **Reference:** [GitHub - setup/i18n](https://github.com/Dreamvention/cleanslice/tree/main/app/slices/setup/i18n)
 
 ```bash
-npm i -D @nuxtjs/i18n@next
+bun add -d @nuxtjs/i18n@next
 ```
 
 ```typescript
@@ -313,8 +313,8 @@ export default defineNuxtConfig({
 **Reference:** [setup/api](https://github.com/Dreamvention/cleanslice/tree/main/app/slices/setup/api) | [openapi-ts.config.ts](https://github.com/Dreamvention/cleanslice/blob/main/app/openapi-ts.config.ts)
 
 ```bash
-npm i @hey-api/client-axios axios
-npm i -D @hey-api/openapi-ts
+bun add @hey-api/client-axios axios
+bun add -d @hey-api/openapi-ts
 ```
 
 **openapi-ts.config.ts (root):**
@@ -348,14 +348,14 @@ export default defineConfig({
 {
   "scripts": {
     "build:api": "openapi-ts",
-    "dev": "npm run build:api && nuxt dev",
+    "dev": "bun run build:api && nuxt dev",
     "build": "nuxt build"
   }
 }
 ```
 
 ```bash
-npm run build:api
+bun run build:api
 ```
 
 **nuxt.config.ts:**
@@ -493,8 +493,8 @@ export const handleError = async (error: any) => {
 **Reference:** [GitHub - setup/theme](https://github.com/Dreamvention/cleanslice/tree/main/app/slices/setup/theme)
 
 ```bash
-npm i @nuxtjs/tailwindcss shadcn-nuxt
-npm i -D vite-svg-loader
+bun add @nuxtjs/tailwindcss shadcn-nuxt
+bun add -d vite-svg-loader
 ```
 
 ```typescript
@@ -615,15 +615,15 @@ export default defineNuxtConfig({
 ## Dockerfile
 
 ```dockerfile
-FROM node:22-alpine AS builder
+FROM oven/bun:1-alpine AS builder
 WORKDIR /usr/src/app
-COPY package*.json ./
-RUN npm install
+COPY package.json bun.lock ./
+RUN bun install --frozen-lockfile
 COPY . .
 ARG API_URL
-RUN API_URL=${API_URL} npm run build
+RUN API_URL=${API_URL} bun run build
 EXPOSE 3000
-CMD ["npm", "run", "start"]
+CMD ["bun", "run", "start"]
 ```
 
 ```bash

docs/00-quickstart/system-prompt-feature.md

@@ -258,7 +258,7 @@ When extending existing slices:
 
 3. **Database changes:**
    - Add new models or fields to prisma/schema.prisma
-   - Create migration: `npx prisma migrate dev --name feature_name`
+   - Create migration: `bunx prisma migrate dev --name feature_name`
    - Update mappers if schema changes
 
 ## EXAMPLE PHASE 1 OUTPUT (NEW FEATURE)

docs/00-quickstart/vscode.md

@@ -235,7 +235,7 @@ Create `.vscode/extensions.json` for team recommendations:
 
 1. Ensure Prisma extension is installed
 2. Set Prisma as default formatter for `.prisma` files
-3. Run `npx prisma format` manually if needed
+3. Run `bunx prisma format` manually if needed
 
 ### ESLint Not Finding Config