# Use cases — Lumina / Salon_Assistant (SSOT)

**This file is the single source of truth for product use cases.**  
Do not maintain full UC matrices in README or the design plan; cite names/families here.

**Demo persona (fixtures only):** Claire Bennett, owner-operator of a sample salon/spa. Real deployments replace this at introduction.

**Actors:**

| Actor | Role |
|-------|------|
| Owner | Salon/spa owner (primary user of the assistant) |
| Operator | Technical person who installs/upgrades the stack once |
| Front desk / stylist | Future; MVP is owner-centric |
| System | Hermes agent + deterministic scripts + NemoClaw/OpenShell |

---

## Family A — Scheduling / floor ops

### A1. Morning / day board
- **Actor:** Owner  
- **Goal:** See appointments for a day: time, client, service, staff, status, gaps, who needs confirmation.  
- **Sources:** Vagaro and/or Square (or fixtures if not connected).  
- **Outcome:** Clear board summary in chat (WhatsApp/Email/Telegram).  
- **Degraded:** Fixtures or “scheduling offline” — never silent fake live data.

### A2. Client prep card
- **Actor:** Owner / stylist on duty  
- **Goal:** Recall preferences, allergies, color formula, notes before a guest sits.  
- **Sources:** Scheduling SoR + local overlay notes (formulas may not live in SaaS).  
- **Privacy:** Do not share one client’s private details with another guest.

### A3. Draft client message
- **Actor:** Owner  
- **Goal:** Draft confirm / running-late / no-show rebook messages in owner’s voice.  
- **Constraint:** **Draft only** — owner sends (SMS/WhatsApp/email). No silent auto-send.  
- **Sources:** Templates + style pack + client contact from SoR.

### A4. Inbox triage
- **Actor:** Owner  
- **Goal:** Sort vendor vs client vs noise; flag invoices for review.  
- **Sources:** Email fixtures or connected mail later; optional match to books (open bills).  
- **Constraint:** Do not pay invoices.

### A5. Retail / supply stock
- **Actor:** Owner  
- **Goal:** Low stock / reorder list for retail, backbar, spa supplies.  
- **Sources:** Square catalog/inventory, Vagaro if available, or fixtures.  
- **Constraint:** Owner approves purchases.

### A6. Service menu
- **Actor:** Owner  
- **Goal:** List bookable services (duration, category).  
- **Sources:** Catalog / fixtures.

### A7. Availability peek
- **Actor:** Owner  
- **Goal:** “Any opening Thursday after 3 for a facial?”  
- **Sources:** Scheduling availability API or board-derived gaps (fixtures).

### A8. Propose reschedule / cancel
- **Actor:** Owner  
- **Goal:** Prepare change; confirm before write to SaaS.  
- **Constraint:** Gated write; off by default in MVP if unsafe; else owner does it in Vagaro/Square with assistant checklist.

### A9. Weekly floor metrics
- **Actor:** Owner  
- **Goal:** Completes, no-shows, rebooks, rough volume (from fixtures or SoR).  
- **Note:** May disagree with QuickBooks; surface both when books connected.

---

## Family B — Books / QuickBooks

### B1. Books snapshot
- **Actor:** Owner  
- **Goal:** “How are we doing?” — income/expense/net for a period.  
- **Source:** QBO reports (e.g. P&L) via MCP read tools; fixtures if not connected.  
- **Constraint:** Operational support, not CPA advice. **Read only.**

### B2. Open invoices (AR)
- **Actor:** Owner  
- **Goal:** Who owes the salon (suite rent, bridal deposit, packages).  
- **Source:** QBO invoices; open balance only.

### B3. Bills due (AP)
- **Actor:** Owner  
- **Goal:** What we owe vendors this week.  
- **Constraint:** Agent does **not** pay bills.

### B4. Vendor spend lookup
- **Actor:** Owner  
- **Goal:** Spend with a vendor over a period.  
- **Source:** Bills/purchases/vendor tools (read).

### B5. Inbox ↔ books match
- **Actor:** Owner  
- **Goal:** Vendor email invoice matched to open QBO bill or “not in books yet.”  
- **Constraint:** Review only; no payment.

### B6. Weekly digest + books
- **Actor:** Owner  
- **Goal:** Floor metrics plus P&L/AR/AP highlights in one answer.

### B7. Draft sales invoice
- **Actor:** Owner  
- **Goal:** Prepare invoice payload for private client / suite rental.  
- **Constraint:** Does not post/send/collect payment; owner completes in QBO.

### B8. Draft expense / bill entry
- **Actor:** Owner  
- **Goal:** Categorize a receipt into a draft bill.  
- **Constraint:** Owner posts; agent does not pay.

### B9. Customer/vendor directory assist
- **Actor:** Owner  
- **Goal:** Find QBO party; note name mismatch vs Vagaro/Square client.

### B10. Books connectivity
- **Actor:** Operator / owner setup  
- **Goal:** Health of QBO connection (company info).

### B11. Overdue AR nudge draft
- **Actor:** Owner  
- **Goal:** Collection-style message draft from open invoice + contact.  
- **Constraint:** Owner sends.

---

## Family C — Owner channels and identity

### C1. Talk to assistant on WhatsApp
- **Actor:** Owner  
- **Goal:** Day-to-day product chat on WhatsApp.  
- **MVP:** Yes.

### C2. Talk to assistant on Email
- **Actor:** Owner  
- **Goal:** Thread-based interaction by email.  
- **MVP:** Yes.

### C3. Talk to assistant on Telegram
- **Actor:** Owner  
- **Goal:** Chat via Telegram bot.  
- **MVP:** Yes.

### C4. Hermes dashboard (secondary)
- **Actor:** Operator / power user  
- **Goal:** Debug, status — not primary owner path.

### C5. Name the assistant
- **Actor:** Owner at introduction  
- **Goal:** Choose assistant name; becomes Hermes/NemoClaw profile/sandbox display name.

### C6. Owner profile intake
- **Actor:** Owner  
- **Goal:** Who I am, business, timezone, hours, staff, priorities, hard rules.  
- **Outcome:** Structured profile feeding identity/voice.

### C7. Remember / forget preferences
- **Actor:** Owner  
- **Goal:** Durable style/needs after explicit confirm; “forget that” works.  
- **Constraint:** No silent finetune; never unlocks pay/send/publish.

---

## Family D — Social / content

### D1. Social caption draft (text)
- **Actor:** Owner  
- **Goal:** Draft IG/FB-style caption from theme/brief.  
- **Constraint:** Owner posts; agent does not publish.

### D2. Media-assisted social craft
- **Actor:** Owner  
- **Goal:** Send photo/video on WhatsApp/Telegram/email; get caption, hook, hashtags, alt-text, timing tip.  
- **Sources:** Multimodal vision aux + style pack.  
- **Constraint:** Owner-supplied media only; no auto-publish; no scrape of client photos from SaaS without owner send.  
- **Degraded:** If vision offline, owner describes shot; text draft still works.

---

## Family E — Setup, education, degrade

### E1. Educational setup (post-install)
- **Actor:** Owner (+ operator for secrets/host scripts)  
- **Goal:** Lessons: profile, channels, Vagaro, Square, QBO, expectations; each ends connected | skipped | later | error.  
- **Prerequisite:** Platform install S0–S6 already done.

### E2. Connect owner’s Vagaro
- **Actor:** Owner + operator connect script  
- **Goal:** Wire **their** Vagaro (API/webhooks), not a demo tenant.

### E3. Connect owner’s Square
- **Actor:** Owner + operator  
- **Goal:** Remote MCP + allowlisted read tools; deny pay tools.

### E4. Connect owner’s QuickBooks
- **Actor:** Owner + operator  
- **Goal:** Local MCP read tools; deny payment tools.

### E5. Connect WhatsApp / Email / Telegram
- **Actor:** Owner + operator  
- **Goal:** Hermes channels via NemoClaw channel commands; allowlists.

### E6. Capability report
- **Actor:** Owner  
- **Goal:** Understand what works vs offline/fixtures in plain language.

### E7. Degraded mode when SaaS/channel missing
- **Actor:** System  
- **Goal:** Explicit status; never silent demo-as-truth.

---

## Family F — Control and boundaries

### F1. Boundary check
- **Actor:** Owner / demo  
- **Goal:** Prove no silent send, no social publish, no pay.  
- **Enforcement:** Skills + OpenShell + SOUL.

### F2. Refuse payment / bill-pay / refund
- **Actor:** System  
- **Goal:** Hard refuse even if prompted.

### F3. Refuse terminal recipes to owner
- **Actor:** System  
- **Goal:** Never tell owner to run nano/docker/shell; operator scripts + `nemohermes` only.

---

## Family G — Platform ops (operator)

### G1. Install from repo
- **Actor:** Operator  
- **Goal:** Baselined host → Docker if needed → Compose + `nemohermes onboard` → doctor green.

### G2. Automatic software update
- **Actor:** System (scheduled) / operator  
- **Goal:** Updates **on by default**, invisible to owner; `upgrade.sh` + pins + volumes + rollback.

### G3. Doctor / logs
- **Actor:** Operator  
- **Goal:** Health, production/debug/trace logs, upgrade journal.

---

## Explicit non-use-cases (out of MVP)

| Item | Reason |
|------|--------|
| Agent pay / BillPayment / refund / charge card | Product decision |
| Silent client send | Reputation |
| Silent social publish | Reputation |
| iMessage as bot channel | No clean API |
| Holographic memory | Overkill |
| Dual live write Vagaro+Square | One active scheduler connection model per plane config |
| Unofficial Vagaro scrape | Unsupported |
| Unrestricted pay-capable MCP tools on owner agent | Safety |
| Owner-driven platform upgrades | Ops model |

---

## Traceability

| Family | Primary design plan sections |
|--------|------------------------------|
| A Scheduling | Planes, SaaS adapters |
| B Books | QBO MCP, det vs inf |
| C Channels / identity | Hermes channels, single profile |
| D Social | Vision aux, media |
| E Setup | Install stages, owner-safe setup |
| F Boundaries | Policy, SOUL |
| G Ops | Updates, observability |