Salon_Assistant/design/DESIGN_PLAN.md

# Design & Implementation Plan: Lumina (Salon / Spa Hermes Assistant)

**Document type:** Architecture and implementation plan, grounded in NVIDIA NemoClaw and Nous Hermes platform behavior.  
**Audience:** Operators deploying from this git repository on a baselined Linux host (cloud VM, bare metal; WSL optional).  
**Authorization:** Code only after explicit **build** / **implement**.  
**Canonical copies:** this file under workspace `Salon_Assistant/` and Gitea `Ty_Tech/Salon_Assistant`.

**Normative platform docs:**

- [NemoClaw Hermes architecture](https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/reference/architecture.md)
- [Understand Runtime Changes (Hermes)](https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/manage-sandboxes/configure-sandboxes/understand-runtime-changes.md)
- [Manage Messaging Channels](https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/manage-sandboxes/messaging-channels/manage-messaging-channels)
- [Hermes Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)
- [Hermes Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) · [MCP config](https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference) · [Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models)

**Platform-first rule:** Use `nemohermes` / `openshell` for all sandbox, policy, credential, channel, inference, and config mutations. Product scripts wrap those CLIs. Do not invent a parallel control API.

---

## 1. Product frame

Lumina packages a **minimal NemoClaw Hermes sandbox** for a salon/spa owner-operator, delivered as a **Docker-based** deployment from this repository.

| Plane | Role |
|-------|------|
| Scheduling | Owner’s Vagaro and/or Square |
| Books | Owner’s QuickBooks Online (read-heavy) |
| Owner messaging | WhatsApp, Email, Telegram |
| Client / social drafts | Draft only; owner sends/posts |
| Social media craft | Owner photos/video + vision aux |
| Identity | Assistant name = sandbox/profile name |
| Setup | Guided connection of the owner’s SaaS after install |
| Control | OpenShell policy + Hermes security + skill contracts |
| Ops | Install, automatic updates (on by default), doctor, logs |

**Non-goals:** agent payments; silent send/publish; iMessage bot; holographic memory; multi-profile staff product; replacing NemoClaw CLIs with a custom API server.

---

## 2. Research decision: host automation (no custom control API)

### 2.1 Question

Does Lumina need a bespoke control API so the owner avoids terminal work?

### 2.2 Research findings

NemoClaw already provides host-side, sealed operations for Hermes:

| Operation | Platform command / mechanism |
|-----------|------------------------------|
| Create / recreate sandbox | `nemohermes onboard` (with agent package from this repo) |
| Status / logs | `nemohermes <name> status`, `logs` |
| Snapshot / rebuild | `nemohermes <name> snapshot create`, `rebuild` |
| Inference route | `nemohermes inference set` (patches `/sandbox/.hermes/config.yaml` with trust anchors; typically no rebuild) |
| Supported Hermes config keys | `nemohermes <name> config set` (sealed transaction; do not hand-edit in-sandbox config) |
| Network policy | `openshell policy set`, `nemohermes <name> policy-add` / `policy-remove` |
| Messaging channels | `nemohermes <name> channels add` / stop; rebuild when required by runtime matrix |
| Credentials | OpenShell **provider store**; L7 injects secrets; sandbox sees placeholders |
| Shields for mutations | `shields down` / `shields up` around host config writes when lockdown is active |
| Gateway | `nemohermes <name> gateway restart` when startup-bound config changes |

Hermes itself blocks unsafe self-edits (`write_file`/`patch` denylist for `.env`, credentials, etc.; optional `HERMES_WRITE_SAFE_ROOT`). That is intentional. Configuration is supposed to come from **host NemoClaw commands**, not from the model editing files.

### 2.3 Decision

**No bespoke control API.**

All privileged mutations are performed by **product host scripts** that invoke `nemohermes` and `openshell` non-interactively. Owner-facing chat never runs those scripts; it only:

- Explains browser/vendor steps the owner can do (BotFather, OAuth consent, etc.)
- Collects values into a **host-side connect helper** run by the **operator** at install/connect time, or into NemoClaw’s documented credential/channel flows
- Reports success/failure in plain language

| Actor | Interface |
|-------|-----------|
| Technical operator (once or rare) | `./scripts/install.sh`, `./scripts/connect-*.sh`, `./scripts/upgrade.sh`, `./scripts/doctor.sh` → all call platform CLIs |
| Salon owner | WhatsApp / Email / Telegram only; vendor websites for OAuth/bots |

If a connect step requires a secret, the **operator script** prompts on the host (or uses NemoClaw’s reviewed messaging secret helpers during onboard)—never “open a terminal and run nano” in the owner’s chat.

---

## 3. Hermes as NemoClaw-managed infrastructure

### 3.1 Topology

```text
Host: nemohermes CLI, openshell CLI, Docker, product scripts, ~/.nemoclaw registry
  → OpenShell gateway (credentials, L7 proxy, policy, sandbox lifecycle)
    → Sandbox container (Hermes + NemoClaw integration)
         config: /sandbox/.hermes/config.yaml + .env (trust-anchored)
         skills, sessions, memory under /sandbox/.hermes
         egress only via policy; inference via gateway placeholders
```

### 3.2 Single profile (MVP)

One sandbox/profile. Introduction sets the **assistant name**, used as the NemoClaw sandbox name / display identity (within platform naming rules). Default name if skipped. Rename is a reconnect/settings operation via host scripts—not an upgrade side effect.

### 3.3 What the product configures (via platform)

| Concern | How |
|---------|-----|
| Main model | OpenShell inference provider + `nemohermes inference set`; endpoint may be outside Docker |
| Aux vision | Hermes `auxiliary.vision` in generated config; required; smoke-tested |
| Other aux | Default to same base/main endpoint |
| MCP servers | `mcp_servers` in managed config with `tools.include` / `exclude` |
| Channels | `nemohermes … channels add` + allowlists; rebuild when matrix requires |
| Skills | Only Lumina pack synced into sandbox skills paths |
| Policy | Repo overlays merged → `openshell policy set` / policy-add |
| Approvals / tools | Production profile: essentials toolsets; no owner dependency on terminal approvals |

### 3.4 Runtime change discipline

Follow NemoClaw’s Hermes matrix: inference often hot; channels often rebuild; never hand-edit in-sandbox config expecting trust—always host sealed commands.

---

## 4. Docker packaging and install stages

| Stage | Location | Outcome |
|-------|----------|---------|
| S0 | Human | Host per `docs/DEPLOYER_HOST.md` |
| S0b | Host script | Docker installed if missing |
| S1 | Host script | Repo env, `.env` |
| S2 | Host script | Model + aux vision config; vision smoke |
| S3–S5 | Host script → Compose / nemohermes | Stack + sandbox + policy + skills |
| S6 | Host script | Doctor green |
| S7 | Owner messaging + operator connect scripts | Name assistant; connect **their** SaaS/channels |

Host vs container: host runs bootstrap/install/upgrade/doctor and `nemohermes`/`docker compose`; containers run gateway, sandbox, local MCP when needed, webhooks.

---

## 5. Owner-safe messaging (no terminal literacy)

- Owner never receives shell, Docker, or editor instructions.  
- Hermes write protections stay on; config changes use `nemohermes` from host scripts.  
- SOUL/setup skills forbid “run this command on your PC” answers.  
- Failures: plain-language owner message; technical detail only in operator doctor logs.

---

## 6. MCP and SaaS integration

| Path | Technology |
|------|------------|
| Agent ↔ SaaS | MCP when available: **remote preferred**, **local only if necessary** |
| Scripts / CI / health | REST or fixtures |

| Integration | How it runs | Agent allow (summary) | Deny (summary) |
|-------------|-------------|----------------------|----------------|
| **Square** | Vendor **remote** MCP | Bookings, customers, catalog, inventory/location reads | Payments, refunds, cards, checkout, payouts |
| **QuickBooks Online** | **Local** MCP process managed by Compose on the **same Docker network as Hermes** (stdio or network-attached per pinned Hermes MCP client support) | Reports; search/get invoices, bills, vendors, customers; company info | create_payment, bill_payment, money movement; write/update/delete disabled for MVP |
| **Vagaro** | No public MCP — REST + webhooks in our services | Appointments, clients, services, staff | No scrape |
| **WhatsApp / Telegram / Email** | Hermes channels via NemoClaw channel commands | Owner ↔ agent | Client outbound draft-first |

Connection walkthrough: browser/vendor UI for human steps → operator `connect-*.sh` registers providers/MCP/policy via platform CLIs → health → capability report (connected | skipped | later | error).

---

## 7. Deterministic execution vs model inference

This section exists to force an implementable boundary: **what must be code** vs **what may be the LLM**, so install/upgrade/policy never depend on model compliance and so skills stay testable without GPUs.

| Concern | Deterministic (code / CLI) | Inference (main or vision aux) |
|---------|----------------------------|--------------------------------|
| Install Docker, Compose, pins | Yes | No |
| `nemohermes onboard`, policy set, channels add, inference set, snapshot, rebuild | Yes | No |
| Provider/MCP process start, health probes | Yes | No |
| SaaS JSON → domain objects; stock thresholds; appointment gap math | Yes | No |
| Template fill for standard SMS/email skeletons | Yes | Optional paraphrase |
| “What’s important on my board today?” | Facts from tools | Ranking and wording |
| Draft tone in owner’s voice | Style pack constraints | Generation |
| Photo/video understanding | Media validation | Vision aux |
| Refuse pay / silent send / publish | OpenShell + skill hard fail | Model should refuse; not relied on alone |
| Confirm-to-remember persistence | Write only after structured confirm | Propose text to remember |
| Upgrade pull/migrate/recreate | Yes | No |

Unit tests cover the deterministic column without a live model. Integration tests may use a cheap model for dialogue paths.

---

## 8. Software updates

**Owner:** updates are invisible; no participation required.  
**Default:** automatic updates **on** (scheduled host job). Operator may disable. Manual upgrade always available.

### 8.1 How

Host `./scripts/upgrade.sh` orchestrates everything:

1. `nemohermes <name> snapshot create` when available  
2. Record release pins; optional volume backup  
3. Fetch product release (git tag / image digests)  
4. Non-interactive only — no Hermes interactive update/setup wizards  
5. Compose pull/build/recreate **keeping volumes**  
6. Run state migrations if schema version changed  
7. Re-apply policy via `openshell` / `nemohermes policy-*`  
8. Re-assert inference/aux via `nemohermes inference set` / config set from `.env`  
9. Gateway restart if required by platform matrix  
10. Doctor; write operator upgrade journal only  

### 8.2 Suppressing Hermes interactive update during product upgrade

| Risk | Mitigation |
|------|------------|
| Interactive `hermes update` | Never invoked; versions pinned by product release |
| Startup config wizards | Config pre-written; non-interactive entrypoint |
| Agent-triggered host upgrade | No tools/skills for that; no docker.sock to owner agent |
| Concurrent sealed config writes | Serialize; honor shields/busy; retry |

### 8.3 Update content vectors (full list)

| # | Vector | Source | Upgrade action |
|---|--------|--------|----------------|
| 1 | This product git repo | Release tags | Fetch/checkout |
| 2 | Host scripts (install/upgrade/doctor/connect) | Repo | Replace |
| 3 | Docs | Repo | Replace |
| 4 | Compose files | Repo | Replace + recreate |
| 5 | Product images (if published) | Registry digests | Pull |
| 6 | NemoClaw CLI pin | Release manifest | Host install to pin |
| 7 | OpenShell CLI/gateway pin | Compatible pin | Host/bootstrap |
| 8 | Sandbox / Hermes agent image | Blueprint/image pin | Rebuild/recreate as required |
| 9 | Hermes runtime inside image | Image | With image |
| 10 | NemoClaw Hermes integration/plugin | Image/blueprint | With image |
| 11 | Lumina skills | Repo → sandbox | Sync |
| 12 | Default identity templates | Repo | Merge; never clobber owner name/profile |
| 13 | Owner profile, style, notes | Volume | Persist + migrate |
| 14 | Hermes sessions/state DB | Volume | Persist + backup major |
| 15 | Managed config.yaml / placeholders | Sealed host writes | Regenerate from state + templates |
| 16 | OpenShell provider secrets | Gateway store | Persist |
| 17 | Policy base + overlays | Repo | Merge + apply |
| 18 | Enabled policy presets | Connection state | Re-apply |
| 19 | Square remote MCP registration | Managed mcp_servers | Re-assert + health |
| 20 | QBO local MCP package pin | Release pin | Upgrade process + restart |
| 21 | Vagaro webhook service | Compose | Replace |
| 22 | Channel adapters | Platform channels | Rebuild if required |
| 23 | Channel allowlists | Onboard state | Persist |
| 24 | Inference main route | OpenShell + hermes config | inference set from .env |
| 25 | Auxiliary model slots | hermes config | Regenerate defaults unless overridden |
| 26 | Dashboard/API forwards | openshell forward | Re-bind after restart |
| 27 | Fixtures | Repo | Replace; not live connections |
| 28 | Migrations | Repo migrations/ | Run by version |
| 29 | Auto-update timer unit | Host systemd/cron | **Installed and enabled by default** |
| 30 | Host Docker Engine | Bootstrap policy | Separate documented path |

### 8.4 Instrumentation

Operator-only events: `upgrade.started|step|migration|policy|service|doctor|finished|failed` under `state/upgrade/`.

### 8.5 Rollback

Previous pins + volumes; `upgrade.sh --rollback`; doctor.

---

## 9. Observability (runtime)

| Level | Default | Content |
|-------|---------|---------|
| production | On | Redacted events, errors, health, boundary/memory audit |
| debug | Off | Tool names, timings, status codes |
| trace | Off | Prompts (dev only) |

Sources: `nemohermes logs`, `docker compose logs`, volume paths. CI uses assertions on outputs, not a live trace backend.

---

## 10. Repository layout (implementation targets)

| Path | Purpose |
|------|---------|
| `docs/DEPLOYER_HOST.md`, `INSTALL.md`, `UPGRADE.md`, `HERMES_MODELS.md`, `ARCHITECTURE.md`, `POLICY.md`, `SETUP_UX.md`, provider docs | Operator SSOT |
| `scripts/bootstrap.sh`, `install/`, `upgrade.sh`, `doctor.sh`, `connect-*.sh` | Host wrappers around Docker + `nemohermes`/`openshell` |
| `docker-compose.yml`, Dockerfiles | Runtime |
| `policy/openshell/` | Policy sources |
| `agents/hermes/` | Manifest, identity templates, model/MCP config fragments for onboard |
| `skills/`, providers, fixtures | Product behavior |
| `design/use-cases.md` | Use-case catalog SSOT |
| `observability/`, `migrations/`, `tests/` | Events, upgrades, quality |

---

## 11. Implementation workstreams

| # | Workstream |
|---|------------|
| W1 | Host baselining + Docker bootstrap |
| W2 | Compose + volumes aligned to NemoClaw/Hermes paths |
| W3 | Policy overlays + apply via platform CLIs |
| W4 | Domain, fixtures, skills |
| W5 | Agent package: one named profile, main/aux models, MCP fragments |
| W6 | Non-interactive install (`nemohermes onboard`, etc.) |
| W7 | `connect-*.sh` + owner-safe chat guidance (no shell recipes) |
| W8 | WhatsApp, Email, Telegram via channel commands |
| W9 | Square remote MCP allowlist |
| W10 | QBO local MCP on Compose network + tool filters |
| W11 | Vagaro REST/webhooks |
| W12 | Social multimodal |
| W13 | Memory confirm/forget |
| W14 | Runtime observability |
| W15 | Auto-update on by default + full vector upgrade/rollback |
| W16 | CI |

---

## 12. Success criteria

- [ ] All mutations via `nemohermes`/`openshell` + scripts; no parallel control API  
- [ ] Hermes write-safety preserved; owner never gets terminal instructions  
- [ ] Docker-first; Docker installed if missing; external model OK  
- [ ] One profile; intro name = sandbox/profile name  
- [ ] MCP remote-prefer / local-necessary with concrete allow/deny  
- [ ] Auto-update on by default; owner-transparent; vectors enumerated  
- [ ] Parent upgrade non-interactive; no Hermes self-update UX  
- [ ] Det vs inference matrix implemented in tests and skills  
- [ ] Workstreams W1–W16 deliverable  

---

## 13. Non-goals

- Agent payments; silent send/publish  
- Custom control API replacing NemoClaw CLIs  
- Owner-facing upgrade UX  
- Multiple profiles in MVP  
- Unrestricted payment MCP tools  

---

## 14. Repository and design pack

| Path | Role |
|------|------|
| Workspace seed | `Salon_Assistant/` in the ops workspace (product seed) |
| Gitea | `Ty_Tech/Salon_Assistant` via **gitea_vps** only |
| Use cases SSOT | `design/use-cases.md` |
| Scenarios | `design/scenarios.md` |
| Decisions | `design/DECISIONS.md` |

Implementation still requires an explicit **build** / **implement** order.