build(deps): switch package manager to pnpm

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

@@ -7,7 +7,7 @@ disable-model-invocation: true
 allowed-tools:
   - Bash(gh *)
   - Bash(git *)
-  - Bash(bun *)
+  - Bash(pnpm *)
   - Bash(./mvnw *)
   - Read
   - Grep
@@ -62,17 +62,17 @@ Each leg's annotation names its own command; this table is only what the annotat
 
 | Failure | What it actually means |
 |---|---|
-| `routeTree.gen.ts is stale` | A Vite build writes it. `cd webapp && bun run build`, then commit the file. |
-| `README images are stale` | The storybook job runs `export:readme-assets` *after* `test:storybook`, so the job goes red having printed a clean pass line. Run `bun run --filter webapp export:readme-assets` and commit `docs/images/readme`. |
+| `routeTree.gen.ts is stale` | A Vite build writes it. `cd webapp && pnpm run build`, then commit the file. |
+| `README images are stale` | The storybook job runs `export:readme-assets` *after* `test:storybook`, so the job goes red having printed a clean pass line. Run `pnpm --filter webapp run export:readme-assets` and commit `docs/images/readme`. |
 | Migrations gate | A changelog that reached `main` was edited, renamed or deleted, or a `master.xml` `<include>` was not appended at the end. Fix forward with a new changeset; never edit the released file. |
 | `verify-changesets` | The PR touches shipped code with no `.changeset/*.md`. `/land-pr` step 7 has the rules. |
 | App Server leg red on a docs-only PR | Expected, not a misconfiguration: `docs/**` is inside the `application-server` paths filter, because `docs:lint` and `check:diagrams` run on that leg. |
 
 ## 4. Reproduce locally before pushing
 
 ```bash
-bun run format
-bun run check
+pnpm run format
+pnpm run check
 ```
 
 `check` runs every leg CI runs except those needing Docker or a live credential — `docs:lint`

.agents/skills/land-pr/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: true
 allowed-tools:
   - Bash(gh *)
   - Bash(git *)
-  - Bash(bun *)
+  - Bash(pnpm *)
   - Bash(./mvnw *)
   - Read
   - Grep
@@ -42,8 +42,8 @@ than guessing, and note the two shapes that surprise people:
 ## 3. Format, then check
 
 ```bash
-bun run format
-bun run check
+pnpm run format
+pnpm run check
 ```
 
 `check` is the complete local quality gate — every leg is listed under `check` in the root
@@ -57,9 +57,9 @@ Generated artefacts are never hand-edited, and regeneration is destructive — i
 directory first, so stash local edits.
 
 ```bash
-bun run generate:api          # controllers or DTOs changed: rewrites openapi.yaml AND webapp/src/api
-bun run db:draft-changelog    # entities changed (needs Docker); then prune the diff to real deltas
-bun run db:generate-erd-docs  # after any changelog change
+pnpm run generate:api          # controllers or DTOs changed: rewrites openapi.yaml AND webapp/src/api
+pnpm run db:draft-changelog    # entities changed (needs Docker); then prune the diff to real deltas
+pnpm run db:generate-erd-docs  # after any changelog change
 ```
 
 `generate:api:application-server:specs` **fails when a port it needs is busy** — HTTP, management, or
@@ -70,7 +70,7 @@ the cost is a wasted Maven cycle. Pass free ports; the exact invocation is in `s
 ## 5. Run the tests your diff can break
 
 ```bash
-bun run test:webapp
+pnpm run test:webapp
 cd server && ./mvnw -pl application -am test -Dsurefire.includedGroups=unit -T 2C --batch-mode -q
 ```
 
@@ -86,11 +86,11 @@ A PR touching `server/`, `webapp/` or `docker/` needs a `.changeset/*.md` or `ve
 fails it.
 
 ```bash
-bun changeset          # user-facing: pick the bump, write the summary in the operator's voice
-bun changeset --empty  # no user-facing effect; say why in the body
+pnpm changeset          # user-facing: pick the bump, write the summary in the operator's voice
+pnpm changeset --empty  # no user-facing effect; say why in the body
 ```
 
-`bun changeset` is interactive — with no TTY, hand-write `.changeset/<slug>.md` (`.changeset/README.md`
+`pnpm changeset` is interactive — with no TTY, hand-write `.changeset/<slug>.md` (`.changeset/README.md`
 has the shape). The summary lands in `CHANGELOG.md` verbatim, so it names what an operator or user can
 now do, not a class or a file. **Pre-1.0, never pick `major`** — it would cut 1.0.0 and the gate
 rejects it; a breaking change rides in `minor` with `**Operators:** …` in the summary and a

.changeset/README.md

@@ -6,15 +6,15 @@ the version bump. (Not a Liquibase `<changeSet>` — a schema change needs both.
 Every PR that changes shipped code (anything under `server/`, `webapp/`, or `docker/` except tests and in-tree docs) ships one; CI (`verify-changesets`) enforces it.
 
 ```bash
-bun changeset          # write one (pick the bump, describe the change)
-bun changeset --empty  # no user-facing effect — then write why in the file body (non-interactive)
+pnpm changeset          # write one (pick the bump, describe the change)
+pnpm changeset --empty  # no user-facing effect — then write why in the file body (non-interactive)
 ```
 
 The summary lands in the changelog **verbatim**, in the operator/user's voice — lead with what they can now
 do, or the symptom a fix removes. No class/hook/file names. No agent-attribution trailers. One changeset per
 user-visible change; unsure whether it's visible? Add one — a reviewer can delete it, a missing note can't.
 
-No TTY (agents, CI)? `bun changeset` is interactive — instead write `.changeset/<slug>.md` by hand in the
+No TTY (agents, CI)? `pnpm changeset` is interactive — instead write `.changeset/<slug>.md` by hand in the
 format shown below. That is the one sanctioned hand-write; never touch `CHANGELOG.md` directly.
 
 **Bump = the operator's upgrade cost:**

.changeset/clean-pnpm-toolchain.md

@@ -0,0 +1,5 @@
+---
+"hephaestus": patch
+---
+
+No operator action is required for the repository's package-manager migration.

.claude/skills/fix-ci/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: true
 allowed-tools:
   - Bash(gh *)
   - Bash(git *)
-  - Bash(bun *)
+  - Bash(pnpm *)
   - Bash(./mvnw *)
   - Read
   - Grep
@@ -62,17 +62,17 @@ Each leg's annotation names its own command; this table is only what the annotat
 
 | Failure | What it actually means |
 |---|---|
-| `routeTree.gen.ts is stale` | A Vite build writes it. `cd webapp && bun run build`, then commit the file. |
-| `README images are stale` | The storybook job runs `export:readme-assets` *after* `test:storybook`, so the job goes red having printed a clean pass line. Run `bun run --filter webapp export:readme-assets` and commit `docs/images/readme`. |
+| `routeTree.gen.ts is stale` | A Vite build writes it. `cd webapp && pnpm run build`, then commit the file. |
+| `README images are stale` | The storybook job runs `export:readme-assets` *after* `test:storybook`, so the job goes red having printed a clean pass line. Run `pnpm --filter webapp run export:readme-assets` and commit `docs/images/readme`. |
 | Migrations gate | A changelog that reached `main` was edited, renamed or deleted, or a `master.xml` `<include>` was not appended at the end. Fix forward with a new changeset; never edit the released file. |
 | `verify-changesets` | The PR touches shipped code with no `.changeset/*.md`. `/land-pr` step 7 has the rules. |
 | App Server leg red on a docs-only PR | Expected, not a misconfiguration: `docs/**` is inside the `application-server` paths filter, because `docs:lint` and `check:diagrams` run on that leg. |
 
 ## 4. Reproduce locally before pushing
 
 ```bash
-bun run format
-bun run check
+pnpm run format
+pnpm run check
 ```
 
 `check` runs every leg CI runs except those needing Docker or a live credential — `docs:lint`

.claude/skills/land-pr/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: true
 allowed-tools:
   - Bash(gh *)
   - Bash(git *)
-  - Bash(bun *)
+  - Bash(pnpm *)
   - Bash(./mvnw *)
   - Read
   - Grep
@@ -42,8 +42,8 @@ than guessing, and note the two shapes that surprise people:
 ## 3. Format, then check
 
 ```bash
-bun run format
-bun run check
+pnpm run format
+pnpm run check
 ```
 
 `check` is the complete local quality gate — every leg is listed under `check` in the root
@@ -57,9 +57,9 @@ Generated artefacts are never hand-edited, and regeneration is destructive — i
 directory first, so stash local edits.
 
 ```bash
-bun run generate:api          # controllers or DTOs changed: rewrites openapi.yaml AND webapp/src/api
-bun run db:draft-changelog    # entities changed (needs Docker); then prune the diff to real deltas
-bun run db:generate-erd-docs  # after any changelog change
+pnpm run generate:api          # controllers or DTOs changed: rewrites openapi.yaml AND webapp/src/api
+pnpm run db:draft-changelog    # entities changed (needs Docker); then prune the diff to real deltas
+pnpm run db:generate-erd-docs  # after any changelog change
 ```
 
 `generate:api:application-server:specs` **fails when a port it needs is busy** — HTTP, management, or
@@ -70,7 +70,7 @@ the cost is a wasted Maven cycle. Pass free ports; the exact invocation is in `s
 ## 5. Run the tests your diff can break
 
 ```bash
-bun run test:webapp
+pnpm run test:webapp
 cd server && ./mvnw -pl application -am test -Dsurefire.includedGroups=unit -T 2C --batch-mode -q
 ```
 
@@ -86,11 +86,11 @@ A PR touching `server/`, `webapp/` or `docker/` needs a `.changeset/*.md` or `ve
 fails it.
 
 ```bash
-bun changeset          # user-facing: pick the bump, write the summary in the operator's voice
-bun changeset --empty  # no user-facing effect; say why in the body
+pnpm changeset          # user-facing: pick the bump, write the summary in the operator's voice
+pnpm changeset --empty  # no user-facing effect; say why in the body
 ```
 
-`bun changeset` is interactive — with no TTY, hand-write `.changeset/<slug>.md` (`.changeset/README.md`
+`pnpm changeset` is interactive — with no TTY, hand-write `.changeset/<slug>.md` (`.changeset/README.md`
 has the shape). The summary lands in `CHANGELOG.md` verbatim, so it names what an operator or user can
 now do, not a class or a file. **Pre-1.0, never pick `major`** — it would cut 1.0.0 and the gate
 rejects it; a breaking change rides in `minor` with `**Operators:** …` in the summary and a

.claude/skills/react-best-practices/AGENTS.md

@@ -1403,7 +1403,7 @@ Reduce SVG coordinate precision to decrease file size. The optimal precision dep
 **Automate with SVGO:**
 
 ```bash
-bun x svgo --precision=1 --multipass icon.svg
+pnpm dlx svgo --precision=1 --multipass icon.svg
 ```
 
 ### 6.5 Prevent Hydration Mismatch Without Flickering

.claude/skills/react-best-practices/rules/rendering-svg-precision.md

@@ -24,5 +24,5 @@ Reduce SVG coordinate precision to decrease file size. The optimal precision dep
 **Automate with SVGO:**
 
 ```bash
-bun x svgo --precision=1 --multipass icon.svg
+pnpm dlx svgo --precision=1 --multipass icon.svg
 ```

.claude/skills/storybook-components/RUBRIC.md

@@ -2,7 +2,7 @@
 
 Scope: `webapp/src/components/**` and their colocated `*.stories.tsx`. **Grade a diff, not the repo.**
 
-**Calibration contract.** A file that renders correctly, is formatted, passes `bun run check`, has a
+**Calibration contract.** A file that renders correctly, is formatted, passes `pnpm run check`, has a
 story per variant and a green a11y panel scores **C**. C is the floor for competent work, not a
 criticism. B costs deliberate design. A costs a rejected alternative written down. A+ is rare by
 construction — at most one dimension per PR should reach it.
@@ -192,7 +192,7 @@ Nearly every file carries `tags: ["autodocs"]`, so a JSDoc block above `meta` or
   (`webapp/src/components/admin/practice-catalog/SortableCatalogTree.stories.tsx` — the stories render
   a harness).
 
-`bun scripts/check-story-prose.ts` gates `<p>` only. For the D band there is no gate — it is a review
+`node scripts/check-story-prose.ts` gates `<p>` only. For the D band there is no gate — it is a review
 question: *delete this block; is anything lost?* Rather less than half the files carry a meta JSDoc and
 rather less than half the stories carry one, so the absence of a block is not by itself a finding.
 
@@ -201,7 +201,7 @@ rather less than half the stories carry one, so the absence of a block is not by
 - **D** — A new rule added to prose that contradicts existing code, with no migration and no gate.
 - **C** — Rule in prose, no gate.
 - **B** — Rule in prose plus a mechanical check — an oxlint rule in `webapp/tools/oxlint/rules/`, or a
-  repository gate in `scripts/` wired into `bun run check`.
+  repository gate in `scripts/` wired into `pnpm run check`.
 - **A** — B, and the gate's own comment explains the neighbouring shapes it deliberately does *not*
   match, so nobody widens it into a nuisance — the house rules in `webapp/tools/oxlint/rules/` are the
   worked examples.

.claude/skills/storybook-components/SKILL.md

@@ -29,7 +29,7 @@ Load the one file that answers your question.
 
 ## Already enforced — do not re-litigate, and do not restate in prose
 
-These fail `bun run check`. Treat a violation as a build error, not a style opinion, and do not
+These fail `pnpm run check`. Treat a violation as a build error, not a style opinion, and do not
 write a guideline that repeats one.
 
 The house rules are registered in `webapp/tools/oxlint/index.ts` — read it rather than trusting a

.claude/skills/storybook-components/traps.md

@@ -48,7 +48,7 @@ story file installs no handlers at all, and `scripts/check-presentational-compon
 `.github/workflows/ci-tests.yml` runs the webapp package's `export:readme-assets` immediately after
 `test:storybook`, and fails the job if `docs/images/readme` is dirty afterwards. So the storybook job can go red
 having printed a clean pass line. If a change moves or renames a story that exports a README asset,
-run `bun run --filter webapp export:readme-assets` and commit the result.
+run `pnpm --filter webapp run export:readme-assets` and commit the result.
 
 ## 6. A hand-rolled stateful wrapper swallows the spy in `meta.args`
 

.github/PULL_REQUEST_TEMPLATE.md

@@ -14,14 +14,14 @@ TITLE FORMAT (required):
   ✗ Bad:  Added weekly ranking filter to leaderboard
 
 BEFORE PUSHING:
-  bun run format && bun run check     # Apply formatting, then run the local quality gate
+  pnpm run format && pnpm run check     # Apply formatting, then run the local quality gate
 
 AFTER API CHANGES:
-  bun run generate:api                # Regenerate all OpenAPI clients
+  pnpm run generate:api                # Regenerate all OpenAPI clients
 
 AFTER DATABASE/ENTITY CHANGES:
-  bun run db:draft-changelog          # Generate Liquibase migration
-  bun run db:generate-erd-docs        # Update ERD documentation
+  pnpm run db:draft-changelog          # Generate Liquibase migration
+  pnpm run db:generate-erd-docs        # Update ERD documentation
 -->
 
 ## Description

.github/actions/setup-caches/action.yml

@@ -40,7 +40,7 @@ runs:
       if: contains(fromJSON('["webapp-storybook", "webapp-e2e"]'), inputs.cache-type)
       shell: bash
       env:
-        DEPENDENCY_HASH: ${{ hashFiles('bun.lock') }}
+        DEPENDENCY_HASH: ${{ hashFiles('pnpm-lock.yaml') }}
       run: |
         if [[ -z "$DEPENDENCY_HASH" ]]; then
           echo "::error::Cannot compute the Playwright cache identity from the checked-out repository."

.github/actions/setup-node-pnpm/action.yml

@@ -0,0 +1,14 @@
+name: "Setup Node.js and pnpm"
+description: "Installs the versions declared by package.json and restores the pnpm store cache."
+runs:
+  using: "composite"
+  steps:
+    - name: Disable Git hooks in CI
+      shell: bash
+      run: echo "HUSKY=0" >> "$GITHUB_ENV"
+    - name: Setup Node.js and pnpm
+      uses: pnpm/setup@703c52620218391530e48b9e8870d5c0082e1b9b # v2.1.0
+      with:
+        cache: true
+        cache-dependency-path: pnpm-lock.yaml
+        install: false

.github/labeler.yml

@@ -31,8 +31,8 @@ dependencies:
   - changed-files:
     - any-glob-to-any-file:
       - "**/package.json"
-      - "**/bun.lock"
-      - "bunfig.toml"
+      - "**/pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
       - "**/pom.xml"
       - "renovate.json"
 

.github/scripts/label-pr.ts

@@ -65,7 +65,7 @@ const GENERATED_PATTERNS = [
 	// Docs generated
 	/^docs\/contributor\/erd\/.*\.mmd$/, // Generated Mermaid ERD diagrams
 
-	/bun\.lock$/,
+	/pnpm-lock\.yaml$/,
 	/\.lock$/,
 ];
 

.github/workflows/cd-docs-teardown.yml

@@ -19,10 +19,10 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - name: Setup Bun
-        uses: ./.github/actions/setup-bun
+      - name: Setup Node.js and pnpm
+        uses: ./.github/actions/setup-node-pnpm
 
-      - run: bun install --frozen-lockfile --ignore-scripts
+      - run: pnpm install --frozen-lockfile --ignore-scripts
 
       - name: Teardown Surge.sh preview
         env: