docs: sync design pack — design/scenarios.md

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 |