Implement install stages S3–S5: package, policy, and skills sync.

Attach/onboard sandbox from agents/hermes, additive OpenShell policy overlays, and nemohermes skill install for scaffold skills. No doctor/connect and no push.
2026-07-27 12:13:25 -07:00
parent e5e179e541
commit 0198ab6881
38 changed files with 1422 additions and 51 deletions
@@ -1,5 +1,55 @@
-# Compose (scaffold)
+# Compose — product-managed services

-**Status:** No `docker-compose.yml` until **build**.
+**Status:** Optional stub. Not required for S3–S5 UAT attach path.

-Will host gateway/sandbox alignment, local QBO MCP, webhooks, volumes — per [design/DESIGN_PLAN.md](../../design/DESIGN_PLAN.md).
+## Host vs container boundaries
+
+| Layer | Owner | Managed by |
+|-------|-------|------------|
+| **Host** | Operator | `nemohermes` CLI, `openshell` CLI, product scripts |
+| **Gateway** | OpenShell | `nemohermes` (sealed transactions) |
+| **Hermes sandbox** | OpenShell | `nemohermes <name> start/stop/rebuild/destroy` |
+| **Local MCP / webhooks** | Product | `docker compose` (this file) — optional |
+
+**Key principle:** OpenShell owns the Hermes sandbox container. The product does NOT define the sandbox in `docker-compose.yml`. The sandbox is created and managed exclusively through `nemohermes` commands.
+
+## What this compose file provides
+
+An optional Docker Compose file for **product-managed services** that run alongside the Hermes sandbox:
+
+- **QBO MCP** — local MCP server for QuickBooks Online (stdio or network-attached)
+- **Vagaro webhooks** — REST endpoint for Vagaro webhook ingestion
+
+These services share the `lumina` Docker network. The Hermes sandbox container is NOT part of this compose file.
+
+## When to use
+
+- **UAT attach (S3–S5):** Not needed. The sandbox runs via `nemohermes`; no local MCP or webhooks yet.
+- **S7+ (SaaS connections):** Uncomment and configure the relevant service when connecting Square, QBO, or Vagaro.
+
+## Usage
+
+```bash
+# When services are uncommented and configured:
+cd deploy/compose
+docker compose up -d
+
+# Check status
+docker compose ps
+
+# Logs
+docker compose logs -f
+```
+
+## Volumes
+
+| Volume | Purpose |
+|--------|---------|
+| `qbo-mcp-data` | QBO MCP state (tokens, cache) |
+| `vagaro-webhooks-data` | Webhook processing state |
+
+## Design reference
+
+- [design/DESIGN_PLAN.md §3](../../design/DESIGN_PLAN.md) — Hermes as NemoClaw-managed infrastructure
+- [design/DESIGN_PLAN.md §6](../../design/DESIGN_PLAN.md) — MCP and SaaS integration
+- [docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md) — overall architecture
@@ -0,0 +1,55 @@
+# Salon_Assistant / Lumina — optional product services
+#
+# This compose file is OPTIONAL. It is NOT required for the S3–S5 UAT attach path.
+# OpenShell manages the Hermes sandbox container directly; nemohermes owns
+# sandbox lifecycle (start/stop/rebuild/destroy). This compose file exists only
+# for future local MCP processes and webhook services that run alongside the
+# sandbox on the same Docker network.
+#
+# Usage (when needed):
+#   cd deploy/compose && docker compose up -d
+#
+# See deploy/compose/README.md for details.
+
+# ── Network ────────────────────────────────────────────────────────────────
+# All product-managed services share this network. The Hermes sandbox container
+# is NOT defined here — it is managed by nemohermes/OpenShell.
+networks:
+  lumina:
+    driver: bridge
+
+# ── Volumes ────────────────────────────────────────────────────────────────
+volumes:
+  qbo-mcp-data:
+  vagaro-webhooks-data:
+
+# ── Services (stubs — enabled when SaaS connections are configured) ────────
+# Uncomment and configure when the corresponding SaaS integration is connected.
+
+# qbo-mcp:
+#   image: ghcr.io/ty-tech/qbo-mcp:latest  # placeholder — real image at S7
+#   container_name: lumina-qbo-mcp
+#   networks:
+#     - lumina
+#   volumes:
+#     - qbo-mcp-data:/data
+#   environment:
+#     - QBO_CLIENT_ID=${QBO_CLIENT_ID}
+#     - QBO_CLIENT_SECRET=${QBO_CLIENT_SECRET}
+#     - QBO_REFRESH_TOKEN=${QBO_REFRESH_TOKEN}
+#     - QBO_REALM_ID=${QBO_REALM_ID}
+#   restart: unless-stopped
+
+# vagaro-webhooks:
+#   image: ghcr.io/ty-tech/vagaro-webhooks:latest  # placeholder — real image at S7
+#   container_name: lumina-vagaro-webhooks
+#   networks:
+#     - lumina
+#   volumes:
+#     - vagaro-webhooks-data:/data
+#   environment:
+#     - VAGARO_API_KEY=${VAGARO_API_KEY}
+#     - VAGARO_WEBHOOK_SECRET=${VAGARO_WEBHOOK_SECRET}
+#   ports:
+#     - "127.0.0.1:8090:8080"
+#   restart: unless-stopped