Salon_Assistant/docs/INSTALL.md

Install

Status: Stages S0–S7 implemented.

Stages

Stage	Where	Outcome	Status
S0	Human	Host per 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	✅ Implemented

Platform commands (normative)

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

---

S0: Host baselining

Follow 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

./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

./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

./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

./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

./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

./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)

./scripts/install.sh
# or
make install

Run S3–S5 only (attach path)

./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 for owner-facing setup after full install.
• See design/scenarios.md (S1–S5) for operational scenarios.
• See OPERATIONS.md for day-2 operator commands.

S7: Owner messaging + operator connect scripts

After install stages S0–S6 are complete, the operator connects the owner's SaaS integrations and messaging channels.

Safety model: --dry-run is the default. Use --apply to perform mutations. All mutations use nemohermes / openshell. No parallel control API.

Connect dispatcher

./scripts/connect.sh --help
./scripts/connect.sh status
./scripts/connect.sh all --dry-run    # preview all targets
./scripts/connect.sh all --apply      # execute all targets

Per-target connect

# Name / profile (sandbox identity)
./scripts/connect.sh name --dry-run
./scripts/connect.sh name --apply

# Messaging channels (WhatsApp, Email, Telegram)
./scripts/connect.sh channels --target whatsapp --dry-run
./scripts/connect.sh channels --target whatsapp --apply
./scripts/connect.sh channels --target telegram --apply
./scripts/connect.sh channels --target email --apply

# Square (remote MCP — read-only tools)
./scripts/connect.sh square --dry-run
./scripts/connect.sh square --apply

# QuickBooks Online (local MCP — read-only tools)
./scripts/connect.sh quickbooks --dry-run
./scripts/connect.sh quickbooks --apply

# Vagaro (REST + webhooks)
./scripts/connect.sh vagaro --dry-run
./scripts/connect.sh vagaro --apply

Make targets

make connect              # show connect help
make connect-status       # show connection status
make connect-name         # name / profile (--dry-run)
make connect-channels     # channels (--dry-run)
make connect-square       # Square (--dry-run)
make connect-quickbooks   # QuickBooks (--dry-run)
make connect-vagaro       # Vagaro (--dry-run)
make connect-all          # all targets (--dry-run)

Connection state

State is stored in .local/capability_state.json (gitignored). Status values:

Status	Meaning
connected	Integration is active and verified
skipped	Operator or owner chose to skip
later	Planned for future setup
error	Connection attempt failed — needs attention
offline	Not yet connected — using fixtures

Capability report

After connecting, export a capability report compatible with the setup-education skill:

# Via the connect state library (source in a script)
source scripts/lib/connect_state.sh
export_capability_report > /tmp/capability_report.json

Owner-safe messaging

The owner never receives terminal, Docker, or editor instructions. All connect work is done by the operator using these scripts. The owner interacts with the assistant through connected channels (WhatsApp, Email, Telegram) and completes vendor browser steps (OAuth consent, BotFather, etc.) on their own devices.

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.