---
name: setup-sandbox
description: Sets up the local development environment for Humand frontend sandboxes. Installs nvm, Node 24.11.1, bun, git, and verifies Claude Code Desktop. Run once per machine. Use when the user says "configurar entorno", "setup", "preparar mi máquina", or when tools are missing.
metadata:
  category: Setup & Environment
---

# Skill: Setup Sandbox

Prepares the non-tech user's machine with everything needed to run Humand frontend sandboxes. Should be run **once per machine**. Records what was installed in `~/.humand/sandbox-installed.json` so `/cleanup-sandbox` can safely undo only what this skill installed.

## When to use

- First time a user opens Claude Code on a new machine
- User says "configurar entorno", "setup", "preparar mi máquina"
- A required tool is missing when trying to run `/bootstrap-react-project`

## Steps

### 1. Detect operating system

```bash
uname -s   # Darwin = Mac, MINGW/MSYS/CYGWIN = Windows
```

### 2. Run the environment setup script

**Do NOT install tools manually.** Run the appropriate script from the `scripts/` folder next to this SKILL.md. Use the absolute path when invoking it.

**Mac:**
```bash
bash "<skill-dir>/scripts/setup-env.sh"
```

**Windows:**
```powershell
powershell -ExecutionPolicy Bypass -File "<skill-dir>\scripts\setup-env.ps1"
```

The script:
- Checks for Homebrew, nvm, Node 24.11.1, bun, git, and gh — installing each only if missing
- **Mac — If Homebrew installation fails** (e.g. permission error): automatically switches to **mise** (user-space, no admin required) to install Node instead of nvm; bun is still installed via curl. git and gh are skipped with a warning.
- **Windows — If nvm-windows is not found**: automatically uses **mise** (user-space) to install Node instead. git and gh still require graphical installers and will exit with instructions.
- Adds nvm init (brew path) or mise activation (mise path) to the shell profile (idempotent)
- Writes `~/.humand/sandbox-installed.json` progressively so the registry is always up to date even if the script exits early
- Prints the final JSON to stdout on success — capture it to show the user a summary

If the script exits with a non-zero code:
1. Read the stderr output
2. Translate the error to plain Spanish
3. If the error mentions **permissions**: follow step 6 (Handle permission errors) below
4. For any other error: report it to the user and ask how they want to proceed. Do NOT retry individual steps manually.

If the script ran the **mise path** (brew was unavailable/failed), check the registry JSON for `git_missing` or `gh_missing` keys and tell the user:
> git y/o gh no se pudieron instalar automáticamente porque requieren permisos de admin. Pedile a IT que ejecute: `brew install git gh`. Por ahora podés continuar con el proyecto.

### 5. Verify Claude Code Desktop

```bash
# Mac
ls /Applications/Claude.app 2>/dev/null || mdfind "kMDItemCFBundleIdentifier == 'com.anthropic.claudefordesktop'" 2>/dev/null
```

If not found, tell the user:
> Claude Code Desktop no está instalado. Descárgalo desde: https://claude.ai/download — instálalo y luego vuelve a correr /setup-sandbox.

Do not continue until Claude Code is confirmed installed (since the user is already talking to Claude Code, this check is mostly a safeguard).

### 6. Handle permission errors

If any installation step fails with a permissions error:
1. Clearly explain which tool failed and why
2. Tell the user exactly what permission is needed
3. Provide the message to send to IT:
   > "Necesito permisos para instalar [tool] en mi Mac. Es necesario para el proyecto de Humand. El comando que falló fue: [command]"
4. Pause and wait — do not continue with remaining steps

### 7. Configure GitHub access token

This token allows the sandbox to install private Humand packages from GitHub Packages (`material-hu`, `humand-biome-config`).

Ask the user:
> Para que el sandbox pueda acceder a los componentes de diseño de Humand, necesito un token de acceso. Lo podés encontrar en [link a Notion donde vive el token]. Copialo y pegalo acá.

Once you have the token, run the appropriate script for the OS detected in step 1. The script lives in the `scripts/` folder next to this SKILL.md — use the absolute path when invoking it.

**Mac:**
```bash
bash "<skill-dir>/scripts/setup-github-token.sh" "<token>"
```

**Windows (PowerShell):**
```powershell
powershell -ExecutionPolicy Bypass -File "<skill-dir>\scripts\setup-github-token.ps1" -Token "<token>"
```

The script:
1. Saves the token to `~/.humand/github-token` with restricted permissions
2. Adds (or replaces) the `@humanddev` registry entry in `~/.npmrc` without touching other lines

Do NOT replicate these steps manually. If the script fails, report the error to the user as-is.

If the user doesn't have the token yet:
> No hay problema, podés saltearlo por ahora. El sandbox va a funcionar igual, pero Claude no va a poder ver los componentes de material-hu como referencia. Cuando lo tengas, corré `/setup-sandbox` de nuevo y va a quedar configurado.

### 8. Summary

Read the JSON printed by the script and tell the user what was installed vs. what was already there:

> ✅ Entorno listo. Esto es lo que se configuró:
> - nvm instalado (nuevo)
> - Node 24.11.1 instalado (nuevo)
> - git ya estaba instalado
>
> Ya podés correr `/bootstrap-react-project` para crear tu primer proyecto.

