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,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).