# Local Dev Setup

How to maintain a local Muse development environment that survives install/uninstall testing.

## The problem

The `curl | sh` installer creates a venv at `~/.local/share/muse/venv` and symlinks
`~/.local/bin/muse` into it. Running `uninstall.sh` wipes that venv. If your dev install
lives in the same venv, it gets wiped too. Running `pip install -e` against the system pip
doesn't help — the `muse` binary uses the venv pip, not the system one.

The fix is two separate setups with `~/bin` taking PATH priority over `~/.local/bin`.

## Dev setup (one-time)

```sh
# Create a dedicated dev venv in the muse repo
python3.14 -m venv ~/ecosystem/muse/.venv

# Editable install — any change to ~/ecosystem/muse is instantly live
~/ecosystem/muse/.venv/bin/pip install -e ~/ecosystem/muse

# Symlink into ~/bin (takes PATH priority over ~/.local/bin)
mkdir -p ~/bin
ln -sf ~/ecosystem/muse/.venv/bin/muse ~/bin/muse
```

Then ensure `~/bin` comes **after** `~/.local/bin` in your `~/.zshrc` so it takes precedence
(last `export PATH=` wins):

```sh
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/bin:$PATH"   # ← must be last so ~/bin wins
```

After `source ~/.zshrc`, `which muse` should return `~/bin/muse`.

## Verifying the dev setup

```sh
which muse
# → /Users/gabriel/bin/muse

~/ecosystem/muse/.venv/bin/python3 -c "import muse; print(muse.__file__)"
# → /Users/gabriel/ecosystem/muse/muse/__init__.py
```

The second check confirms the venv resolves `muse` to the live source, not a cached sdist.

## Testing install / uninstall

The default installer targets `~/.local/share/muse/venv` and `~/.local/bin/muse`.
Since `~/bin/muse` takes PATH priority, the dev setup is invisible to the installer
and survives uninstall cleanly.

```sh
# Install a release build (uses ~/.local/share/muse/venv — not your dev venv)
curl -fsSL https://staging.musehub.ai/install.sh | sh

# Test it (use full path since ~/bin/muse shadows it in PATH)
~/.local/bin/muse --version

# Uninstall (wipes ~/.local/share/muse/venv and ~/.local/bin/muse — dev venv untouched)
curl -fsSL https://staging.musehub.ai/uninstall.sh | sh

# Confirm dev setup still works
muse --version   # resolves to ~/bin/muse → ~/ecosystem/muse/.venv
```

To test against prod instead of staging, swap the URL:

```sh
curl -fsSL https://musehub.ai/install.sh | sh
```

## After shipping a new muse build

When a new sdist is uploaded to staging, test the full install/uninstall cycle:

1. `curl -fsSL https://staging.musehub.ai/install.sh | sh` — installs release build
2. `~/.local/bin/muse --version` — confirm version matches what was shipped
3. Run any smoke tests against `~/.local/bin/muse`
4. `curl -fsSL https://staging.musehub.ai/uninstall.sh | sh` — clean up
5. `muse --version` — confirm dev setup is intact

## What the venvs contain

| Path | Purpose | Managed by |
|------|---------|------------|
| `~/ecosystem/muse/.venv` | Local dev — editable install | You (`pip install -e`) |
| `~/.local/share/muse/venv` | Release testing | `install.sh` / `uninstall.sh` |

`~/.muse/` (identity store, local repos) is never touched by either script.