From 41b07921f5ffcd6a4553e7a86ed6de83be28cbe1 Mon Sep 17 00:00:00 2001 From: Ty Date: Mon, 27 Jul 2026 15:47:47 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20sync=20design=20pack=20=E2=80=94=20desi?= =?UTF-8?q?gn/use-cases.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- design/use-cases.md | 276 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 design/use-cases.md diff --git a/design/use-cases.md b/design/use-cases.md new file mode 100644 index 0000000..788cc61 --- /dev/null +++ b/design/use-cases.md @@ -0,0 +1,276 @@ +# 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 |