Salon_Assistant (Lumina)

Docker-based NemoClaw + Hermes personal ops assistant for a salon/spa owner-operator.

This directory is the product seed for the Gitea repository Ty_Tech/Salon_Assistant.

---

What this is

Lumina packages a minimal Hermes sandbox so a salon owner can ask, in plain language on WhatsApp/Email/Telegram, what's happening today — appointments, gaps, bills due, stock low — and get draft messages to clients or vendors. The assistant reads from the owner's existing SaaS (Vagaro, Square, QuickBooks Online) via MCP or REST. It never sends or publishes on the owner's behalf; it drafts, the owner decides.

All privileged mutations (sandbox, policy, credentials, channels, inference) go through nemohermes / openshell host CLIs. Product scripts wrap those CLIs. There is no custom control API.

---

How the project flows

design/                          docs/                          scripts/               skills/
(why + what)                     (how-to)                       (host wrappers)        (behavior)
  │                                │                               │                      │
  ├─ DESIGN_PLAN.md               ├─ INSTALL.md                   ├─ bootstrap.sh        ├─ daily-board/
  ├─ use-cases.md                 ├─ UPGRADE.md                   ├─ install.sh          ├─ availability/
  ├─ scenarios.md                 ├─ OPERATIONS.md                ├─ doctor.sh           ├─ client-card/
  ├─ DECISIONS.md                 ├─ SETUP_UX.md                  ├─ upgrade.sh          ├─ ...
  └─ specialty docs               └─ providers/                   └─ connect/*.sh        └─ _lib/

Narrative flow

Owner says "build"
  → Agent reads design/ (SSOT) for the slice to implement
  → Agent implements: scripts, skills, tests
  → Agent runs review + check gates
  → Code lands on a branch (commit only when asked; push only when asked)

Deployer (operator) on host
  → make bootstrap        (S0b: Docker if missing)
  → make install          (S1–S5: env, models, sandbox, policy, skills)
  → make doctor           (S6: health checks)
  → connect helpers       (S7: register owner's SaaS — pending)

Runtime
  → OpenShell gateway (credentials, L7 policy, sandbox lifecycle)
  → Hermes sandbox (skills, channels, MCP clients — allowlisted)
  → External model endpoint (inference, vision aux)

Owner chats
  → WhatsApp / Email / Telegram
  → Assistant answers from deterministic facts (tools/fixtures)
  → Model ranks and words; drafts outbound; owner sends

---

Strategy (plain language)

• Platform-first. All sandbox, policy, credential, channel, and inference mutations go through nemohermes / openshell. Product scripts wrap those CLIs. No parallel control API.
• Two actors. Technical operator runs host scripts (install, connect, upgrade, doctor). Salon owner chats only — never sees terminal, Docker, or editor instructions.
• Fixtures-first. Skills use JSON fixtures until live SaaS connect (S7 / MCP). Output always labels fixture data so the owner never sees silent fake live data.
• Draft-only outbound. The assistant drafts client/vendor messages; the owner sends or posts. No silent send, publish, or pay.
• Deterministic facts, model for wording. Code computes appointments, gaps, thresholds, and JSON→domain objects. The model ranks, paraphrases, and generates drafts within style constraints.
• No agent pay. Refused by OpenShell policy + skill hard-fail + model refusal.
• Auto-updates on by default. Owner-transparent; operator can disable. Rollback available.

---

Install stages

Stage	What	Status
S0	Host baselining (human)	✅ Procedural
S0b	Docker bootstrap	✅ Implemented
S1	.env from .env.example	✅ Implemented
S2	Model + vision config; vision smoke	✅ Implemented
S3	Stack alignment (OpenShell owns sandbox)	✅ Implemented
S4	Sandbox verify (attach) or onboard	✅ Implemented
S5	Policy overlays + skills sync	✅ Implemented
S6	Doctor (health checks)	✅ Implemented
S7	Owner connect + operator connect helpers	⏳ Pending

Full install guide: docs/INSTALL.md · Script details: scripts/README.md

---

Product planes

Plane	Role
Scheduling	Owner Vagaro and/or Square
Books	Owner QuickBooks Online (read-heavy)
Owner messaging	WhatsApp, Email, Telegram
Client / social drafts	Draft only; owner sends/posts
Social craft	Owner photos/video + vision aux
Identity & memory	Named assistant; confirmed preferences
Setup & education	Install, then connect their SaaS
Control	OpenShell policy + Hermes security + skill contracts
Observability	Logs, health, structured events, redaction

Full detail: design/planes.md

---

Doc map

Location	Purpose
design/	Product design SSOT — plan, use cases, scenarios, decisions, MCP strategy, update lifecycle
docs/	Operator runbooks — install, upgrade, providers, ops
AGENTS.md	Agent rails — execution loop, Git hygiene, orchestrator/worker split
scripts/	Host wrappers around Docker + nemohermes/openshell
skills/	Product behavior — deterministic scripts, fixtures, SKILL.md contracts

---

Implementation progress

Implementation queue: design/IMPLEMENT_QUEUE.md

Task	Slice	Status
Task 1	S0–S2 (bootstrap, env, models, vision smoke)	✅ Done
Task 2	S3–S5 (stack, sandbox, policy, skills sync)	✅ Done
Task 3	S6 (doctor health checks)	✅ Done
Task 4	A1 daily-board (fixtures-only)	✅ Done
Task 5	E1 setup-education	⏳ Next

---

Repository layout

Path	Purpose
design/	Design SSOT (plan, use cases, scenarios, decisions, planes, det-vs-inf, MCP, updates)
docs/	Operator manuals (install, upgrade, operations, providers, policy, setup UX)
scripts/	Host scripts: bootstrap, install stages, doctor, upgrade, connect helpers
skills/	Skill directories (daily-board implemented; others scaffolded) + _lib/ shared code
policy/openshell/	Policy overlays applied during S5
agents/hermes/	Agent package manifest, identity templates, config fragments
deploy/compose/	Docker Compose (optional; OpenShell owns sandbox)
data/fixtures/	JSON fixtures for skills (scheduling, books, etc.)
tests/	Unit tests for deterministic code
observability/	Structured event definitions
migrations/	State migrations for upgrades

---

Remote / agent notes

• Gitea: Ty_Tech/Salon_Assistant
• Git MCP: gitea_vps only (never gitea_mcp_for_ty or localhost Git MCP)
• Agent rails: Mandatory execution loop, local-worker split (Grok orchestrates; Primary Subagent on :8083 does product work), and Git hygiene — all in AGENTS.md. See CONTRIBUTING.md for branch/PR conventions.