structure: sync design/DESIGN_PLAN.md

2026-07-27 16:08:07 +00:00
parent 08fcd8b9c6
commit 191b5f0002
1 changed files with 343 additions and 0 deletions
@@ -0,0 +1,343 @@
+# 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.