Salon_Assistant/docs/INSTALL.md

# Install

**Status:** Stages S0–S6 implemented. S7 pending.

## Stages

| Stage | Where | Outcome | Status |
|-------|-------|---------|--------|
| S0 | Human | Host per [DEPLOYER_HOST.md](DEPLOYER_HOST.md) | ✅ Procedural |
| S0b | Host script | Docker installed if missing | ✅ Implemented |
| S1 | Host script | Repo env, `.env` from `.env.example` | ✅ Implemented |
| S2 | Host script | Main + aux vision config; vision smoke | ✅ Implemented |
| S3 | Host script | Stack alignment (compose docs; OpenShell owns sandbox) | ✅ Implemented |
| S4 | Host script | Sandbox verify (attach) or onboard (clean host) | ✅ Implemented |
| S5 | Host script | Policy overlays + skills sync via nemohermes | ✅ Implemented |
| S6 | Host script | Doctor green | ✅ Implemented |
| S7 | Owner + operator connect helpers | Name assistant; connect **their** SaaS/channels | ⏳ Pending |

## Platform commands (normative)

All mutations: `nemohermes` / `openshell` (see [design/research/platform-notes.md](../design/research/platform-notes.md)).

---

## S0: Host baselining

Follow [DEPLOYER_HOST.md](DEPLOYER_HOST.md) to prepare the host:

1. Provision a Linux host (cloud VM, bare metal).
2. Install OS updates.
3. Create a deploy user with sudo access.
4. Install `nemohermes` and `openshell` CLIs.
5. Clone this repository.

## S0b: Docker bootstrap

```bash
./scripts/bootstrap.sh
# or
make bootstrap
```

**Idempotent:** if Docker is already installed and running, the script exits immediately.

**What it checks:**
- `docker info` succeeds → skip install.
- OS family detection (Debian/Ubuntu or RHEL/Fedora).
- Installs Docker, adds user to `docker` group, verifies daemon.

## S1: Repository environment

```bash
./scripts/install/s1-env.sh
# or
make install-s1
```

**What it does:**
1. If `.env` does not exist, copies `.env.example` to `.env`.
2. Validates that all required keys are present and non-empty:
   - `LUMINA_SANDBOX` — sandbox name (default: `hermes`)
   - `LUMINA_INFERENCE_BASE_URL` — inference endpoint URL
   - `LUMINA_INFERENCE_MODEL` — model identifier
   - `LUMINA_VISION_MODEL` — vision model identifier
3. Fails with clear messages if keys are missing or empty.

**Edit `.env`** with your actual values before running S2. See `.env.example` for all keys and descriptions.

**Never commit `.env` with real secrets.** It is in `.gitignore`.

## S2: Model + vision configuration

```bash
./scripts/install/s2-models.sh
# or
make install-s2
```

**What it does:**
1. Loads `.env` and validates required keys.
2. Checks that `nemohermes` and `openshell` CLIs are available.
3. Verifies the inference endpoint is reachable (`/v1/models`).
4. If the OpenShell gateway is connected, configures the inference route via `openshell inference set`.
5. Runs the **vision smoke test**:
   - Probes `/v1/models` for `multimodal` capability tag.
   - Falls back to a minimal chat completion if capability tags are not exposed.
6. **Fails loudly** (non-zero exit) if vision capability cannot be confirmed.

**If the gateway is not yet connected:** the script validates the endpoint and skips the `openshell` write. S3+ will handle full gateway configuration.

## S3: Stack alignment

```bash
./scripts/install.sh --stage s3
# or
make install-s3
```

**What it does:**
- Documents that OpenShell manages the Hermes sandbox container.
- The product compose file (`deploy/compose/docker-compose.yml`) is optional — used only for local MCP and webhook services at S7+.
- No action needed for UAT attach path.

**Key principle:** OpenShell owns the sandbox. The product does NOT define the sandbox in `docker-compose.yml`.

## S4: Sandbox verification or onboard

```bash
./scripts/install/s4-sandbox.sh              # attach mode (default)
./scripts/install/s4-sandbox.sh --mode attach
./scripts/install/s4-sandbox.sh --mode onboard
./scripts/install/s4-sandbox.sh --mode onboard --dry-run
# or
make install-s4
```

**Attach mode (default):**
- Verifies the sandbox exists and is healthy.
- Checks that the agent package (`agents/hermes/`) is present.
- No destructive operations.

**Onboard mode (clean host):**
- Creates a new sandbox from the agent package using `nemohermes onboard`.
- If a sandbox with the same name already exists, falls back to attach mode for safety.
- Use `--dry-run` to preview without executing.

## S5: Policy overlays + skills sync

```bash
./scripts/install/s5-policy-skills.sh        # policy + skills
./scripts/install/s5-policy-skills.sh --policy-only
./scripts/install/s5-policy-skills.sh --skills-only
# or
make install-s5
```

**What it does:**
1. **Policy:** Applies the inference policy overlay from `policy/openshell/overlays/inference.yaml` via `nemohermes policy-add`. Existing balanced-tier presets (npm, pypi, huggingface, brew) are preserved.
2. **Skills:** Iterates skill directories under `skills/` (skipping `_lib`) and installs each via `nemohermes skill install`. Skills without `SKILL.md` are skipped with a warning.

**Additive only:** policy-add never removes existing presets. Skills install is idempotent.

## Run all stages (S0b–S5)

```bash
./scripts/install.sh
# or
make install
```

## Run S3–S5 only (attach path)

```bash
./scripts/install.sh --stage s3-s5
# or
make install-s3-s5
```

## After install (S0–S6)

- Verify `.env` values are correct for your environment.
- Check policy: `nemohermes <name> policy-list`
- Run health checks: `make doctor`
- See [SETUP_UX.md](SETUP_UX.md) for owner-facing setup after full install.
- See [design/scenarios.md](../design/scenarios.md) (S1–S5) for operational scenarios.
- See [OPERATIONS.md](OPERATIONS.md) for day-2 operator commands.

## UAT host notes

This repository was tested on a live host with:
- `nemohermes` v0.0.93, `openshell` v0.0.85
- Sandbox: `hermes` (default)
- Gateway: `nemoclaw` at `https://127.0.0.1:8080`
- Inference: OpenAI-compatible endpoint with multimodal model
- Docker: present and running

Scripts are idempotent on this configuration.