Make `pnpm dev` Just Work

The fastest way to lose a teammate's first hour is a pnpm dev that doesn't work on a clean clone. Ours failed two ways the first time someone tried it. Both were one-line fixes, and both are the kind of thing you only catch by actually starting from zero.

---

Failure one: shared packages weren't built. Our apps import internal packages (@hsm/ui, etc.) that compile to a dist/ folder. On a fresh clone there's no dist/ yet, so the dev server starts and immediately 500s with "can't resolve @hsm/ui."

The fix is telling the task runner that dev depends on its workspace dependencies being built first. In Turborepo that's one line on the dev task, dependsOn: ["^build"], so the shared packages compile before any app server starts. The build is cached, so it's a no-op after the first run, but the first run now succeeds.

The subtle trap: this only kicks in if you start dev through the task runner. Running the app's dev script directly bypasses it and the error comes back. So the blessed command has to route through Turbo, which means the scripts you tell people to run matter as much as the config.

---

Failure two: everything fought over port 3000. Three Next.js apps, each defaulting to next dev on port 3000. Run them together and they collide; run them apart and you're guessing which is which.

Fix: pin a port per app (next dev -p 3000, -p 3001, -p 3002) so the whole workspace comes up cleanly and every app always lives at the same address. Predictable beats clever.

---

The meta-lesson is the one that's easy to skip: test the first run, from nothing. Delete node_modules, delete the build outputs, clone-fresh in a scratch directory, whatever it takes to experience what a new person experiences. Your machine is contaminated with state that hides exactly these bugs. The whole class of "works on my machine" lives in that gap.

We also wrote the two-command path into the README, corepack enable, pnpm install, pnpm dev, plus a one-liner on why the dev task builds packages first, so the next person who hits a weird resolve error has the answer next to the command.

---

None of this is glamorous. But "the project runs the first time you try it" is a feature, for teammates, for future-you, and for the version of you that comes back to this repo in six months having forgotten everything. Spend the hour to make the first pnpm dev boring.