# SPEC: fix-install-update-flow

## Context

Five issues in the install/update flow need fixing: hardcoded git URL, `.venv` cwd bug, Windows venv path, hook copy-vs-symlink inconsistency, and missing `--version` smoke test.

## Non-Goals (deferred)

- Windows `schtasks` schedule installation testing -> v1.1 (needs Windows CI)
- `register-guards.sh` changes -> not in scope (guards work correctly)
- Automated update of copied hooks -> v1.1 (documented as "re-run install-hooks.sh")

## Requirements

### R1 -- User-supplied git URL (D11)

`install.sh` must accept the git URL as `$1` and refuse if absent:

```bash
GIT_URL="${1:-}"
if [ -z "$GIT_URL" ]; then
  echo "ERROR: Git URL required."
  echo "Usage: ./install.sh <git-url>"
  echo "Example: ./install.sh https://github.com/user/automaton.git"
  echo ""
  echo "The framework is cloned to ~/.automaton. Choose your URL carefully"
  echo "as it cannot be changed later without reinstalling."
  exit 1
fi
git clone "$GIT_URL" "$FRAMEWORK_DIR"
```

Remove the hardcoded `http://10.37.0.86:3003/hermes/automaton` URL.

### R2 -- Fix `.venv` cwd bug

Move the venv setup inside the `else` block (after clone), using `$FRAMEWORK_DIR`:
```bash
# --- Python deps (idempotent, in framework dir) ---
if [ ! -d "$FRAMEWORK_DIR/.venv" ]; then
  python3 -m venv "$FRAMEWORK_DIR/.venv"
fi
```

Use the venv's Python directly with `-m pip` (platform-aware path, see R3).

### R3 -- Windows venv path

Detect the venv Python path based on platform:
```bash
if [ -f "$FRAMEWORK_DIR/.venv/bin/python3" ]; then
  VENV_PY="$FRAMEWORK_DIR/.venv/bin/python3"
elif [ -f "$FRAMEWORK_DIR/.venv/Scripts/python.exe" ]; then
  VENV_PY="$FRAMEWORK_DIR/.venv/Scripts/python.exe"
else
  VENV_PY="python3"
fi
"$VENV_PY" -m pip install --quiet --upgrade pip
"$VENV_PY" -m pip install --quiet -r "$FRAMEWORK_DIR/requirements.txt"
```

### R4 -- Hook copy-vs-symlink consistency

Change `update.sh` and `upgrade.sh` to use `cp` instead of `ln -sf`, matching `install-hooks.sh`:

In `update.sh`, replace:
```bash
ln -sf "$HOOK_SRC" "$HOOK_DST"
```
with:
```bash
cp "$HOOK_SRC" "$HOOK_DST"
chmod +x "$HOOK_DST"
```

In `upgrade.sh`, replace all `ln -sf` for hooks with `cp` + `chmod +x`.

### R5 -- `--version` smoke test

Add at the end of `install.sh` (inside the `else` block, after all setup):
```bash
# Verify framework is working
python3 "$FRAMEWORK_DIR/scripts/status.py" --version || echo "WARNING: status.py --version failed"
```

### R6 -- Tests

Write `tests/test_install_update_flow.py` with:

1. `test_install_sh_requires_git_url` -- verify install.sh checks for `$1` and refuses if empty
2. `test_install_sh_no_hardcoded_url` -- verify the hardcoded IP URL is gone
3. `test_install_sh_venv_in_framework_dir` -- verify `.venv` setup uses `$FRAMEWORK_DIR`
4. `test_install_sh_has_version_check` -- verify install.sh calls `status.py --version`
5. `test_install_sh_windows_venv_path` -- verify install.sh handles `.venv/Scripts/python.exe`
6. `test_update_sh_uses_cp_for_hooks` -- verify update.sh uses `cp` not `ln -sf`
7. `test_upgrade_sh_uses_cp_for_hooks` -- verify upgrade.sh uses `cp` not `ln -sf`
8. `test_install_hooks_sh_uses_cp` -- verify install-hooks.sh still uses `cp` (regression guard)

### R7 -- Documentation

- `CHANGELOG.md` under `[unreleased]`
- `README.md` -- update install instructions to show `./install.sh <git-url>`

## Verification

- `bash -n scripts/install.sh scripts/update.sh scripts/upgrade.sh` -- syntax check
- `python3 -m pytest tests/test_install_update_flow.py -v`
- `python3 -m pytest tests/ -q` -- full suite must remain green