Salon_Assistant/design/use-cases.md

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