commit 48566993f63c02c4ebfa0d734fa0a1cec6117dd6 Author: Ty Date: Mon Jul 27 09:44:35 2026 -0700 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. diff --git a/.github/ISSUE_TEMPLATE/.gitkeep b/.github/ISSUE_TEMPLATE/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 0000000..085b9d5 --- /dev/null +++ b/.github/workflows/README.md @@ -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. diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8acda7e --- /dev/null +++ b/.gitignore @@ -0,0 +1,11 @@ +.env +.env.* +!.env.example +state/ +*.log +.venv/ +__pycache__/ +.pytest_cache/ +.ruff_cache/ +.mypy_cache/ +.DS_Store diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e852f13 --- /dev/null +++ b/AGENTS.md @@ -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/` diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..c259930 --- /dev/null +++ b/CHANGELOG.md @@ -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**. diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 0000000..62607b3 --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,2 @@ +# Default owners for Ty_Tech Salon_Assistant +* @Ty diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..68c9983 --- /dev/null +++ b/CONTRIBUTING.md @@ -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). diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..8920497 --- /dev/null +++ b/LICENSE @@ -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. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..64c2477 --- /dev/null +++ b/Makefile @@ -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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..4866a2e --- /dev/null +++ b/README.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 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..2490bb3 --- /dev/null +++ b/SECURITY.md @@ -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. diff --git a/VERSION b/VERSION new file mode 100644 index 0000000..53bebaa --- /dev/null +++ b/VERSION @@ -0,0 +1 @@ +0.1.0-design diff --git a/agents/hermes/README.md b/agents/hermes/README.md new file mode 100644 index 0000000..cb66e6c --- /dev/null +++ b/agents/hermes/README.md @@ -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. diff --git a/agents/hermes/config/.gitkeep b/agents/hermes/config/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/agents/hermes/skills-manifest/.gitkeep b/agents/hermes/skills-manifest/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/data/fixtures/README.md b/data/fixtures/README.md new file mode 100644 index 0000000..e7a30f7 --- /dev/null +++ b/data/fixtures/README.md @@ -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. diff --git a/data/fixtures/books/.gitkeep b/data/fixtures/books/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/data/fixtures/media/.gitkeep b/data/fixtures/media/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/data/recorded/.gitkeep b/data/recorded/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/deploy/compose/README.md b/deploy/compose/README.md new file mode 100644 index 0000000..6b8f5e1 --- /dev/null +++ b/deploy/compose/README.md @@ -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). diff --git a/deploy/systemd/README.md b/deploy/systemd/README.md new file mode 100644 index 0000000..8c6813f --- /dev/null +++ b/deploy/systemd/README.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). diff --git a/design/DECISIONS.md b/design/DECISIONS.md new file mode 100644 index 0000000..78ed9c9 --- /dev/null +++ b/design/DECISIONS.md @@ -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. diff --git a/design/DESIGN_PLAN.md b/design/DESIGN_PLAN.md new file mode 100644 index 0000000..58f6dba --- /dev/null +++ b/design/DESIGN_PLAN.md @@ -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 status`, `logs` | +| Snapshot / rebuild | `nemohermes snapshot create`, `rebuild` | +| Inference route | `nemohermes inference set` (patches `/sandbox/.hermes/config.yaml` with trust anchors; typically no rebuild) | +| Supported Hermes config keys | `nemohermes config set` (sealed transaction; do not hand-edit in-sandbox config) | +| Network policy | `openshell policy set`, `nemohermes policy-add` / `policy-remove` | +| Messaging channels | `nemohermes 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 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 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. diff --git a/design/README.md b/design/README.md new file mode 100644 index 0000000..b43ed77 --- /dev/null +++ b/design/README.md @@ -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. diff --git a/design/det-vs-inf.md b/design/det-vs-inf.md new file mode 100644 index 0000000..2544584 --- /dev/null +++ b/design/det-vs-inf.md @@ -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. diff --git a/design/diagrams/README.md b/design/diagrams/README.md new file mode 100644 index 0000000..a13b220 --- /dev/null +++ b/design/diagrams/README.md @@ -0,0 +1,4 @@ +# Diagrams (optional) + +Place architecture diagrams (mermaid sources or images) here when useful. +Design narrative lives in sibling markdown files. diff --git a/design/mcp-integrations.md b/design/mcp-integrations.md new file mode 100644 index 0000000..30b01ad --- /dev/null +++ b/design/mcp-integrations.md @@ -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. diff --git a/design/planes.md b/design/planes.md new file mode 100644 index 0000000..e991a5b --- /dev/null +++ b/design/planes.md @@ -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. diff --git a/design/research/platform-notes.md b/design/research/platform-notes.md new file mode 100644 index 0000000..fa9ed77 --- /dev/null +++ b/design/research/platform-notes.md @@ -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. diff --git a/design/scenarios.md b/design/scenarios.md new file mode 100644 index 0000000..6b27984 --- /dev/null +++ b/design/scenarios.md @@ -0,0 +1,199 @@ +# Scenarios — Lumina / Salon_Assistant + +Narrative scenarios that drive design and tests. Use cases SSOT: [`use-cases.md`](use-cases.md). + +--- + +## S1. First-time operator install + +1. Operator provisions a baselined Linux host (`docs/DEPLOYER_HOST.md` when written). +2. Clones this repo; runs bootstrap → Docker installed if missing. +3. Configures external OpenAI-compatible model URL + vision aux. +4. `install` creates NemoClaw Hermes sandbox from this package, applies policy, installs skills. +5. Doctor green. +6. Owner still has not been involved. + +**Success:** Stack runs; no owner terminal work yet. + +--- + +## S2. Introduction — name the assistant + +1. Owner opens WhatsApp/Telegram/Email to the bot (or first post-install operator-facilitated intro). +2. Assistant asks what to call it. +3. Name becomes Hermes/NemoClaw profile/sandbox identity. +4. Profile intake: business, timezone, hours, priorities, hard rules. + +**Success:** Named profile; structured profile stored; no shell instructions. + +--- + +## S3. Connect Square (happy path) + +1. Educational step: what Lumina reads; never pays. +2. Owner completes Square developer/OAuth in browser. +3. Operator `connect-square` script registers remote MCP + policy overlay via `nemohermes`/`openshell`. +4. Health: sample bookings/catalog read. +5. Capability report: scheduling = connected (Square). + +**Success:** Board uses live Square; pay tools not registered. + +--- + +## S4. Connect QuickBooks (happy path) + +1. Educational step: read-only money picture. +2. Owner OAuth via Intuit; operator script starts local QBO MCP on Compose network; sealed config. +3. Health: company info + P&L or invoice search. +4. Capability report: books = connected. + +**Success:** Books snapshot works; payment tools denied. + +--- + +## S5. Connect Vagaro (happy path) + +1. API key / webhook setup in Vagaro UI. +2. Operator script configures REST provider + webhook service + policy. +3. Board reflects Vagaro appointments. + +**Success:** No scrape; deterministic provider. + +--- + +## S6. Owner cannot connect any SaaS + +1. Owner skips Vagaro, Square, QBO. +2. Channels may still work. +3. Board/books use fixtures or “offline.” +4. Every answer that would use live data labels demo/offline. + +**Success:** Educational + draft helper still useful; no silent fake live numbers. + +--- + +## S7. Channel partial outage + +1. WhatsApp connected; Email failed; Telegram skipped. +2. Owner uses WhatsApp only. +3. Capability report shows per-channel status. + +**Success:** Product usable on remaining channels. + +--- + +## S8. Morning board on WhatsApp + +1. Owner: “What’s on the book tomorrow?” +2. Deterministic fetch → model summarizes in her voice. +3. Flags pending confirmations and gaps. + +**Success:** Actionable list; sources labeled if fixtures. + +--- + +## S9. Client prep with formula overlay + +1. Owner: “Prep me for Elena.” +2. Client card from SoR + local formula/allergy notes. +3. Privacy reminder if needed. + +**Success:** Correct card; no cross-client leak. + +--- + +## S10. Draft late-running SMS + +1. Owner asks for a late message for Chris. +2. Style pack applied; `sends=false`. +3. Owner copies to Messages/WhatsApp herself. + +**Success:** Draft only; never auto-sent. + +--- + +## S11. Vendor invoice email triage + +1. Invoice-like message in inbox fixtures or mail. +2. Matched to open QBO bill or “not in books.” +3. Owner told to review; agent will not pay. + +**Success:** Clear next step; no payment path. + +--- + +## S12. Social post from before/after photo + +1. Owner sends photo on Telegram. +2. Vision aux describes; main model drafts caption package. +3. Owner posts to Instagram herself. + +**Success:** Draft package; no publish API call; vision degraded path if aux down. + +--- + +## S13. Owner asks agent to refund a client + +1. Agent refuses (skill + SOUL + no pay MCP tools + OpenShell). +2. Offers non-money help (draft apology, rebook draft). + +**Success:** Hard refuse; helpful alternative. + +--- + +## S14. Owner asks “run nano and edit config” + +1. Agent refuses shell/editor recipes. +2. Routes to supported connect/settings path or operator doctor. + +**Success:** No terminal literacy required of owner. + +--- + +## S15. Automatic software update overnight + +1. Scheduled host job runs `upgrade.sh` (on by default). +2. Snapshot, pull pins, recreate containers, migrate, policy re-apply, doctor. +3. Owner sees no chat about upgrade; possible brief reconnect blip only. + +**Success:** Invisible to owner; operator journal has events; connections preserved. + +--- + +## S16. Upgrade failure + +1. Doctor fails mid-upgrade. +2. Rollback to previous pin when possible. +3. Operator alerted via logs/journal — not owner spam. + +**Success:** Safe failure; owner data intact. + +--- + +## S17. Learn style over time + +1. Owner: “Too salesy, shorter.” +2. Agent proposes remember; owner confirms. +3. Next drafts shorter. + +**Success:** Confirm-to-learn; forget works; no silent model finetune. + +--- + +## S18. Multi-SoR honesty + +1. Floor revenue from metrics ≠ QBO P&L. +2. Weekly digest surfaces both and does not reconcile silently. + +**Success:** Transparent disagreement. + +--- + +## Test mapping (future) + +| Scenario | Automated test type | +|----------|---------------------| +| S8–S11, S13 fixtures | Unit/contract/smoke | +| S12 vision | Smoke when vision configured | +| S15–S16 | Upgrade dry-run / migration tests | +| S3–S5 | Optional integration with real sandboxes | diff --git a/design/updates-lifecycle.md b/design/updates-lifecycle.md new file mode 100644 index 0000000..4a04812 --- /dev/null +++ b/design/updates-lifecycle.md @@ -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 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. diff --git a/design/use-cases.md b/design/use-cases.md new file mode 100644 index 0000000..788cc61 --- /dev/null +++ b/design/use-cases.md @@ -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 | diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..d3731fb --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -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) diff --git a/docs/DEPLOYER_HOST.md b/docs/DEPLOYER_HOST.md new file mode 100644 index 0000000..85b7cf6 --- /dev/null +++ b/docs/DEPLOYER_HOST.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. diff --git a/docs/HERMES_MODELS.md b/docs/HERMES_MODELS.md new file mode 100644 index 0000000..44a21cd --- /dev/null +++ b/docs/HERMES_MODELS.md @@ -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). diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 0000000..f07d308 --- /dev/null +++ b/docs/INSTALL.md @@ -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). diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md new file mode 100644 index 0000000..b6415f1 --- /dev/null +++ b/docs/OPERATIONS.md @@ -0,0 +1,24 @@ +# Operations (day-2) + +**Status:** Outline. + +## Operator commands (when implemented) + +```bash +./scripts/doctor.sh +nemohermes status +nemohermes 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) diff --git a/docs/POLICY.md b/docs/POLICY.md new file mode 100644 index 0000000..b07659b --- /dev/null +++ b/docs/POLICY.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). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..3a2f0d8 --- /dev/null +++ b/docs/README.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**. diff --git a/docs/SETUP_UX.md b/docs/SETUP_UX.md new file mode 100644 index 0000000..f0fd971 --- /dev/null +++ b/docs/SETUP_UX.md @@ -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) diff --git a/docs/UPGRADE.md b/docs/UPGRADE.md new file mode 100644 index 0000000..78625fd --- /dev/null +++ b/docs/UPGRADE.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. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..4e15a4e --- /dev/null +++ b/docs/adr/README.md @@ -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. diff --git a/docs/install/README.md b/docs/install/README.md new file mode 100644 index 0000000..5fb1dfa --- /dev/null +++ b/docs/install/README.md @@ -0,0 +1,3 @@ +# Install appendix + +Optional deep-dive install notes. Primary guide: [../INSTALL.md](../INSTALL.md). diff --git a/docs/ops/README.md b/docs/ops/README.md new file mode 100644 index 0000000..4905b57 --- /dev/null +++ b/docs/ops/README.md @@ -0,0 +1,3 @@ +# Ops appendix + +Optional runbooks. Primary guide: [../OPERATIONS.md](../OPERATIONS.md). diff --git a/docs/providers/channels.md b/docs/providers/channels.md new file mode 100644 index 0000000..c810366 --- /dev/null +++ b/docs/providers/channels.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). diff --git a/docs/providers/quickbooks.md b/docs/providers/quickbooks.md new file mode 100644 index 0000000..06a8eb5 --- /dev/null +++ b/docs/providers/quickbooks.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). diff --git a/docs/providers/square.md b/docs/providers/square.md new file mode 100644 index 0000000..1019ded --- /dev/null +++ b/docs/providers/square.md @@ -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. diff --git a/docs/providers/vagaro.md b/docs/providers/vagaro.md new file mode 100644 index 0000000..8bdcb4a --- /dev/null +++ b/docs/providers/vagaro.md @@ -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). diff --git a/migrations/.gitkeep b/migrations/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/migrations/README.md b/migrations/README.md new file mode 100644 index 0000000..14978d2 --- /dev/null +++ b/migrations/README.md @@ -0,0 +1,5 @@ +# State migrations (scaffold) + +**Status:** Empty until **build**. + +Used by `upgrade.sh` when schema/version changes between product releases. diff --git a/observability/README.md b/observability/README.md new file mode 100644 index 0000000..eb5103b --- /dev/null +++ b/observability/README.md @@ -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. diff --git a/observability/schema/.gitkeep b/observability/schema/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/policy/openshell/README.md b/policy/openshell/README.md new file mode 100644 index 0000000..071d151 --- /dev/null +++ b/policy/openshell/README.md @@ -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 policy-add` / `policy-remove`. + +See [design/mcp-integrations.md](../../design/mcp-integrations.md) and [docs/POLICY.md](../../docs/POLICY.md). diff --git a/policy/openshell/overlays/.gitkeep b/policy/openshell/overlays/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..aa95238 --- /dev/null +++ b/scripts/README.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). diff --git a/scripts/connect/.gitkeep b/scripts/connect/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/scripts/install/.gitkeep b/scripts/install/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/scripts/lib/.gitkeep b/scripts/lib/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/services/README.md b/services/README.md new file mode 100644 index 0000000..2f7820c --- /dev/null +++ b/services/README.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.** diff --git a/services/qbo-mcp/README.md b/services/qbo-mcp/README.md new file mode 100644 index 0000000..4b526dc --- /dev/null +++ b/services/qbo-mcp/README.md @@ -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). diff --git a/services/salon-ops-api/README.md b/services/salon-ops-api/README.md new file mode 100644 index 0000000..db67dbd --- /dev/null +++ b/services/salon-ops-api/README.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). diff --git a/services/vagaro-webhooks/README.md b/services/vagaro-webhooks/README.md new file mode 100644 index 0000000..105478f --- /dev/null +++ b/services/vagaro-webhooks/README.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). diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..77d3078 --- /dev/null +++ b/skills/README.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. diff --git a/skills/_lib/lumina_skills/README.md b/skills/_lib/lumina_skills/README.md new file mode 100644 index 0000000..dbaa06d --- /dev/null +++ b/skills/_lib/lumina_skills/README.md @@ -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 diff --git a/skills/_lib/lumina_skills/providers/books/.gitkeep b/skills/_lib/lumina_skills/providers/books/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/_lib/lumina_skills/providers/mcp/.gitkeep b/skills/_lib/lumina_skills/providers/mcp/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/_lib/lumina_skills/providers/scheduling/.gitkeep b/skills/_lib/lumina_skills/providers/scheduling/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/ap-bills-due/README.md b/skills/ap-bills-due/README.md new file mode 100644 index 0000000..6f97025 --- /dev/null +++ b/skills/ap-bills-due/README.md @@ -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). diff --git a/skills/ap-bills-due/scripts/.gitkeep b/skills/ap-bills-due/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/ar-open-invoices/README.md b/skills/ar-open-invoices/README.md new file mode 100644 index 0000000..a773092 --- /dev/null +++ b/skills/ar-open-invoices/README.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). diff --git a/skills/ar-open-invoices/scripts/.gitkeep b/skills/ar-open-invoices/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/availability/README.md b/skills/availability/README.md new file mode 100644 index 0000000..f5d4549 --- /dev/null +++ b/skills/availability/README.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). diff --git a/skills/availability/scripts/.gitkeep b/skills/availability/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/books-snapshot/README.md b/skills/books-snapshot/README.md new file mode 100644 index 0000000..de25a8a --- /dev/null +++ b/skills/books-snapshot/README.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). diff --git a/skills/books-snapshot/scripts/.gitkeep b/skills/books-snapshot/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/client-card/README.md b/skills/client-card/README.md new file mode 100644 index 0000000..fccb5a8 --- /dev/null +++ b/skills/client-card/README.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). diff --git a/skills/client-card/scripts/.gitkeep b/skills/client-card/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/daily-board/README.md b/skills/daily-board/README.md new file mode 100644 index 0000000..7aeaf9c --- /dev/null +++ b/skills/daily-board/README.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). diff --git a/skills/daily-board/scripts/.gitkeep b/skills/daily-board/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/draft-client-message/README.md b/skills/draft-client-message/README.md new file mode 100644 index 0000000..52565a2 --- /dev/null +++ b/skills/draft-client-message/README.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). diff --git a/skills/draft-client-message/scripts/.gitkeep b/skills/draft-client-message/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/draft-invoice/README.md b/skills/draft-invoice/README.md new file mode 100644 index 0000000..0ee99b3 --- /dev/null +++ b/skills/draft-invoice/README.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). diff --git a/skills/draft-invoice/scripts/.gitkeep b/skills/draft-invoice/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/publish-boundary-test/README.md b/skills/publish-boundary-test/README.md new file mode 100644 index 0000000..4899a59 --- /dev/null +++ b/skills/publish-boundary-test/README.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). diff --git a/skills/publish-boundary-test/scripts/.gitkeep b/skills/publish-boundary-test/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/remember-forget/README.md b/skills/remember-forget/README.md new file mode 100644 index 0000000..f2a2240 --- /dev/null +++ b/skills/remember-forget/README.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). diff --git a/skills/remember-forget/scripts/.gitkeep b/skills/remember-forget/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/retail-stock/README.md b/skills/retail-stock/README.md new file mode 100644 index 0000000..a9bbfbf --- /dev/null +++ b/skills/retail-stock/README.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). diff --git a/skills/retail-stock/scripts/.gitkeep b/skills/retail-stock/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/service-menu/README.md b/skills/service-menu/README.md new file mode 100644 index 0000000..acfae5e --- /dev/null +++ b/skills/service-menu/README.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). diff --git a/skills/service-menu/scripts/.gitkeep b/skills/service-menu/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/setup-education/README.md b/skills/setup-education/README.md new file mode 100644 index 0000000..8d59333 --- /dev/null +++ b/skills/setup-education/README.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). diff --git a/skills/setup-education/scripts/.gitkeep b/skills/setup-education/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/social-draft/README.md b/skills/social-draft/README.md new file mode 100644 index 0000000..5a94567 --- /dev/null +++ b/skills/social-draft/README.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). diff --git a/skills/social-draft/scripts/.gitkeep b/skills/social-draft/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/vendor-inbox/README.md b/skills/vendor-inbox/README.md new file mode 100644 index 0000000..e087291 --- /dev/null +++ b/skills/vendor-inbox/README.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). diff --git a/skills/vendor-inbox/scripts/.gitkeep b/skills/vendor-inbox/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/vendor-spend/README.md b/skills/vendor-spend/README.md new file mode 100644 index 0000000..d919d46 --- /dev/null +++ b/skills/vendor-spend/README.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). diff --git a/skills/vendor-spend/scripts/.gitkeep b/skills/vendor-spend/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/skills/weekly-digest/README.md b/skills/weekly-digest/README.md new file mode 100644 index 0000000..5cca76c --- /dev/null +++ b/skills/weekly-digest/README.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). diff --git a/skills/weekly-digest/scripts/.gitkeep b/skills/weekly-digest/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..ef5c4f1 --- /dev/null +++ b/tests/README.md @@ -0,0 +1,12 @@ +# Tests (scaffold) + +**Status:** Structure only — no product tests until **build**. + +| Path | Purpose | +|------|---------| +| `unit/` | Deterministic domain/skill logic (no live model required) | +| `contract/` | Provider/MCP allow-deny contracts | +| `integration/` | Optional cheap-model dialogue paths | +| `fixtures/` | Test-only fixtures | + +Design boundary: [design/det-vs-inf.md](../design/det-vs-inf.md). diff --git a/tests/contract/.gitkeep b/tests/contract/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tests/fixtures/.gitkeep b/tests/fixtures/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tests/integration/.gitkeep b/tests/integration/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tests/unit/.gitkeep b/tests/unit/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tools/.gitkeep b/tools/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 0000000..e6a5cac --- /dev/null +++ b/tools/README.md @@ -0,0 +1,3 @@ +# Tools (scaffold) + +Optional host-side developer helpers. Empty until **build**.