Seed approved structure: design SSOT, operator docs, scaffolds.

Product layout for Lumina / Salon_Assistant at 0.1.0-design. No product implementation until explicit build.
2026-07-27 09:44:35 -07:00
commit 48566993f6
108 changed files with 1813 additions and 0 deletions
@@ -0,0 +1,100 @@
+# Resolved design decisions — Lumina / Salon_Assistant
+
+Record of decisions from the planning session. Supersedes chat-only memory.
+
+---
+
+## Product
+
+| ID | Decision |
+|----|----------|
+| D-01 | Product name working title **Lumina**; repo **Salon_Assistant** under **Ty_Tech** |
+| D-02 | Demo persona Claire Bennett (fixtures only); real owner set at intro |
+| D-03 | Hermes under NemoClaw; not OpenClaw-first |
+| D-04 | No agent payments / bill-pay / refunds |
+| D-05 | Client outbound and social: **draft only**; owner sends/posts |
+| D-06 | Social media is a **first-class plane** (incl. owner photo/video craft) |
+
+---
+
+## Channels
+
+| ID | Decision |
+|----|----------|
+| D-10 | Owner MVP channels: **WhatsApp, Email, Telegram** |
+| D-11 | Hermes dashboard secondary |
+| D-12 | **iMessage** not a supported bot channel |
+| D-13 | Channels via Hermes/NemoClaw messaging — not IDE MCPs |
+
+---
+
+## SaaS and MCP
+
+| ID | Decision |
+|----|----------|
+| D-20 | Scheduling: **Vagaro and/or Square** + fixtures |
+| D-21 | Books: **QuickBooks Online** + fixtures |
+| D-22 | Agent↔SaaS: **MCP when possible**; scripts/CI use **REST/fixtures** |
+| D-23 | **Remote MCP preferred**; local MCP only if necessary |
+| D-24 | **Square:** remote MCP; allow bookings/customers/catalog/inventory reads; deny pay tools |
+| D-25 | **QBO:** local MCP on same Docker network as Hermes; read tools; deny payment tools; write/update/delete off for MVP |
+| D-26 | **Vagaro:** no public MCP → REST + webhooks |
+| D-27 | Setup teaches connecting **the owner’s** accounts, not demo tenants only |
+
+---
+
+## Platform / install
+
+| ID | Decision |
+|----|----------|
+| D-30 | **Docker-first** runtime; bootstrap installs Docker if missing |
+| D-31 | Model OpenAI-compatible endpoint **may be outside** containers |
+| D-32 | Host scripts outside containers; some automation in-container — documented split |
+| D-33 | **No bespoke control API**; all mutations via `nemohermes` / `openshell` + product scripts |
+| D-34 | Hermes write-safety stays on; config via sealed host commands |
+| D-35 | Owner never receives terminal/nano/docker instructions |
+| D-36 | One Hermes profile MVP; **intro name = profile/sandbox name** |
+| D-37 | Multimodal: **aux vision required** for media social; other aux default to base/main |
+| D-38 | Prefer platform-native ops; bespoke last resort |
+
+---
+
+## Memory / learning
+
+| ID | Decision |
+|----|----------|
+| D-40 | Base memory: profile, style pack, structured notes, skills |
+| D-41 | Confirm-to-learn / forget; no silent finetune |
+| D-42 | No holographic memory MVP |
+| D-43 | Optional curated wiki later |
+
+---
+
+## Updates / observability
+
+| ID | Decision |
+|----|----------|
+| D-50 | Automatic updates **ON by default** |
+| D-51 | Owner-transparent (no upgrade chat) |
+| D-52 | `upgrade.sh` parent process; pins, volumes, migrations, rollback |
+| D-53 | Suppress Hermes interactive update during product upgrade |
+| D-54 | Log levels: production (default), debug, trace |
+| D-55 | Optional external trace UIs not MVP |
+
+---
+
+## Documentation process
+
+| ID | Decision |
+|----|----------|
+| D-60 | Use-case SSOT: `design/use-cases.md` (this tree) |
+| D-61 | Scenarios: `design/scenarios.md` |
+| D-62 | Full architecture plan: `design/DESIGN_PLAN.md` (not under `docs/`) |
+| D-63 | Workspace seed = repo root content for Gitea check-in |
+| D-64 | Plan approval ≠ build authorization |
+
+---
+
+## Queues absorbed (historical labels)
+
+Q1 Setup UX · Q2 Educational setup/degrade/identity · Q3 Learning · Q4 Base memory · Q5 Channels MVP · Q6 Media social · Q7 UC SSOT · Q8 Minimal Hermes · Q9 Observability · P1–P6 packages · Docker/MCP/profile/update decisions above.
@@ -0,0 +1,343 @@
+# Design & Implementation Plan: Lumina (Salon / Spa Hermes Assistant)
+
+**Document type:** Architecture and implementation plan, grounded in NVIDIA NemoClaw and Nous Hermes platform behavior.  
+**Audience:** Operators deploying from this git repository on a baselined Linux host (cloud VM, bare metal; WSL optional).  
+**Authorization:** Code only after explicit **build** / **implement**.  
+**Canonical copies:** this file under workspace `Salon_Assistant/` and Gitea `Ty_Tech/Salon_Assistant`.
+
+**Normative platform docs:**
+
+- [NemoClaw Hermes architecture](https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/reference/architecture.md)
+- [Understand Runtime Changes (Hermes)](https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/manage-sandboxes/configure-sandboxes/understand-runtime-changes.md)
+- [Manage Messaging Channels](https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/manage-sandboxes/messaging-channels/manage-messaging-channels)
+- [Hermes Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)
+- [Hermes Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) · [MCP config](https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference) · [Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models)
+
+**Platform-first rule:** Use `nemohermes` / `openshell` for all sandbox, policy, credential, channel, inference, and config mutations. Product scripts wrap those CLIs. Do not invent a parallel control API.
+
+---
+
+## 1. Product frame
+
+Lumina packages a **minimal NemoClaw Hermes sandbox** for a salon/spa owner-operator, delivered as a **Docker-based** deployment from this repository.
+
+| Plane | Role |
+|-------|------|
+| Scheduling | Owner’s Vagaro and/or Square |
+| Books | Owner’s QuickBooks Online (read-heavy) |
+| Owner messaging | WhatsApp, Email, Telegram |
+| Client / social drafts | Draft only; owner sends/posts |
+| Social media craft | Owner photos/video + vision aux |
+| Identity | Assistant name = sandbox/profile name |
+| Setup | Guided connection of the owner’s SaaS after install |
+| Control | OpenShell policy + Hermes security + skill contracts |
+| Ops | Install, automatic updates (on by default), doctor, logs |
+
+**Non-goals:** agent payments; silent send/publish; iMessage bot; holographic memory; multi-profile staff product; replacing NemoClaw CLIs with a custom API server.
+
+---
+
+## 2. Research decision: host automation (no custom control API)
+
+### 2.1 Question
+
+Does Lumina need a bespoke control API so the owner avoids terminal work?
+
+### 2.2 Research findings
+
+NemoClaw already provides host-side, sealed operations for Hermes:
+
+| Operation | Platform command / mechanism |
+|-----------|------------------------------|
+| Create / recreate sandbox | `nemohermes onboard` (with agent package from this repo) |
+| Status / logs | `nemohermes <name> status`, `logs` |
+| Snapshot / rebuild | `nemohermes <name> snapshot create`, `rebuild` |
+| Inference route | `nemohermes inference set` (patches `/sandbox/.hermes/config.yaml` with trust anchors; typically no rebuild) |
+| Supported Hermes config keys | `nemohermes <name> config set` (sealed transaction; do not hand-edit in-sandbox config) |
+| Network policy | `openshell policy set`, `nemohermes <name> policy-add` / `policy-remove` |
+| Messaging channels | `nemohermes <name> channels add` / stop; rebuild when required by runtime matrix |
+| Credentials | OpenShell **provider store**; L7 injects secrets; sandbox sees placeholders |
+| Shields for mutations | `shields down` / `shields up` around host config writes when lockdown is active |
+| Gateway | `nemohermes <name> gateway restart` when startup-bound config changes |
+
+Hermes itself blocks unsafe self-edits (`write_file`/`patch` denylist for `.env`, credentials, etc.; optional `HERMES_WRITE_SAFE_ROOT`). That is intentional. Configuration is supposed to come from **host NemoClaw commands**, not from the model editing files.
+
+### 2.3 Decision
+
+**No bespoke control API.**
+
+All privileged mutations are performed by **product host scripts** that invoke `nemohermes` and `openshell` non-interactively. Owner-facing chat never runs those scripts; it only:
+
+- Explains browser/vendor steps the owner can do (BotFather, OAuth consent, etc.)
+- Collects values into a **host-side connect helper** run by the **operator** at install/connect time, or into NemoClaw’s documented credential/channel flows
+- Reports success/failure in plain language
+
+| Actor | Interface |
+|-------|-----------|
+| Technical operator (once or rare) | `./scripts/install.sh`, `./scripts/connect-*.sh`, `./scripts/upgrade.sh`, `./scripts/doctor.sh` → all call platform CLIs |
+| Salon owner | WhatsApp / Email / Telegram only; vendor websites for OAuth/bots |
+
+If a connect step requires a secret, the **operator script** prompts on the host (or uses NemoClaw’s reviewed messaging secret helpers during onboard)—never “open a terminal and run nano” in the owner’s chat.
+
+---
+
+## 3. Hermes as NemoClaw-managed infrastructure
+
+### 3.1 Topology
+
+```text
+Host: nemohermes CLI, openshell CLI, Docker, product scripts, ~/.nemoclaw registry
+  → OpenShell gateway (credentials, L7 proxy, policy, sandbox lifecycle)
+    → Sandbox container (Hermes + NemoClaw integration)
+         config: /sandbox/.hermes/config.yaml + .env (trust-anchored)
+         skills, sessions, memory under /sandbox/.hermes
+         egress only via policy; inference via gateway placeholders
+```
+
+### 3.2 Single profile (MVP)
+
+One sandbox/profile. Introduction sets the **assistant name**, used as the NemoClaw sandbox name / display identity (within platform naming rules). Default name if skipped. Rename is a reconnect/settings operation via host scripts—not an upgrade side effect.
+
+### 3.3 What the product configures (via platform)
+
+| Concern | How |
+|---------|-----|
+| Main model | OpenShell inference provider + `nemohermes inference set`; endpoint may be outside Docker |
+| Aux vision | Hermes `auxiliary.vision` in generated config; required; smoke-tested |
+| Other aux | Default to same base/main endpoint |
+| MCP servers | `mcp_servers` in managed config with `tools.include` / `exclude` |
+| Channels | `nemohermes … channels add` + allowlists; rebuild when matrix requires |
+| Skills | Only Lumina pack synced into sandbox skills paths |
+| Policy | Repo overlays merged → `openshell policy set` / policy-add |
+| Approvals / tools | Production profile: essentials toolsets; no owner dependency on terminal approvals |
+
+### 3.4 Runtime change discipline
+
+Follow NemoClaw’s Hermes matrix: inference often hot; channels often rebuild; never hand-edit in-sandbox config expecting trust—always host sealed commands.
+
+---
+
+## 4. Docker packaging and install stages
+
+| Stage | Location | Outcome |
+|-------|----------|---------|
+| S0 | Human | Host per `docs/DEPLOYER_HOST.md` |
+| S0b | Host script | Docker installed if missing |
+| S1 | Host script | Repo env, `.env` |
+| S2 | Host script | Model + aux vision config; vision smoke |
+| S3–S5 | Host script → Compose / nemohermes | Stack + sandbox + policy + skills |
+| S6 | Host script | Doctor green |
+| S7 | Owner messaging + operator connect scripts | Name assistant; connect **their** SaaS/channels |
+
+Host vs container: host runs bootstrap/install/upgrade/doctor and `nemohermes`/`docker compose`; containers run gateway, sandbox, local MCP when needed, webhooks.
+
+---
+
+## 5. Owner-safe messaging (no terminal literacy)
+
+- Owner never receives shell, Docker, or editor instructions.  
+- Hermes write protections stay on; config changes use `nemohermes` from host scripts.  
+- SOUL/setup skills forbid “run this command on your PC” answers.  
+- Failures: plain-language owner message; technical detail only in operator doctor logs.
+
+---
+
+## 6. MCP and SaaS integration
+
+| Path | Technology |
+|------|------------|
+| Agent ↔ SaaS | MCP when available: **remote preferred**, **local only if necessary** |
+| Scripts / CI / health | REST or fixtures |
+
+| Integration | How it runs | Agent allow (summary) | Deny (summary) |
+|-------------|-------------|----------------------|----------------|
+| **Square** | Vendor **remote** MCP | Bookings, customers, catalog, inventory/location reads | Payments, refunds, cards, checkout, payouts |
+| **QuickBooks Online** | **Local** MCP process managed by Compose on the **same Docker network as Hermes** (stdio or network-attached per pinned Hermes MCP client support) | Reports; search/get invoices, bills, vendors, customers; company info | create_payment, bill_payment, money movement; write/update/delete disabled for MVP |
+| **Vagaro** | No public MCP — REST + webhooks in our services | Appointments, clients, services, staff | No scrape |
+| **WhatsApp / Telegram / Email** | Hermes channels via NemoClaw channel commands | Owner ↔ agent | Client outbound draft-first |
+
+Connection walkthrough: browser/vendor UI for human steps → operator `connect-*.sh` registers providers/MCP/policy via platform CLIs → health → capability report (connected | skipped | later | error).
+
+---
+
+## 7. Deterministic execution vs model inference
+
+This section exists to force an implementable boundary: **what must be code** vs **what may be the LLM**, so install/upgrade/policy never depend on model compliance and so skills stay testable without GPUs.
+
+| Concern | Deterministic (code / CLI) | Inference (main or vision aux) |
+|---------|----------------------------|--------------------------------|
+| Install Docker, Compose, pins | Yes | No |
+| `nemohermes onboard`, policy set, channels add, inference set, snapshot, rebuild | Yes | No |
+| Provider/MCP process start, health probes | Yes | No |
+| SaaS JSON → domain objects; stock thresholds; appointment gap math | Yes | No |
+| Template fill for standard SMS/email skeletons | Yes | Optional paraphrase |
+| “What’s important on my board today?” | Facts from tools | Ranking and wording |
+| Draft tone in owner’s voice | Style pack constraints | Generation |
+| Photo/video understanding | Media validation | Vision aux |
+| Refuse pay / silent send / publish | OpenShell + skill hard fail | Model should refuse; not relied on alone |
+| Confirm-to-remember persistence | Write only after structured confirm | Propose text to remember |
+| Upgrade pull/migrate/recreate | Yes | No |
+
+Unit tests cover the deterministic column without a live model. Integration tests may use a cheap model for dialogue paths.
+
+---
+
+## 8. Software updates
+
+**Owner:** updates are invisible; no participation required.  
+**Default:** automatic updates **on** (scheduled host job). Operator may disable. Manual upgrade always available.
+
+### 8.1 How
+
+Host `./scripts/upgrade.sh` orchestrates everything:
+
+1. `nemohermes <name> snapshot create` when available  
+2. Record release pins; optional volume backup  
+3. Fetch product release (git tag / image digests)  
+4. Non-interactive only — no Hermes interactive update/setup wizards  
+5. Compose pull/build/recreate **keeping volumes**  
+6. Run state migrations if schema version changed  
+7. Re-apply policy via `openshell` / `nemohermes policy-*`  
+8. Re-assert inference/aux via `nemohermes inference set` / config set from `.env`  
+9. Gateway restart if required by platform matrix  
+10. Doctor; write operator upgrade journal only  
+
+### 8.2 Suppressing Hermes interactive update during product upgrade
+
+| Risk | Mitigation |
+|------|------------|
+| Interactive `hermes update` | Never invoked; versions pinned by product release |
+| Startup config wizards | Config pre-written; non-interactive entrypoint |
+| Agent-triggered host upgrade | No tools/skills for that; no docker.sock to owner agent |
+| Concurrent sealed config writes | Serialize; honor shields/busy; retry |
+
+### 8.3 Update content vectors (full list)
+
+| # | Vector | Source | Upgrade action |
+|---|--------|--------|----------------|
+| 1 | This product git repo | Release tags | Fetch/checkout |
+| 2 | Host scripts (install/upgrade/doctor/connect) | Repo | Replace |
+| 3 | Docs | Repo | Replace |
+| 4 | Compose files | Repo | Replace + recreate |
+| 5 | Product images (if published) | Registry digests | Pull |
+| 6 | NemoClaw CLI pin | Release manifest | Host install to pin |
+| 7 | OpenShell CLI/gateway pin | Compatible pin | Host/bootstrap |
+| 8 | Sandbox / Hermes agent image | Blueprint/image pin | Rebuild/recreate as required |
+| 9 | Hermes runtime inside image | Image | With image |
+| 10 | NemoClaw Hermes integration/plugin | Image/blueprint | With image |
+| 11 | Lumina skills | Repo → sandbox | Sync |
+| 12 | Default identity templates | Repo | Merge; never clobber owner name/profile |
+| 13 | Owner profile, style, notes | Volume | Persist + migrate |
+| 14 | Hermes sessions/state DB | Volume | Persist + backup major |
+| 15 | Managed config.yaml / placeholders | Sealed host writes | Regenerate from state + templates |
+| 16 | OpenShell provider secrets | Gateway store | Persist |
+| 17 | Policy base + overlays | Repo | Merge + apply |
+| 18 | Enabled policy presets | Connection state | Re-apply |
+| 19 | Square remote MCP registration | Managed mcp_servers | Re-assert + health |
+| 20 | QBO local MCP package pin | Release pin | Upgrade process + restart |
+| 21 | Vagaro webhook service | Compose | Replace |
+| 22 | Channel adapters | Platform channels | Rebuild if required |
+| 23 | Channel allowlists | Onboard state | Persist |
+| 24 | Inference main route | OpenShell + hermes config | inference set from .env |
+| 25 | Auxiliary model slots | hermes config | Regenerate defaults unless overridden |
+| 26 | Dashboard/API forwards | openshell forward | Re-bind after restart |
+| 27 | Fixtures | Repo | Replace; not live connections |
+| 28 | Migrations | Repo migrations/ | Run by version |
+| 29 | Auto-update timer unit | Host systemd/cron | **Installed and enabled by default** |
+| 30 | Host Docker Engine | Bootstrap policy | Separate documented path |
+
+### 8.4 Instrumentation
+
+Operator-only events: `upgrade.started|step|migration|policy|service|doctor|finished|failed` under `state/upgrade/`.
+
+### 8.5 Rollback
+
+Previous pins + volumes; `upgrade.sh --rollback`; doctor.
+
+---
+
+## 9. Observability (runtime)
+
+| Level | Default | Content |
+|-------|---------|---------|
+| production | On | Redacted events, errors, health, boundary/memory audit |
+| debug | Off | Tool names, timings, status codes |
+| trace | Off | Prompts (dev only) |
+
+Sources: `nemohermes logs`, `docker compose logs`, volume paths. CI uses assertions on outputs, not a live trace backend.
+
+---
+
+## 10. Repository layout (implementation targets)
+
+| Path | Purpose |
+|------|---------|
+| `docs/DEPLOYER_HOST.md`, `INSTALL.md`, `UPGRADE.md`, `HERMES_MODELS.md`, `ARCHITECTURE.md`, `POLICY.md`, `SETUP_UX.md`, provider docs | Operator SSOT |
+| `scripts/bootstrap.sh`, `install/`, `upgrade.sh`, `doctor.sh`, `connect-*.sh` | Host wrappers around Docker + `nemohermes`/`openshell` |
+| `docker-compose.yml`, Dockerfiles | Runtime |
+| `policy/openshell/` | Policy sources |
+| `agents/hermes/` | Manifest, identity templates, model/MCP config fragments for onboard |
+| `skills/`, providers, fixtures | Product behavior |
+| `design/use-cases.md` | Use-case catalog SSOT |
+| `observability/`, `migrations/`, `tests/` | Events, upgrades, quality |
+
+---
+
+## 11. Implementation workstreams
+
+| # | Workstream |
+|---|------------|
+| W1 | Host baselining + Docker bootstrap |
+| W2 | Compose + volumes aligned to NemoClaw/Hermes paths |
+| W3 | Policy overlays + apply via platform CLIs |
+| W4 | Domain, fixtures, skills |
+| W5 | Agent package: one named profile, main/aux models, MCP fragments |
+| W6 | Non-interactive install (`nemohermes onboard`, etc.) |
+| W7 | `connect-*.sh` + owner-safe chat guidance (no shell recipes) |
+| W8 | WhatsApp, Email, Telegram via channel commands |
+| W9 | Square remote MCP allowlist |
+| W10 | QBO local MCP on Compose network + tool filters |
+| W11 | Vagaro REST/webhooks |
+| W12 | Social multimodal |
+| W13 | Memory confirm/forget |
+| W14 | Runtime observability |
+| W15 | Auto-update on by default + full vector upgrade/rollback |
+| W16 | CI |
+
+---
+
+## 12. Success criteria
+
+- [ ] All mutations via `nemohermes`/`openshell` + scripts; no parallel control API  
+- [ ] Hermes write-safety preserved; owner never gets terminal instructions  
+- [ ] Docker-first; Docker installed if missing; external model OK  
+- [ ] One profile; intro name = sandbox/profile name  
+- [ ] MCP remote-prefer / local-necessary with concrete allow/deny  
+- [ ] Auto-update on by default; owner-transparent; vectors enumerated  
+- [ ] Parent upgrade non-interactive; no Hermes self-update UX  
+- [ ] Det vs inference matrix implemented in tests and skills  
+- [ ] Workstreams W1–W16 deliverable  
+
+---
+
+## 13. Non-goals
+
+- Agent payments; silent send/publish  
+- Custom control API replacing NemoClaw CLIs  
+- Owner-facing upgrade UX  
+- Multiple profiles in MVP  
+- Unrestricted payment MCP tools  
+
+---
+
+## 14. Repository and design pack
+
+| Path | Role |
+|------|------|
+| Workspace seed | `Salon_Assistant/` in the ops workspace (product seed) |
+| Gitea | `Ty_Tech/Salon_Assistant` via **gitea_vps** only |
+| Use cases SSOT | `design/use-cases.md` |
+| Scenarios | `design/scenarios.md` |
+| Decisions | `design/DECISIONS.md` |
+
+Implementation still requires an explicit **build** / **implement** order.
@@ -0,0 +1,18 @@
+# Design pack (product SSOT)
+
+This folder is the **product design source of truth** for Salon_Assistant / Lumina.
+
+| Document | Purpose |
+|----------|---------|
+| [DESIGN_PLAN.md](DESIGN_PLAN.md) | Architecture + implementation plan (NemoClaw/Hermes, install, MCP, updates) |
+| [use-cases.md](use-cases.md) | Use-case catalog (SSOT — do not duplicate full matrices elsewhere) |
+| [scenarios.md](scenarios.md) | Narrative scenarios for design and future tests |
+| [DECISIONS.md](DECISIONS.md) | Resolved decisions from planning |
+| [planes.md](planes.md) | Capability planes |
+| [det-vs-inf.md](det-vs-inf.md) | Deterministic code vs model inference |
+| [mcp-integrations.md](mcp-integrations.md) | Square / QBO / Vagaro / channels |
+| [updates-lifecycle.md](updates-lifecycle.md) | Software update model and vectors |
+
+Operator runbooks live under [`../docs/`](../docs/) and **link here** for design rationale.
+
+**Implementation** of code under `skills/`, `scripts/`, etc. requires an explicit **build** / **implement** order.
@@ -0,0 +1,20 @@
+# Deterministic execution vs model inference
+
+Implementable boundary so install/upgrade/policy never depend on model compliance and skills stay testable offline.
+
+| Concern | Deterministic (code / CLI) | Inference (main or vision aux) |
+|---------|----------------------------|--------------------------------|
+| Install Docker, Compose, pins | Yes | No |
+| `nemohermes onboard`, policy set, channels add, inference set, snapshot, rebuild | Yes | No |
+| Provider/MCP process start, health probes | Yes | No |
+| SaaS JSON → domain objects; stock thresholds; appointment gap math | Yes | No |
+| Template fill for standard SMS/email skeletons | Yes | Optional paraphrase |
+| “What’s important on my board today?” | Facts from tools | Ranking and wording |
+| Draft tone in owner’s voice | Style pack constraints | Generation |
+| Photo/video understanding | Media validation | Vision aux |
+| Refuse pay / silent send / publish | OpenShell + skill hard fail | Model should refuse; not relied on alone |
+| Confirm-to-remember persistence | Write only after structured confirm | Propose text to remember |
+| Upgrade pull/migrate/recreate | Yes | No |
+| Owner-facing “run this in a terminal” | **Forbidden** | SOUL/skills must not invent shell recipes |
+
+Unit tests cover the deterministic column without a live model.
@@ -0,0 +1,4 @@
+# Diagrams (optional)
+
+Place architecture diagrams (mermaid sources or images) here when useful.
+Design narrative lives in sibling markdown files.
@@ -0,0 +1,31 @@
+# MCP and SaaS integrations
+
+## Principle
+
+| Path | Technology |
+|------|------------|
+| **Agent ↔ SaaS** | **MCP when available** — **remote preferred**, **local only if necessary** |
+| **Scripts / CI / health / install** | **REST/SDK or fixtures** — no MCP required |
+
+## Inventory
+
+| Integration | MCP reality | Runtime | Agent allow (summary) | Deny (summary) |
+|-------------|-------------|---------|----------------------|----------------|
+| **Square** | Official remote MCP (`mcp.squareup.com`) | Remote MCP | Bookings, customers, catalog, inventory/location reads | Payments, refunds, cards, checkout, payouts |
+| **QuickBooks Online** | Local stdio MCP ([intuit/quickbooks-online-mcp-server](https://github.com/intuit/quickbooks-online-mcp-server)) | Local MCP process on same Docker network as Hermes | Reports; search/get invoices, bills, vendors, customers; company info | create_payment, bill_payment, money movement; write/update/delete off for MVP |
+| **Vagaro** | No public MCP | REST + webhooks in our services | Appointments, clients, services, staff | No scrape |
+| **WhatsApp / Telegram / Email** | N/A as Square-like SaaS MCP | Hermes channels via NemoClaw channel commands | Owner ↔ agent | Client outbound draft-first |
+
+## Hermes MCP registration
+
+Managed `/sandbox/.hermes/config.yaml` `mcp_servers` with `tools.include` / `tools.exclude`, applied via **host sealed** `nemohermes` config paths — not agent free-edit of config files.
+
+## Connection walkthrough (after install)
+
+1. Explain read scope and hard limits (no pay, no auto-publish).  
+2. Owner completes vendor browser/bot steps.  
+3. Operator `connect-*.sh` registers providers/MCP/policy via `nemohermes`/`openshell`.  
+4. Health check.  
+5. Capability report: connected | skipped | later | error.
+
+Owner connects **their** accounts, not demo tenants only.
@@ -0,0 +1,15 @@
+# Capability planes
+
+| Plane | Role | Systems / stores |
+|-------|------|------------------|
+| **Scheduling** | Board, clients, services, staff, stock, openings | Owner **Vagaro** and/or **Square**; fixtures for CI/demo |
+| **Books** | AR/AP/P&L visibility; draft invoice/bill text | Owner **QuickBooks Online**; fixtures |
+| **Owner comms** | Owner ↔ assistant | **WhatsApp, Email, Telegram** (Hermes channels) |
+| **Client drafts** | Outbound copy only | Templates + style pack; owner sends |
+| **Social / content** | Post packages from text + **owner media** | Multimodal (vision aux) + style pack; owner publishes |
+| **Identity & memory** | Named assistant; confirmed preferences | Profile, style pack, structured notes, skills |
+| **Setup & education** | Install then connect **their** SaaS | Installer + guided Setup UX |
+| **Control** | Hard refusals | OpenShell policy + Hermes security + SOUL/skills |
+| **Observability** | Debug without PII leaks | Logs, health, structured events, redaction |
+
+See [use-cases.md](use-cases.md) for detailed use cases per plane.
@@ -0,0 +1,26 @@
+# Platform research notes (NemoClaw / Hermes)
+
+Normative links for implementers. Prefer platform-native operations over bespoke control planes.
+
+## NemoClaw
+
+- [Hermes architecture](https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/reference/architecture.md) — CLI, blueprint, OpenShell gateway, sandbox, L7 credential injection  
+- [Understand Runtime Changes](https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/manage-sandboxes/configure-sandboxes/understand-runtime-changes.md) — what hot-reloads vs rebuild  
+- [Manage Messaging Channels](https://docs.nvidia.com/nemoclaw/latest/user-guide/hermes/manage-sandboxes/messaging-channels/manage-messaging-channels)  
+
+Key host commands: `nemohermes onboard`, `inference set`, `config set`, `policy-add`/`policy-remove`, `channels add`, `snapshot create`, `rebuild`, `shields up/down`, `gateway restart`.
+
+In-sandbox source of truth: `/sandbox/.hermes/config.yaml` + `.env` (trust-anchored; do not hand-edit expecting trust).
+
+## Hermes
+
+- [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) — write safety, approvals, gateway allowlists, MCP env filtering  
+- [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)  
+- [MCP config](https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference) — `tools.include` / `exclude`  
+- [Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models) — main + auxiliary (vision)  
+
+File write safety blocks credential/`config.yaml` self-edits via agent tools. Mutations belong on the **host** via NemoClaw sealed commands.
+
+## Decision
+
+No parallel control API. Product scripts wrap `nemohermes` / `openshell` only.
@@ -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 |
@@ -0,0 +1,75 @@
+# Software updates and lifecycle
+
+## Owner transparency
+
+Updates are an **operator** concern. The salon owner does **not** participate in or see software updates under normal operation.
+
+## When
+
+| Trigger | Default |
+|---------|---------|
+| Scheduled host job (`upgrade.sh`) | **ON by default** at install |
+| Manual `./scripts/upgrade.sh` | Always available to operator |
+| Owner chat | Does **not** drive platform upgrades |
+
+## How
+
+Host `upgrade.sh` is the parent orchestrator:
+
+1. Snapshot via `nemohermes <name> snapshot create` when available  
+2. Record release pins; optional volume backup  
+3. Fetch product release (git tag / image digests)  
+4. Non-interactive only — no Hermes interactive update/setup wizards  
+5. Compose pull/build/recreate **preserving volumes**  
+6. Run migrations if state schema changed  
+7. Re-apply policy via `openshell` / `nemohermes policy-*`  
+8. Re-assert inference/aux via `nemohermes inference set` / config set from `.env`  
+9. Gateway restart if required by platform matrix  
+10. Doctor; write **operator-only** upgrade journal  
+
+## Suppress Hermes interactive update
+
+| Risk | Mitigation |
+|------|------------|
+| Interactive `hermes update` | Never invoked; versions pinned by product release |
+| Startup config wizards | Config pre-written; non-interactive entrypoint |
+| Agent-triggered host upgrade | No tools for that; no docker.sock for owner agent |
+| Concurrent sealed config writes | Serialize; honor shields/busy; retry |
+
+## Update content vectors
+
+| # | Vector | Upgrade action |
+|---|--------|----------------|
+| 1 | This product git repo | Fetch/checkout release tag |
+| 2 | Host scripts | Replace from release |
+| 3 | Docs | Replace |
+| 4 | Compose files | Replace + recreate |
+| 5 | Product images (if published) | Pull digests |
+| 6 | NemoClaw CLI pin | Host install to pin |
+| 7 | OpenShell CLI/gateway pin | Host/bootstrap |
+| 8 | Sandbox / Hermes agent image | Rebuild/recreate as required |
+| 9–10 | Hermes runtime + NemoClaw integration | With image |
+| 11 | Lumina skills | Sync into sandbox |
+| 12 | Default identity templates | Merge; never clobber owner name/profile |
+| 13–14 | Owner memory / Hermes session state | Persist + migrate |
+| 15 | Managed config.yaml / placeholders | Regenerate via sealed host commands |
+| 16 | OpenShell provider secrets | Persist |
+| 17–18 | Policy base/overlays/presets | Merge + apply |
+| 19 | Square remote MCP registration | Re-assert + health |
+| 20 | QBO local MCP package pin | Upgrade process + restart |
+| 21 | Vagaro webhook service | Replace |
+| 22–23 | Channels + allowlists | Rebuild if matrix requires; persist allowlists |
+| 24–25 | Inference main + aux slots | inference set / config from `.env` |
+| 26 | Dashboard/API forwards | Re-bind |
+| 27 | Fixtures | Replace; not live connections |
+| 28 | Migrations | Run by version |
+| 29 | Auto-update timer unit | Enabled by default |
+| 30 | Host Docker Engine | Separate documented path |
+
+## Instrumentation
+
+Operator-only events under `state/upgrade/`: `upgrade.started|step|migration|policy|service|doctor|finished|failed`.
+
+## Rollback
+
+Previous pins + volumes; `upgrade.sh --rollback`; doctor.
@@ -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 |