17 KiB
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
- Understand Runtime Changes (Hermes)
- Manage Messaging Channels
- Hermes Security
- Hermes Configuration · MCP config · 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
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
nemohermesfrom 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:
nemohermes <name> snapshot createwhen available- Record release pins; optional volume backup
- Fetch product release (git tag / image digests)
- Non-interactive only — no Hermes interactive update/setup wizards
- Compose pull/build/recreate keeping volumes
- Run state migrations if schema version changed
- Re-apply policy via
openshell/nemohermes policy-* - Re-assert inference/aux via
nemohermes inference set/ config set from.env - Gateway restart if required by platform matrix
- 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.