docs: fix contributor setup instructions

[marc0olo]

Stack of 4 — merge bottom to top. Review each layer against the one below it, not main.

    1. #284 — security fix: dependency advisories, bun.lock removal
→ 2. #285 — contributor setup docs
    3. #286 — consumer_install job, retires e2e_test_bun
    4. #288 — consumer install guidance

Repo installs are pnpm-only: pnpm.overrides, minimumReleaseAge and onlyBuiltDependencies are pnpm-only fields, so a second installer resolves a graph that bypasses them. Bun remains a supported consumer runtime, covered by consumer_install (bun) from layer 3.

Fixes contributor setup instructions. All four issues predate this stack.

• Missing pocket-ic download. .npmrc sets ignore-scripts=true, so the postinstall that fetches the binary does not run on a plain install. Verified: after deleting the binary, pnpm i --frozen-lockfile does not restore it and pnpm run setup does. Both guides now list it as a step.
• Missing example build order. build:examples generates the gitignored declarations/ that the specs import (counter.spec.ts imports ../../declarations/counter.did.js), and root build only builds packages/pic. It also needs the ICP CLI toolchain, which no guide mentioned.
• Broken badges. They pointed at test-nodejs.yml and test-bun.yml; neither file exists.
• Vestigial workspaces. It duplicated pnpm-workspace.yaml exactly for bun installs, and pnpm reads only the YAML. Verified all 12 workspace projects still resolve.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Example toolchain installation is incomplete, and removing workspaces may break Bun installs.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Updates contributor setup documentation, fixes a broken badge, and removes duplicate workspace metadata.

Changes:

• Adds PocketIC and example build guidance.
• Corrects the test workflow badge.
• Removes the redundant workspaces declaration.

File summaries

File	Summary
README.md	Adds PocketIC setup instructions and fixes the badge.
package.json	Removes duplicate workspace metadata; Bun compatibility needs preservation.
examples/README.md	Adds build guidance, but toolchain setup remains incomplete.

Review details

Suppressed comments (1)

package.json:11

• Removing this field breaks the Bun installation path: the example test packages all declare @dfinity/pic as workspace:* (for example, examples/counter/tests/package.json:5), but Bun discovers the root workspace from package.json, not pnpm-workspace.yaml. A fresh bun install will therefore not link/resolve these packages. Keep this field for Bun or replace it with a Bun-supported workspace configuration; pnpm's continued resolution does not cover Bun installs.

  "scripts": {

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[marc0olo]

On the suppressed comment about removing the root workspaces field — it's factually right, and worth recording. Bun does not read pnpm-workspace.yaml, so with the field gone bun install at the root finds nothing:

with    workspaces  ->  "Checked 4 installs across 3 packages"
without workspaces  ->  "No packages! Deleted empty lockfile"
                        pkgs/app: error: lib@workspace:* failed to resolve

Keeping it as-is, deliberately: after this stack nothing supported runs bun install — CI installs with pnpm, both guides say pnpm, engines already carries "npm": "please use pnpm", and bun.lock is gone. The field's only remaining effect would be to let an unsupported root bun install succeed and produce a graph that bypasses pnpm.overrides and minimumReleaseAge — the exact hazard #284 removes.

The cost is that bun install now no-ops quietly instead of erroring clearly, which is not a great failure mode. It's a close call; happy to restore the field if you'd rather keep that path working.

[Copilot]

🔵 Needs a closer look

examples/README.md still omits building packages/pic before example tests.

Review details

Suppressed comments (1)

examples/README.md:39

• Following this setup on a clean checkout still makes pnpm test:examples fail: the workspace dependency resolves @dfinity/pic to packages/pic, whose entry point is dist/index.js, but pnpm i does not build that directory and this sequence only runs build:examples. Please run the package build before the example build (for example, add pnpm build here).

- Build all examples. This compiles the canisters and generates the
  `declarations/` that the tests import, so it must run before the tests:

  ```bash
  pnpm build:examples

• Files reviewed: 3/3 changed files
• Comments generated: 0 new
• Review effort level: Lite

[marc0olo]

Valid — fixed. Following the guide on a clean checkout did fail:

Error: Cannot find module '.../examples/counter/tests/node_modules/@dfinity/pic/dist/index.js'

packages/pic/dist is gitignored and untracked, main is ./dist/index.js, and the package's only script is postinstall (with .npmrc setting ignore-scripts=true), so nothing builds it. CI runs pnpm run build before build:examples; the guide skipped it.

Added a pnpm build step before the example build, so the documented order now matches CI: pnpm i → pnpm run setup → toolchain → pnpm build → pnpm build:examples → pnpm test:examples.

Verified by deleting dist/: resolution fails before pnpm build and succeeds after.

[Copilot]

🟢 Approval recommended

The documented setup corrections are complete with no blocking issues.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 0 new
• Review effort level: Lite