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,5 @@
+# CI workflows (scaffold)
+
+**Status:** No workflow YAML until **build** (optional docs-only CI later).
+
+Intended: lint docs, unit tests on fixtures, no live SaaS credentials in CI.
@@ -0,0 +1,11 @@
+.env
+.env.*
+!.env.example
+state/
+*.log
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.DS_Store
@@ -0,0 +1,29 @@
+# Agent notes — Salon_Assistant / Lumina
+
+## What this repo is
+
+Product seed for a **NemoClaw + Hermes** salon/spa owner assistant.  
+Remote: Gitea **Ty_Tech/Salon_Assistant** (via **gitea_vps** MCP only for this product’s Git ops).
+
+## Read first
+
+1. [`design/DESIGN_PLAN.md`](design/DESIGN_PLAN.md)  
+2. [`design/use-cases.md`](design/use-cases.md)  
+3. [`design/scenarios.md`](design/scenarios.md)  
+4. [`design/DECISIONS.md`](design/DECISIONS.md)  
+5. [`docs/README.md`](docs/README.md) (operator manuals)
+
+## Hard rules
+
+- **Platform-first:** `nemohermes` / `openshell` for config; no parallel control API.  
+- **No build** until user says **build** / **implement**.  
+- **No** `gitea_mcp_for_ty` / localhost Git MCP for this product — **gitea_vps** only.  
+- Owner never gets terminal/nano/docker instructions.  
+- No agent pay; no silent send/publish.  
+- **`design/`** = product POR SSOT; **`docs/`** = operator runbooks.
+
+## Git MCP
+
+- Server: `gitea_vps`  
+- URL: `https://giteamcp1.vps1.afterthedemo.com/mcp`  
+- User-Agent: `grok-connectors-manager/`  
@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning follows [Semantic Versioning](https://semver.org/).
+
+## [0.1.0-design] — 2026-07-27
+
+### Added
+
+- Approved repository structure (design pack + operator docs + code scaffolds).
+- Design SSOT under `design/`: DESIGN_PLAN, use cases, scenarios, decisions, planes, det-vs-inf, MCP integrations, updates lifecycle, platform research notes.
+- Operator runbook outlines under `docs/`.
+- Scaffold directories (README only) for policy, agents, skills, scripts, services, deploy, tests, etc.
+
+### Notes
+
+- No product implementation until explicit **build** / **implement**.
@@ -0,0 +1,2 @@
+# Default owners for Ty_Tech Salon_Assistant
+* @Ty
@@ -0,0 +1,35 @@
+# Contributing
+
+## Before you code
+
+1. Read [design/DESIGN_PLAN.md](design/DESIGN_PLAN.md).
+2. Read [design/use-cases.md](design/use-cases.md), [design/scenarios.md](design/scenarios.md), [design/DECISIONS.md](design/DECISIONS.md).
+3. Implementation requires an explicit **build** decision for greenfield features; structural and documentation work follows this CONTRIBUTING guide.
+
+## Platform-first
+
+- Sandbox, policy, credentials, channels, inference: **`nemohermes` / `openshell` only**.
+- Product scripts wrap those CLIs. Do not add a parallel control API.
+
+## Git ops for this product
+
+- Remote: Gitea **Ty_Tech/Salon_Assistant**.
+- Agent Git MCP for this product: **gitea_vps** only (`https://giteamcp1.vps1.afterthedemo.com/mcp`, User-Agent `grok-connectors-manager/`).
+
+## Pull requests
+
+- Branch from `main`.
+- Keep use-case SSOT in `design/use-cases.md` (do not duplicate full matrices in README).
+- Run `make verify` when implementation exists (fixture CI).
+- No secrets in commits.
+
+## Code style
+
+- Python 3.11+ for skill scripts and providers.
+- Deterministic logic in code; LLM only where the design matrix allows.
+
+## Releases
+
+- Tag releases (`vX.Y.Z`).
+- Pin images and MCP package versions in the release manifest.
+- `scripts/upgrade.sh` is the operator upgrade entrypoint (see docs/UPGRADE.md).
@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Ty_Tech / Salon_Assistant contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
@@ -0,0 +1,23 @@
+# Salon_Assistant / Lumina — operator entrypoints (STUB until build)
+# Approved structure: document targets only; do not invoke unimplemented scripts.
+
+.PHONY: help bootstrap install upgrade doctor verify sync-design
+
+help:
+	@echo "Salon_Assistant (Lumina) — structure phase (0.1.0-design)"
+	@echo "  Implementation not started. Explicit build/implement required."
+	@echo ""
+	@echo "Intended targets (after build):"
+	@echo "  make bootstrap  - host prereqs (Docker if missing)"
+	@echo "  make install    - full install S0b–S6"
+	@echo "  make upgrade    - product upgrade"
+	@echo "  make doctor     - health checks"
+	@echo "  make verify     - lint + tests + smoke (fixtures)"
+	@echo "  make sync-design - list design pack paths"
+
+bootstrap install upgrade doctor verify:
+	@echo "not implemented — wait for explicit build/implement order" >&2; exit 1
+
+sync-design:
+	@echo "Design SSOT:"
+	@ls -la design/DESIGN_PLAN.md design/use-cases.md design/scenarios.md design/DECISIONS.md
@@ -0,0 +1,47 @@
+# Salon_Assistant (Lumina)
+
+Docker-based **NemoClaw + Hermes** personal ops assistant for a salon/spa owner-operator.
+
+This directory is the **product seed** for the Gitea repository `Ty_Tech/Salon_Assistant`.
+
+## Status
+
+| Artifact | Location |
+|----------|----------|
+| Design plan (SSOT) | [`design/DESIGN_PLAN.md`](design/DESIGN_PLAN.md) |
+| Use cases (SSOT) | [`design/use-cases.md`](design/use-cases.md) |
+| Scenarios | [`design/scenarios.md`](design/scenarios.md) |
+| Resolved decisions | [`design/DECISIONS.md`](design/DECISIONS.md) |
+| Operator runbooks | [`docs/`](docs/) |
+| Implementation | **Not started** until explicit **build** / **implement** |
+
+## Product planes
+
+| Plane | Role |
+|-------|------|
+| Scheduling | Owner Vagaro and/or Square |
+| Books | Owner QuickBooks Online (read-heavy) |
+| Owner messaging | WhatsApp, Email, Telegram |
+| Client / social drafts | Draft only; owner sends/posts |
+| Social craft | Owner photos/video + vision aux |
+| Setup / ops | Install, connect SaaS, automatic updates (on by default) |
+
+## Doc placement
+
+| Folder | Purpose |
+|--------|---------|
+| **`design/`** | Product design SSOT — plan, use cases, scenarios, decisions, MCP strategy, update lifecycle |
+| **`docs/`** | Operator/user manuals — install, upgrade, providers, ops |
+
+## Platform-first rule
+
+All sandbox, policy, credential, channel, and inference mutations go through **`nemohermes` / `openshell`**. Product scripts (when built) wrap those CLIs. No parallel control API.
+
+## Layout (scaffolds)
+
+Code under `skills/`, `scripts/`, `services/`, `policy/`, etc. is **scaffold only** until **build**. See each area’s `README.md`.
+
+## Remote
+
+- Gitea: `Ty_Tech/Salon_Assistant` (public)
+- Git MCP for this product: **`gitea_vps`** only
@@ -0,0 +1,21 @@
+# Security Policy
+
+## Product invariants
+
+- Agent never executes payments, refunds, or bill-pay.
+- Client outbound messages and social posts are draft-only unless a future gated send is explicitly designed.
+- Secrets never commit to git (use OpenShell providers / host env).
+- Owner never receives host shell, Docker, or editor instructions from the assistant.
+
+## Reporting
+
+Report security issues privately to the repository maintainers (Ty_Tech org admins). Do not open public issues with secrets, tokens, or production PII.
+
+## Dependencies
+
+- Prefer pinned versions of NemoClaw, OpenShell, Hermes, and MCP packages.
+- Automatic product updates are on by default; review release notes for major pins.
+
+## Logging
+
+Default log level is production (redacted). Do not enable trace in owner-facing demos.
@@ -0,0 +1 @@
+0.1.0-design
@@ -0,0 +1,13 @@
+# Hermes agent package (scaffold)
+
+**Status:** Structure only until **build**.
+
+## Intended contents
+
+| Path | Purpose |
+|------|---------|
+| `config/` | Onboard fragments (model, MCP, channels placeholders) |
+| `skills-manifest/` | Which Lumina skills ship with the profile |
+| Identity templates | SOUL / USER / assistant naming (Claire demo persona when implemented) |
+
+Onboard via `nemohermes onboard` using this package — never hand-edit in-sandbox config as SSOT.
@@ -0,0 +1,11 @@
+# Fixtures (scaffold)
+
+Demo persona when implemented: **Claire Bennett**, **Lumina Hair Studio & Spa**.
+
+| Path | Purpose |
+|------|---------|
+| `books/` | Sample QBO-shaped JSON |
+| `media/` | Sample social media assets for vision tests |
+| `../recorded/` | Optional recorded responses (local only; do not commit secrets) |
+
+No fixture JSON committed until **build** unless explicitly requested.
@@ -0,0 +1,5 @@
+# Compose (scaffold)
+
+**Status:** No `docker-compose.yml` until **build**.
+
+Will host gateway/sandbox alignment, local QBO MCP, webhooks, volumes — per [design/DESIGN_PLAN.md](../../design/DESIGN_PLAN.md).
@@ -0,0 +1,5 @@
+# systemd units (scaffold)
+
+**Status:** Empty until **build**.
+
+Intended: auto-update timer/service calling `upgrade.sh` (auto-update **on** by default).
@@ -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 |
@@ -0,0 +1,21 @@
+# Architecture (operator summary)
+
+Full design: **[design/DESIGN_PLAN.md](../design/DESIGN_PLAN.md)**.
+
+## Layers
+
+```text
+Host (bootstrap, Docker, product scripts, nemohermes/openshell CLIs)
+  → OpenShell gateway (credentials, L7 policy, sandbox lifecycle)
+    → Hermes sandbox (minimal Lumina profile)
+         skills, channels, MCP clients (allowlisted)
+  → External OpenAI-compatible model (outside containers OK)
+```
+
+## Related design docs
+
+- [Planes](../design/planes.md)  
+- [Det vs inference](../design/det-vs-inf.md)  
+- [MCP integrations](../design/mcp-integrations.md)  
+- [Updates lifecycle](../design/updates-lifecycle.md)  
+- [Platform research notes](../design/research/platform-notes.md)  
@@ -0,0 +1,29 @@
+# Deployer host baselining
+
+**Status:** Outline from approved design POR. Procedural scripts at **build**.
+
+## Purpose
+
+Create a clean host that can run the Docker-based Lumina stack. This product is **repo-driven**, not tied to one developer’s existing Hermes install.
+
+## Requirements (POR)
+
+| Item | Spec |
+|------|------|
+| OS | Linux x86_64 or arm64 (cloud VM, bare metal; WSL2 optional path only) |
+| Resources | Multi-core CPU; ≥8–16 GB RAM recommended; disk for Docker images |
+| Privileges | User able to install Docker / run Compose |
+| Network | Outbound HTTPS to model endpoint, SaaS APIs, MCP remotes, image registry |
+| GPU | Optional; only if local VLM is used (not required if vision is remote) |
+
+## Steps (operator)
+
+1. Provision host (cloud console / hypervisor).  
+2. Install base OS updates.  
+3. Create deploy user; clone this repository.  
+4. Run `./scripts/bootstrap.sh` (installs Docker if missing — when implemented).  
+5. Continue with [INSTALL.md](INSTALL.md).
+
+## Design reference
+
+[design/DESIGN_PLAN.md](../design/DESIGN_PLAN.md) § Docker packaging and install stages.
@@ -0,0 +1,13 @@
+# Hermes model configuration
+
+**Status:** Outline from approved design.
+
+| Slot | Requirement |
+|------|-------------|
+| **Main** | OpenAI-compatible chat + tools; endpoint **may be outside Docker** |
+| **Auxiliary `vision`** | **Required** for media social; install smoke test |
+| **Other aux** | Default to same base/main endpoint unless overridden |
+
+Configured via NemoClaw inference + generated Hermes config (`nemohermes inference set` / sealed config), not owner terminal editing.
+
+See [design/DESIGN_PLAN.md](../design/DESIGN_PLAN.md) and [Hermes Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models).
@@ -0,0 +1,31 @@
+# Install
+
+**Status:** Outline from approved design. Scripts stubbed until **build**.
+
+## Stages
+
+| Stage | Where | Outcome |
+|-------|--------|---------|
+| S0 | Human | Host per [DEPLOYER_HOST.md](DEPLOYER_HOST.md) |
+| S0b | Host script | Docker installed if missing |
+| S1 | Host script | Repo env, `.env` from `.env.example` |
+| S2 | Host script | Main + aux vision config; vision smoke |
+| S3–S5 | Host → Compose / `nemohermes` | Stack, sandbox, policy, skills |
+| S6 | Host script | Doctor green |
+| S7 | Owner + operator connect helpers | Name assistant; connect **their** SaaS/channels |
+
+## Platform commands (normative)
+
+All mutations: `nemohermes` / `openshell` (see [design/research/platform-notes.md](../design/research/platform-notes.md)).
+
+## Intended entrypoints
+
+```bash
+./scripts/bootstrap.sh
+./scripts/install.sh
+./scripts/doctor.sh
+```
+
+## After install
+
+[SETUP_UX.md](SETUP_UX.md) · [design/scenarios.md](../design/scenarios.md) (S1–S5).
@@ -0,0 +1,24 @@
+# Operations (day-2)
+
+**Status:** Outline.
+
+## Operator commands (when implemented)
+
+```bash
+./scripts/doctor.sh
+nemohermes <sandbox-name> status
+nemohermes <sandbox-name> logs --follow
+docker compose -f deploy/compose/docker-compose.yml logs
+```
+
+## Log levels
+
+| Level | Default | Use |
+|-------|---------|-----|
+| production | Yes | Redacted events, errors, health |
+| debug | Off | Operator troubleshooting |
+| trace | Off | Dev only |
+
+## Updates
+
+[UPGRADE.md](UPGRADE.md) · [design/updates-lifecycle.md](../design/updates-lifecycle.md)
@@ -0,0 +1,16 @@
+# OpenShell policy
+
+**Status:** Outline. Policy sources under `policy/openshell/`.
+
+| Artifact | Role |
+|----------|------|
+| `policy/openshell/policy.yaml` | Base deny-by-default |
+| `policy/openshell/overlays/` | channels, square, vagaro, quickbooks, inference |
+| Generated on volume | Applied at install / connect / upgrade |
+
+**Always deny:** social publish APIs; payment/refund/payout/bill-pay.  
+**Allow when connected:** model endpoint; channel APIs; enabled SaaS hosts.
+
+Apply via `openshell policy set` and `nemohermes … policy-add` / `policy-remove` (platform-native).
+
+See [design/DESIGN_PLAN.md](../design/DESIGN_PLAN.md).
@@ -0,0 +1,17 @@
+# Operator & user documentation
+
+Runbooks and how-tos. **Product design SSOT** is under [`../design/`](../design/).
+
+| Document | Purpose | Status |
+|----------|---------|--------|
+| [DEPLOYER_HOST.md](DEPLOYER_HOST.md) | Create/baselined host requirements | Outline (POR) |
+| [INSTALL.md](INSTALL.md) | Install stages S0–S6 | Outline (POR) |
+| [UPGRADE.md](UPGRADE.md) | Upgrade / rollback | Outline — full design in [design/updates-lifecycle.md](../design/updates-lifecycle.md) |
+| [HERMES_MODELS.md](HERMES_MODELS.md) | Main + auxiliary models | Outline (POR) |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | Operator-facing architecture summary | Outline → links design |
+| [POLICY.md](POLICY.md) | OpenShell policy apply | Outline (POR) |
+| [SETUP_UX.md](SETUP_UX.md) | Owner educational connect flows | Outline (POR) |
+| [OPERATIONS.md](OPERATIONS.md) | Day-2 logs, doctor | Outline (POR) |
+| [providers/](providers/) | Square, QBO, Vagaro, channels | Outlines |
+
+Implementation of install scripts is **not** started until **build**.
@@ -0,0 +1,27 @@
+# Owner Setup UX (post-install)
+
+**Status:** Outline. Scenarios: [design/scenarios.md](../design/scenarios.md).
+
+## Prerequisite
+
+Install stages S0–S6 complete ([INSTALL.md](INSTALL.md)).
+
+## Flow
+
+1. **Name the assistant** → profile/sandbox name.  
+2. **Profile intake** — business, timezone, hours, priorities, hard rules.  
+3. **Channels** — WhatsApp, Email, Telegram (connect / skip / later).  
+4. **Scheduling** — owner’s Vagaro and/or Square.  
+5. **Books** — owner’s QuickBooks Online.  
+6. **Expectations** — draft-only client send; no auto-publish; no inventing live data.  
+7. **Capability report** — plain language.
+
+## Rules
+
+- Owner never receives terminal/Docker/editor instructions.  
+- Secrets via operator `scripts/connect-*.sh` + OpenShell providers / NemoClaw channel flows.  
+- Agent explains vendor browser steps only.
+
+## Related
+
+[design/use-cases.md](../design/use-cases.md) family E · [design/mcp-integrations.md](../design/mcp-integrations.md)
@@ -0,0 +1,22 @@
+# Upgrade and rollback
+
+**Status:** Outline. Full POR: [design/updates-lifecycle.md](../design/updates-lifecycle.md).
+
+## Defaults
+
+- Automatic updates: **ON by default** (host timer calling `upgrade.sh`).  
+- Owner: **no** participation or chat noise.  
+- Manual: `./scripts/upgrade.sh` · dry-run · rollback.
+
+## Operator quick path (when implemented)
+
+```bash
+./scripts/upgrade.sh --dry-run
+./scripts/upgrade.sh
+./scripts/doctor.sh
+./scripts/upgrade.sh --rollback   # if needed
+```
+
+## Non-interactive Hermes
+
+Product upgrade must **not** invoke interactive `hermes update` / config wizards. Pins and sealed `nemohermes` config/inference commands only.
@@ -0,0 +1,5 @@
+# Architecture Decision Records
+
+Product-level decisions currently live in [design/DECISIONS.md](../../design/DECISIONS.md).
+
+Formal ADRs may be added here at **build** if needed.
@@ -0,0 +1,3 @@
+# Install appendix
+
+Optional deep-dive install notes. Primary guide: [../INSTALL.md](../INSTALL.md).
@@ -0,0 +1,3 @@
+# Ops appendix
+
+Optional runbooks. Primary guide: [../OPERATIONS.md](../OPERATIONS.md).
@@ -0,0 +1,10 @@
+# Owner channels (WhatsApp, Email, Telegram)
+
+**Status:** Outline.
+
+- MVP owner ↔ assistant channels: **WhatsApp, Email, Telegram**.  
+- Configured via **NemoClaw Hermes channel commands** (`nemohermes … channels add`, rebuild when required).  
+- Allowlists for who may talk to the bot.  
+- Owner never configures via host shell recipes in chat.  
+
+See [design/use-cases.md](../../design/use-cases.md) family C · [docs/SETUP_UX.md](../SETUP_UX.md).
@@ -0,0 +1,8 @@
+# QuickBooks Online
+
+**Status:** Outline. Design: [design/mcp-integrations.md](../../design/mcp-integrations.md).
+
+- **Agent path:** local QBO MCP on Docker network with Hermes.  
+- **Allow:** P&L/reports, invoice/bill/vendor/customer read, company info.  
+- **Deny:** payment/bill_payment tools; write/update/delete off for MVP.  
+- **Connect:** operator `scripts/connect/connect-quickbooks.sh` (build).  
@@ -0,0 +1,8 @@
+# Square
+
+**Status:** Outline. Design: [design/mcp-integrations.md](../../design/mcp-integrations.md).
+
+- **Agent path:** remote Square MCP.  
+- **Allow:** bookings, customers, catalog, inventory/location reads.  
+- **Deny:** payments, refunds, cards, checkout, payouts.  
+- **Connect:** operator `scripts/connect/connect-square.sh` (build) + owner browser OAuth.  
@@ -0,0 +1,8 @@
+# Vagaro
+
+**Status:** Outline. Design: [design/mcp-integrations.md](../../design/mcp-integrations.md).
+
+- **No public MCP** — REST + webhooks.  
+- Appointments, clients, services, staff.  
+- No unofficial scrape.  
+- **Connect:** operator `scripts/connect/connect-vagaro.sh` (build).  
@@ -0,0 +1,5 @@
+# State migrations (scaffold)
+
+**Status:** Empty until **build**.
+
+Used by `upgrade.sh` when schema/version changes between product releases.
@@ -0,0 +1,8 @@
+# Observability (scaffold)
+
+**Status:** Schema placeholders until **build**.
+
+Runtime levels (design): production (default), debug, trace.  
+Sources: `nemohermes logs`, compose logs, volume event paths.
+
+See [design/DESIGN_PLAN.md](../design/DESIGN_PLAN.md) § Observability.
@@ -0,0 +1,14 @@
+# OpenShell policy (scaffold)
+
+**Status:** Structure only — no live policy applied until **build**.
+
+## Intended contents
+
+| Path | Purpose |
+|------|---------|
+| `policy.yaml` (or equivalent) | Deny-by-default base for salon egress |
+| `overlays/` | Per-integration allowlists (Square MCP host, QBO local, channels, etc.) |
+
+Apply via platform CLIs only: `openshell policy set`, `nemohermes <name> policy-add` / `policy-remove`.
+
+See [design/mcp-integrations.md](../../design/mcp-integrations.md) and [docs/POLICY.md](../../docs/POLICY.md).
@@ -0,0 +1,19 @@
+# Host scripts (scaffold)
+
+**Status:** Documented entrypoints only — no executable bodies until **build**.
+
+All scripts must wrap **`nemohermes` / `openshell` / Docker**. No parallel control API.
+
+## Intended entrypoints
+
+| Script | Role |
+|--------|------|
+| `bootstrap.sh` | Host prereqs; install Docker if missing |
+| `install.sh` | Stages S0b–S6 |
+| `upgrade.sh` | Snapshot, pull pins, migrate, re-apply policy, doctor |
+| `doctor.sh` | Health checks |
+| `connect/*.sh` | Operator connect helpers (Square, QBO, Vagaro, channels) |
+| `install/` | Stage helpers |
+| `lib/` | Shared shell helpers |
+
+See [docs/INSTALL.md](../docs/INSTALL.md), [docs/UPGRADE.md](../docs/UPGRADE.md), [design/updates-lifecycle.md](../design/updates-lifecycle.md).
@@ -0,0 +1,11 @@
+# Services (scaffold)
+
+Optional Dockerized helpers for integrations that are not pure Hermes skills.
+
+| Service | Role |
+|---------|------|
+| `salon-ops-api/` | Domain helpers (not a control API) |
+| `vagaro-webhooks/` | Vagaro webhooks + REST |
+| `qbo-mcp/` | Local QBO MCP |
+
+**No product code until build.**
@@ -0,0 +1,7 @@
+# `qbo-mcp` (scaffold)
+
+**Status:** Not implemented until **build**.
+
+Local QuickBooks Online MCP process on Compose network.
+
+Design: [design/mcp-integrations.md](../../design/mcp-integrations.md).
@@ -0,0 +1,7 @@
+# `salon-ops-api` (scaffold)
+
+**Status:** Not implemented until **build**.
+
+Internal ops API / domain services (if needed; not a NemoClaw control plane).
+
+Design: [design/mcp-integrations.md](../../design/mcp-integrations.md).
@@ -0,0 +1,7 @@
+# `vagaro-webhooks` (scaffold)
+
+**Status:** Not implemented until **build**.
+
+Vagaro REST + webhook receiver (no public Vagaro MCP).
+
+Design: [design/mcp-integrations.md](../../design/mcp-integrations.md).
@@ -0,0 +1,30 @@
+# Skills (scaffold)
+
+**Status:** Directory layout only. No skill scripts or SKILL.md bodies until **build**.
+
+See use-case catalog: [design/use-cases.md](../design/use-cases.md).
+
+## Planned skill families
+
+| Directory | Status |
+|-----------|--------|
+| `daily-board/` | Scaffold — skill body at **build** |
+| `availability/` | Scaffold — skill body at **build** |
+| `client-card/` | Scaffold — skill body at **build** |
+| `service-menu/` | Scaffold — skill body at **build** |
+| `retail-stock/` | Scaffold — skill body at **build** |
+| `books-snapshot/` | Scaffold — skill body at **build** |
+| `ar-open-invoices/` | Scaffold — skill body at **build** |
+| `ap-bills-due/` | Scaffold — skill body at **build** |
+| `vendor-spend/` | Scaffold — skill body at **build** |
+| `vendor-inbox/` | Scaffold — skill body at **build** |
+| `draft-invoice/` | Scaffold — skill body at **build** |
+| `draft-client-message/` | Scaffold — skill body at **build** |
+| `social-draft/` | Scaffold — skill body at **build** |
+| `weekly-digest/` | Scaffold — skill body at **build** |
+| `remember-forget/` | Scaffold — skill body at **build** |
+| `setup-education/` | Scaffold — skill body at **build** |
+| `publish-boundary-test/` | Scaffold — skill body at **build** |
+| `_lib/lumina_skills/` | Shared providers (scheduling/books/MCP) — empty until **build** |
+
+Rules (from design): draft-first outbound; no agent payments; deterministic facts from tools; refuse silent send/publish.
@@ -0,0 +1,9 @@
+# Shared skill library (scaffold)
+
+**Status:** Empty until **build**.
+
+Planned packages under `providers/`:
+
+- `scheduling/` — Vagaro / Square adapters  
+- `books/` — QuickBooks Online adapters  
+- `mcp/` — MCP client helpers / allowlist metadata  
@@ -0,0 +1,5 @@
+# `ap-bills-due` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `ar-open-invoices` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `availability` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `books-snapshot` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `client-card` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `daily-board` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `draft-client-message` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `draft-invoice` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `publish-boundary-test` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `remember-forget` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `retail-stock` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `service-menu` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `setup-education` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `social-draft` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `vendor-inbox` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `vendor-spend` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
@@ -0,0 +1,5 @@
+# `weekly-digest` (scaffold)
+
+**Status:** Not implemented. Implementation requires explicit **build**.
+
+Intent: see [design/use-cases.md](../../design/use-cases.md) and [design/scenarios.md](../../design/scenarios.md).
--- a/Show More
+++ b/Show More