Improve local dev environment setup documentation

CONTRIBUTING.md

@@ -7,10 +7,33 @@ for a friendly and welcoming collaborative environment.
 
 ## Setting up a development environment
 
+### Prerequisites
+
+| Tool    | Required Version | How to check       |
+| ------- | ---------------- | ------------------ |
+| Python  | >= 3.10          | `python --version` |
+| Node.js | 22.x             | `node --version`   |
+
 Note: You will need NodeJS to build the extension package.
 
-The `jlpm` command is Jupyter's pinned version of [yarn](https://yarnpkg.com/) that is installed with Jupyter Builder. You may use
-`yarn` or `npm` in lieu of `jlpm` below.
+The `jlpm` command is Jupyter's pinned version of [yarn](https://yarnpkg.com/) that is installed with Jupyter Builder. Use `jlpm` for all JavaScript dependency and build commands below; the repo only ships a `yarn.lock`, so plain `yarn` or `npm` may resolve different versions and break the build.
+
+### Option A: Using pixi
+
+[pixi](https://pixi.sh/) handles Python, Node.js, and all dependencies in one step. [Install pixi](https://pixi.prefix.dev/latest/#installation), then from the repo root:
+
+```bash
+# Install everything and set up the dev environment
+pixi install
+pixi run develop
+
+# Start the notebook server
+pixi run start
+```
+
+This installs the correct Python and Node.js versions automatically and links the extension for development.
+
+### Option B: Using mamba/conda
 
 **Note**: we recommend using `mamba` to speed up the creation of the environment.
 
@@ -35,6 +58,31 @@ jlpm develop
 jupyter server extension enable notebook
 ```
 
+### Option C: Using pip + jlpm (no conda)
+
+If you prefer not to use conda/mamba, you can set up the environment with pip directly. Make sure you have Python >= 3.10 and Node.js 22.x installed on your system.
+
+```bash
+# Create and activate a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install the package in development mode (this also installs jlpm)
+pip install -e ".[dev,docs,test]"
+
+# Install JavaScript dependencies and build
+jlpm install
+jlpm build
+
+# Link the notebook extension for development
+jlpm develop
+
+# Enable the server extension
+jupyter server extension enable notebook
+```
+
+### Building and running
+
 `notebook` follows a monorepo structure. To build all the packages at once:
 
 ```bash
@@ -47,6 +95,16 @@ There is also a `watch` script to watch for changes and rebuild the app automati
 jlpm watch
 ```
 
+To start the notebook server with development-friendly flags:
+
+```bash
+jupyter notebook --no-browser --ServerApp.token='' --NotebookApp.allow_origin='*'
+```
+
+This disables the auth token (convenient for local dev) and allows cross-origin requests (useful if you're working with a separate frontend dev server).
+
+### Verifying your setup
+
 To make sure the `notebook` server extension is installed:
 
 ```bash
@@ -70,6 +128,29 @@ Then start Jupyter Notebook with:
 jupyter notebook
 ```
 
+### Troubleshooting
+
+**`jlpm: command not found`**\
+`jlpm` is installed as part of Jupyter Builder. Make sure you ran `pip install -e ".[dev,docs,test]"` first.
+
+**JavaScript build fails with missing modules**\
+Try clearing the build cache and reinstalling:
+
+```bash
+jlpm clean
+jlpm
+jlpm build
+```
+
+**`ModuleNotFoundError` when running `jupyter notebook`**\
+Make sure you installed in editable mode (`pip install -e .`) and that your virtual environment is activated.
+
+**Node.js version mismatch**\
+This project requires Node.js 22.x. Check with `node --version`. If you're using nvm: `nvm install 22 && nvm use 22`.
+
+**Pre-commit hooks not running**\
+Run `pre-commit install` manually. The hooks should have been set up automatically by the dev install, but may need to be reinitialized if you cloned before installing.
+
 ### Local changes in Notebook dependencies
 
 The development installation described above fetches JavaScript dependencies from `npm`,