docs: how to set up a git worktree, and why inheritance hides the gaps

CONTRIBUTING.md

@@ -15,6 +15,43 @@ Threadplane is MIT-licensed and developed in the open. Contributions are welcome
 4. **Security issues:** do not open a public issue — see [SECURITY.md](SECURITY.md)
    for the private vulnerability-reporting process.
 
+## Working in a git worktree
+
+A `git worktree` gets a fresh checkout but **not** a fresh `npm install`. Node
+resolves modules by walking *up* the directory tree, so a worktree created inside
+this repository silently inherits the main checkout's `node_modules` and mostly
+works — which is why the gaps surface as unrelated-looking failures well into a
+task rather than up front.
+
+Run install once per worktree before building anything:
+
+```bash
+npm ci
+```
+
+`npm ci` installs strictly from `package-lock.json` and never rewrites it, so it
+is safe on any platform (regenerating the lockfile is not — see the note below).
+It also runs `postinstall`, which generates files that are gitignored and
+therefore absent from every fresh checkout.
+
+Four failure signatures come from skipping it. They look unrelated but share one
+cause, and each is fixed by the install above:
+
+| Symptom | Why inheritance doesn't cover it |
+| --- | --- |
+| `Failed to resolve import "./license-public-key.generated.js"` | Generated by `postinstall` and gitignored, so it exists in no fresh checkout. |
+| `Cannot find module 'posthog-node'` when building `website` | Installed only into `apps/website/node_modules`, never hoisted. The walk up from the worktree's `apps/website/` never passes through the main checkout's. |
+| `Could not resolve "node_modules/katex/dist/katex.min.css"` | Referenced by literal path from the workspace root, not by module resolution — so there is no upward walk to inherit through. |
+| `Next.js inferred your workspace root, but it may not be correct` when building `cockpit` | Turbopack resolves its own workspace root and will not compile outside it. |
+
+Do not fix these by copying individual packages from the main checkout. The list
+keeps growing, a partial copy pulls in a package without its transitive
+dependencies, and a mistargeted `cp` can overwrite `node_modules` itself.
+
+Do not run `npm install` in a worktree on macOS either: it rewrites
+`package-lock.json` and drops the Linux `@next/swc-*` bindings, which breaks CI.
+`npm ci` is the safe command.
+
 ## Testing
 
 New functionality and bug fixes must include automated tests. Run a project's