From 6ac73dc4e213faa1682cd8cdf0a64c4882093b6c Mon Sep 17 00:00:00 2001 From: Ty Date: Mon, 27 Jul 2026 16:11:00 +0000 Subject: [PATCH] structure: move DESIGN_PLAN to design/ --- docs/DESIGN_PLAN.md | 343 -------------------------------------------- 1 file changed, 343 deletions(-) delete mode 100644 docs/DESIGN_PLAN.md diff --git a/docs/DESIGN_PLAN.md b/docs/DESIGN_PLAN.md deleted file mode 100644 index 58f6dba..0000000 --- a/docs/DESIGN_PLAN.md +++ /dev/null @@ -1,343 +0,0 @@ -# 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 status`, `logs` | -| Snapshot / rebuild | `nemohermes snapshot create`, `rebuild` | -| Inference route | `nemohermes inference set` (patches `/sandbox/.hermes/config.yaml` with trust anchors; typically no rebuild) | -| Supported Hermes config keys | `nemohermes config set` (sealed transaction; do not hand-edit in-sandbox config) | -| Network policy | `openshell policy set`, `nemohermes policy-add` / `policy-remove` | -| Messaging channels | `nemohermes 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 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 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.