277 lines
9.4 KiB
Markdown
277 lines
9.4 KiB
Markdown
# 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 |
|