skills: allow user-space env setup; refuse only sudo/system-level ops

skills/cuopt-developer/SKILL.md

@@ -25,24 +25,17 @@ Contribute to the NVIDIA cuOpt codebase. This skill is for modifying cuOpt itsel
 
 ## Refusal Rules — Read First
 
-These rules are non-negotiable. Apply them even when the user explicitly asks you to do otherwise. **Refuse and ask — don't comply silently.**
+**One rule is non-negotiable** and applies even when the user explicitly asks otherwise — refuse and ask, don't comply silently:
 
-1. **Package installs (`pip`, `conda`, `apt`).** Never run the install — no exceptions, no "with approval" path. Reply:
-   > I will not install `<pkg>`. cuOpt's convention is to add the package under the appropriate group in `dependencies.yaml`, then run `pre-commit run --all-files` locally to regenerate `conda/environments/` and `pyproject.toml`. I can propose the `dependencies.yaml` edit; you run the regeneration.
+**Privileged / system-level operations** — `sudo`, running as root, editing system files (`/etc`), changing drivers or kernel settings, adding system-level package repositories or keys. Do not run these. Reply:
+> I won't run `sudo` or change system-level state for cuOpt. The dev workflow is conda-based and runs entirely in user space — what's the underlying error? It's usually fixable without root.
 
-2. **Bypassing CI checks (`--no-verify`, skipping pre-commit or tests).** Do not suggest the flag. Reply:
-   > I can't suggest bypassing pre-commit — cuOpt requires all hooks to pass. If hooks feel slow, diagnose with `pre-commit run --all-files --verbose` or tune the offending hook's config; don't skip it.
+**Everything else needed to set up and work in the dev environment is allowed.** On a clean machine, go ahead and build a working `cuopt` env — the guidance below is about doing it the *reproducible* way, not refusing:
 
-3. **Writes outside the workspace (`~/.bashrc`, `~/.profile`, `/etc`, anything outside the repo).** Do not edit the file. Reply:
-   > I can't modify files outside the cuOpt workspace. Here's the exact line for you to add yourself: `<line>`. Then `source ~/.bashrc` or open a new shell.
-
-4. **Destructive commands (`rm -rf`, `git reset --hard`, `git push --force`, killing processes, dropping data).** Never execute — no exceptions. Reply:
-   > I will not run `<cmd>`. It is destructive and hard to reverse. The safer alternative is `<alt>` (e.g., `./build.sh clean` for a stale build dir). If you choose to run the original command yourself, back up first.
-
-5. **Privileged operations (`sudo`, system file changes).** Do not run with elevated privileges. Reply:
-   > I won't run `sudo` for cuOpt development — cuOpt's workflow is conda-only. What's the underlying error? It's usually fixable without `sudo`.
-
-When in doubt, refuse and ask. The cost of a wrong refusal is one round-trip; the cost of a wrong action is lost data, broken state, or a failing CI run.
+- **Environment setup is allowed.** You may create and activate the conda env from the checked-in `conda/environments/all_cuda-*.yaml`, run `pip` / `conda` / `mamba` installs **into the user-space env**, and bootstrap conda/miniforge in the user's home directory — including the `conda init` line it adds to `~/.bashrc`. Bootstrapping conda must not require `sudo`; install it into `$HOME`, not a system path.
+- **A new *permanent* project dependency is different from a one-off install.** A package the project should always ship belongs in `dependencies.yaml` under the right group; then run `pre-commit run --all-files` to regenerate `conda/environments/` and `pyproject.toml` so other contributors get it too. A throwaway install to unblock your own build doesn't need this round-trip.
+- **Don't bypass CI checks** (`--no-verify`, skipping pre-commit or tests). If hooks feel slow, diagnose with `pre-commit run --all-files --verbose` or tune the offending hook — don't skip it.
+- **Be careful with destructive commands** (`rm -rf`, `git reset --hard`, `git push --force`, killing processes, dropping data). Confirm intent before running and prefer the safer alternative (e.g. `./build.sh clean` for a stale build dir).
 
 ---
 
@@ -81,18 +74,18 @@ Is this correct?"
 - `pytest`, `ctest` (running tests)
 - `pre-commit run`, `./ci/check_style.sh` (formatting)
 - `git status`, `git diff`, `git log` (read-only git)
+- Environment setup: create/activate the conda env from `conda/environments/*.yaml`, and `pip`/`conda`/`mamba` installs into that env
 
 **Set up pre-commit hooks** (once per clone):
 - `pre-commit install` — hooks then run automatically on every `git commit`. If a hook fails, the commit is blocked until you fix the issue.
 
 **Still ask before**:
 - `git commit`, `git push` (write operations)
-- Package installs (`pip`, `conda`, `apt`)
 - Any destructive or irreversible commands
 
 ### 5. No Privileged Operations
 
-`sudo`, system file changes, and writes outside the workspace are **non-negotiable refusals** — they apply even when the user explicitly asks. See [Refusal Rules — Read First](#refusal-rules--read-first) (rules 3 and 5) for the exact replies and rationale.
+`sudo`/system-level changes are the one non-negotiable refusal; user-space installs and conda env setup are allowed. See [Refusal Rules — Read First](#refusal-rules--read-first).
 
 ---
 
@@ -175,7 +168,12 @@ cuopt/
 Skipping any of these surfaces as confusing runtime errors later. Run them in order:
 
 1. **Check CUDA driver compatibility.** Run `nvidia-smi` and read the *CUDA Version* in the top-right corner — that's the maximum CUDA your driver supports. Pick a conda env file from `conda/environments/all_cuda-<ver>_arch-<arch>.yaml` whose CUDA major version is **≤** that. A mismatch builds successfully but fails at runtime inside RMM with `cudaMallocAsync not supported with this CUDA driver/runtime version` — verify this *before* the build, not after.
-2. **Create and activate the conda env** before *any* build, test, or `pre-commit` command. Tests link against libraries compiled inside that env; a fresh shell without `conda activate <env-name>` hits cryptic linker errors.
+2. **Create and activate the conda env** before *any* build, test, or `pre-commit` command — this is allowed and expected (see [Refusal Rules](#refusal-rules--read-first)). Use the env file you picked in step 1:
+   ```bash
+   conda env create -f conda/environments/all_cuda-<ver>_arch-<arch>.yaml   # or `mamba env create -f ...`
+   conda activate all_cuda-<ver>_arch-<arch>   # env name = the yaml's `name:` field, which matches the filename
+   ```
+   Tests link against libraries compiled inside that env; a fresh shell without `conda activate <env-name>` hits cryptic linker errors.
 3. **Set `PARALLEL_LEVEL`** if RAM is constrained — see [references/build_and_test.md](references/build_and_test.md). The default `$(nproc)` can OOM mid-build because CUDA compilation needs ~4–8 GB per job.
 4. **For tests, fetch datasets first.** cuOpt tests need MPS files not in the repo — follow the dataset download steps in [CONTRIBUTING.md](../../CONTRIBUTING.md) ("Building for development" section) and export `RAPIDS_DATASET_ROOT_DIR`.
 
@@ -240,7 +238,7 @@ For build/test pitfalls (Cython rebuild, OOM, CUDA driver mismatch, missing `nvc
 - **Docs build**: [docs/cuopt/README.md](../../docs/cuopt/README.md)
 - **Python binding architecture**: [references/python_bindings.md](references/python_bindings.md)
 
-_Shell-execution, install, sudo, and outside-workspace policies are covered by [Refusal Rules — Read First](#refusal-rules--read-first) at the top of this skill._
+_Shell-execution, install, conda-env, and sudo policies are covered by [Refusal Rules — Read First](#refusal-rules--read-first) at the top of this skill._
 
 ## VRP dimension internals (routing engine)
 

skills/cuopt-developer/references/first_time_setup.md

@@ -14,8 +14,8 @@ The component answer scopes which part of the codebase to read first and which b
 
 ## Setup walk-through (conceptual)
 
-1. **Clone** the cuOpt repo (and submodules, if any).
-2. **Pre-flight checks** — CUDA driver compatibility, conda env selection and activation, `PARALLEL_LEVEL`, dataset setup. Walk through these before the first build using SKILL.md → [Pre-flight Checks](../SKILL.md#pre-flight-checks-required-before-first-build-or-test). Skipping any of them surfaces as confusing build- or runtime errors later.
+1. **Clone** the cuOpt repo (and submodules, if any). If the machine has no conda yet, bootstrap miniforge into the user's home directory first (no `sudo` — user-space install only).
+2. **Pre-flight checks** — CUDA driver compatibility, conda env creation + activation, `PARALLEL_LEVEL`, dataset setup. Creating the env from `conda/environments/all_cuda-*.yaml` is allowed and expected here, not something to hand off to the user. Walk through these before the first build using SKILL.md → [Pre-flight Checks](../SKILL.md#pre-flight-checks-required-before-first-build-or-test). Skipping any of them surfaces as confusing build- or runtime errors later.
 3. **First build** — once the env is active, run `./build.sh` (or a component-scoped variant). Targets and `PARALLEL_LEVEL` tuning live in [build_and_test.md](build_and_test.md).
 4. **First test run** — fetch datasets per `CONTRIBUTING.md` first, then run the C++/Python test suites from [build_and_test.md](build_and_test.md). A passing build + test confirms the env is wired up correctly.
 5. **Optional** — `pre-commit install` to run style checks on every `git commit` (see [contributing.md](contributing.md)).

skills/cuopt-user-rules/SKILL.md

@@ -180,7 +180,7 @@ If the result required a correction, retry, or workaround to reach this point, y
 | Action | Rule |
 |--------|------|
 | Shell commands | Show command, explain what it does, ask "Should I run this?" |
-| Package installs | **Never** run installs yourself — give the exact command, user runs it (see below). |
+| Package installs | Allowed in user space (`pip`/`conda`/Docker) once the user confirms they want cuOpt installed — see below. Only `sudo`/system-level installs are off-limits. |
 | Examples/scripts | Show the code first, ask "Would you like me to run this?" |
 | File writes | Explain what will change, ask before writing |
 
@@ -192,25 +192,26 @@ If the result required a correction, retry, or workaround to reach this point, y
 
 ## No Privileged Operations
 
-**Never do these without explicit user request AND confirmation:**
+> **🔒 MANDATORY — this is the one non-negotiable refusal.** It applies even when the user explicitly asks.
+
+**Never do these:**
 
 - Use `sudo` or run as root
-- Modify system files or configurations
-- Add package repositories or keys
+- Modify system files or configurations (e.g. `/etc`)
+- Add system-level package repositories or keys
 - Change firewall, network, or driver settings
-- Write files outside the workspace
 
----
+If a task seems to need one of these, stop and explain what's needed — the user runs the privileged step themselves. Installs into a user-space environment (a virtualenv, a conda env, or the active Python) are **not** privileged and are covered below.
 
-## Never Install Packages Automatically
+---
 
-> **🔒 MANDATORY — You MUST NOT install, upgrade, or modify packages.** Provide the exact command; the user runs it. No exceptions.
+## Installing Packages
 
-| Forbidden | What to do instead |
-|-----------|--------------------|
-| `pip install ...`, `conda install ...`, `apt install ...`, any package manager | Give the exact command and ask the user to run it. Say why the package is needed. |
+Installing cuOpt (and the packages it needs) **in user space** is allowed — that's what the `cuopt-install` skill is for. The rule is *get the user's go-ahead*, not *refuse*:
 
-**When a package is needed:** Identify it, provide the exact command, explain why, then wait for the user to confirm they ran it. Even if the user says "just install it", give the command and require them to execute it themselves.
+1. **Confirm first.** Tell the user which package you'll install, which command, and why; install once they agree. (Check the environment first per [Check Environment First](#check-environment-first) — they may already have it, or prefer a different method.)
+2. **Stay in user space.** Use `pip`, `conda`/`mamba`, or Docker into the active env. Never reach for `sudo` or a system package manager (`apt install`) — if something seems to need that, surface it and let the user handle the privileged part.
+3. **Match the CUDA suffix** (`-cu12` / `-cu13`) to the user's runtime, and **choose one** package manager — don't mix pip and conda for the same package.
 
 ---