From db053d0b10220670e2c4636f7c4a7ff958e2a57c Mon Sep 17 00:00:00 2001 From: Ty Date: Mon, 27 Jul 2026 15:47:49 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20sync=20design=20pack=20=E2=80=94=20desi?= =?UTF-8?q?gn/scenarios.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- design/scenarios.md | 199 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 design/scenarios.md diff --git a/design/scenarios.md b/design/scenarios.md new file mode 100644 index 0000000..6b27984 --- /dev/null +++ b/design/scenarios.md @@ -0,0 +1,199 @@ +# Scenarios — Lumina / Salon_Assistant + +Narrative scenarios that drive design and tests. Use cases SSOT: [`use-cases.md`](use-cases.md). + +--- + +## S1. First-time operator install + +1. Operator provisions a baselined Linux host (`docs/DEPLOYER_HOST.md` when written). +2. Clones this repo; runs bootstrap → Docker installed if missing. +3. Configures external OpenAI-compatible model URL + vision aux. +4. `install` creates NemoClaw Hermes sandbox from this package, applies policy, installs skills. +5. Doctor green. +6. Owner still has not been involved. + +**Success:** Stack runs; no owner terminal work yet. + +--- + +## S2. Introduction — name the assistant + +1. Owner opens WhatsApp/Telegram/Email to the bot (or first post-install operator-facilitated intro). +2. Assistant asks what to call it. +3. Name becomes Hermes/NemoClaw profile/sandbox identity. +4. Profile intake: business, timezone, hours, priorities, hard rules. + +**Success:** Named profile; structured profile stored; no shell instructions. + +--- + +## S3. Connect Square (happy path) + +1. Educational step: what Lumina reads; never pays. +2. Owner completes Square developer/OAuth in browser. +3. Operator `connect-square` script registers remote MCP + policy overlay via `nemohermes`/`openshell`. +4. Health: sample bookings/catalog read. +5. Capability report: scheduling = connected (Square). + +**Success:** Board uses live Square; pay tools not registered. + +--- + +## S4. Connect QuickBooks (happy path) + +1. Educational step: read-only money picture. +2. Owner OAuth via Intuit; operator script starts local QBO MCP on Compose network; sealed config. +3. Health: company info + P&L or invoice search. +4. Capability report: books = connected. + +**Success:** Books snapshot works; payment tools denied. + +--- + +## S5. Connect Vagaro (happy path) + +1. API key / webhook setup in Vagaro UI. +2. Operator script configures REST provider + webhook service + policy. +3. Board reflects Vagaro appointments. + +**Success:** No scrape; deterministic provider. + +--- + +## S6. Owner cannot connect any SaaS + +1. Owner skips Vagaro, Square, QBO. +2. Channels may still work. +3. Board/books use fixtures or “offline.” +4. Every answer that would use live data labels demo/offline. + +**Success:** Educational + draft helper still useful; no silent fake live numbers. + +--- + +## S7. Channel partial outage + +1. WhatsApp connected; Email failed; Telegram skipped. +2. Owner uses WhatsApp only. +3. Capability report shows per-channel status. + +**Success:** Product usable on remaining channels. + +--- + +## S8. Morning board on WhatsApp + +1. Owner: “What’s on the book tomorrow?” +2. Deterministic fetch → model summarizes in her voice. +3. Flags pending confirmations and gaps. + +**Success:** Actionable list; sources labeled if fixtures. + +--- + +## S9. Client prep with formula overlay + +1. Owner: “Prep me for Elena.” +2. Client card from SoR + local formula/allergy notes. +3. Privacy reminder if needed. + +**Success:** Correct card; no cross-client leak. + +--- + +## S10. Draft late-running SMS + +1. Owner asks for a late message for Chris. +2. Style pack applied; `sends=false`. +3. Owner copies to Messages/WhatsApp herself. + +**Success:** Draft only; never auto-sent. + +--- + +## S11. Vendor invoice email triage + +1. Invoice-like message in inbox fixtures or mail. +2. Matched to open QBO bill or “not in books.” +3. Owner told to review; agent will not pay. + +**Success:** Clear next step; no payment path. + +--- + +## S12. Social post from before/after photo + +1. Owner sends photo on Telegram. +2. Vision aux describes; main model drafts caption package. +3. Owner posts to Instagram herself. + +**Success:** Draft package; no publish API call; vision degraded path if aux down. + +--- + +## S13. Owner asks agent to refund a client + +1. Agent refuses (skill + SOUL + no pay MCP tools + OpenShell). +2. Offers non-money help (draft apology, rebook draft). + +**Success:** Hard refuse; helpful alternative. + +--- + +## S14. Owner asks “run nano and edit config” + +1. Agent refuses shell/editor recipes. +2. Routes to supported connect/settings path or operator doctor. + +**Success:** No terminal literacy required of owner. + +--- + +## S15. Automatic software update overnight + +1. Scheduled host job runs `upgrade.sh` (on by default). +2. Snapshot, pull pins, recreate containers, migrate, policy re-apply, doctor. +3. Owner sees no chat about upgrade; possible brief reconnect blip only. + +**Success:** Invisible to owner; operator journal has events; connections preserved. + +--- + +## S16. Upgrade failure + +1. Doctor fails mid-upgrade. +2. Rollback to previous pin when possible. +3. Operator alerted via logs/journal — not owner spam. + +**Success:** Safe failure; owner data intact. + +--- + +## S17. Learn style over time + +1. Owner: “Too salesy, shorter.” +2. Agent proposes remember; owner confirms. +3. Next drafts shorter. + +**Success:** Confirm-to-learn; forget works; no silent model finetune. + +--- + +## S18. Multi-SoR honesty + +1. Floor revenue from metrics ≠ QBO P&L. +2. Weekly digest surfaces both and does not reconcile silently. + +**Success:** Transparent disagreement. + +--- + +## Test mapping (future) + +| Scenario | Automated test type | +|----------|---------------------| +| S8–S11, S13 fixtures | Unit/contract/smoke | +| S12 vision | Smoke when vision configured | +| S15–S16 | Upgrade dry-run / migration tests | +| S3–S5 | Optional integration with real sandboxes |