From 48566993f63c02c4ebfa0d734fa0a1cec6117dd6 Mon Sep 17 00:00:00 2001 From: Ty Date: Mon, 27 Jul 2026 09:44:35 -0700 Subject: [PATCH] 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. --- .github/ISSUE_TEMPLATE/.gitkeep | 0 .github/workflows/README.md | 5 + .gitignore | 11 + AGENTS.md | 29 ++ CHANGELOG.md | 19 + CODEOWNERS | 2 + CONTRIBUTING.md | 35 ++ LICENSE | 17 + Makefile | 23 ++ README.md | 47 +++ SECURITY.md | 21 ++ VERSION | 1 + agents/hermes/README.md | 13 + agents/hermes/config/.gitkeep | 0 agents/hermes/skills-manifest/.gitkeep | 0 data/fixtures/README.md | 11 + data/fixtures/books/.gitkeep | 0 data/fixtures/media/.gitkeep | 0 data/recorded/.gitkeep | 0 deploy/compose/README.md | 5 + deploy/systemd/README.md | 5 + design/DECISIONS.md | 100 +++++ design/DESIGN_PLAN.md | 343 ++++++++++++++++++ design/README.md | 18 + design/det-vs-inf.md | 20 + design/diagrams/README.md | 4 + design/mcp-integrations.md | 31 ++ design/planes.md | 15 + design/research/platform-notes.md | 26 ++ design/scenarios.md | 199 ++++++++++ design/updates-lifecycle.md | 75 ++++ design/use-cases.md | 276 ++++++++++++++ docs/ARCHITECTURE.md | 21 ++ docs/DEPLOYER_HOST.md | 29 ++ docs/HERMES_MODELS.md | 13 + docs/INSTALL.md | 31 ++ docs/OPERATIONS.md | 24 ++ docs/POLICY.md | 16 + docs/README.md | 17 + docs/SETUP_UX.md | 27 ++ docs/UPGRADE.md | 22 ++ docs/adr/README.md | 5 + docs/install/README.md | 3 + docs/ops/README.md | 3 + docs/providers/channels.md | 10 + docs/providers/quickbooks.md | 8 + docs/providers/square.md | 8 + docs/providers/vagaro.md | 8 + migrations/.gitkeep | 0 migrations/README.md | 5 + observability/README.md | 8 + observability/schema/.gitkeep | 0 policy/openshell/README.md | 14 + policy/openshell/overlays/.gitkeep | 0 scripts/README.md | 19 + scripts/connect/.gitkeep | 0 scripts/install/.gitkeep | 0 scripts/lib/.gitkeep | 0 services/README.md | 11 + services/qbo-mcp/README.md | 7 + services/salon-ops-api/README.md | 7 + services/vagaro-webhooks/README.md | 7 + skills/README.md | 30 ++ skills/_lib/lumina_skills/README.md | 9 + .../lumina_skills/providers/books/.gitkeep | 0 .../_lib/lumina_skills/providers/mcp/.gitkeep | 0 .../providers/scheduling/.gitkeep | 0 skills/ap-bills-due/README.md | 5 + skills/ap-bills-due/scripts/.gitkeep | 0 skills/ar-open-invoices/README.md | 5 + skills/ar-open-invoices/scripts/.gitkeep | 0 skills/availability/README.md | 5 + skills/availability/scripts/.gitkeep | 0 skills/books-snapshot/README.md | 5 + skills/books-snapshot/scripts/.gitkeep | 0 skills/client-card/README.md | 5 + skills/client-card/scripts/.gitkeep | 0 skills/daily-board/README.md | 5 + skills/daily-board/scripts/.gitkeep | 0 skills/draft-client-message/README.md | 5 + skills/draft-client-message/scripts/.gitkeep | 0 skills/draft-invoice/README.md | 5 + skills/draft-invoice/scripts/.gitkeep | 0 skills/publish-boundary-test/README.md | 5 + skills/publish-boundary-test/scripts/.gitkeep | 0 skills/remember-forget/README.md | 5 + skills/remember-forget/scripts/.gitkeep | 0 skills/retail-stock/README.md | 5 + skills/retail-stock/scripts/.gitkeep | 0 skills/service-menu/README.md | 5 + skills/service-menu/scripts/.gitkeep | 0 skills/setup-education/README.md | 5 + skills/setup-education/scripts/.gitkeep | 0 skills/social-draft/README.md | 5 + skills/social-draft/scripts/.gitkeep | 0 skills/vendor-inbox/README.md | 5 + skills/vendor-inbox/scripts/.gitkeep | 0 skills/vendor-spend/README.md | 5 + skills/vendor-spend/scripts/.gitkeep | 0 skills/weekly-digest/README.md | 5 + skills/weekly-digest/scripts/.gitkeep | 0 tests/README.md | 12 + tests/contract/.gitkeep | 0 tests/fixtures/.gitkeep | 0 tests/integration/.gitkeep | 0 tests/unit/.gitkeep | 0 tools/.gitkeep | 0 tools/README.md | 3 + 108 files changed, 1813 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/.gitkeep create mode 100644 .github/workflows/README.md create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 CHANGELOG.md create mode 100644 CODEOWNERS create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 Makefile create mode 100644 README.md create mode 100644 SECURITY.md create mode 100644 VERSION create mode 100644 agents/hermes/README.md create mode 100644 agents/hermes/config/.gitkeep create mode 100644 agents/hermes/skills-manifest/.gitkeep create mode 100644 data/fixtures/README.md create mode 100644 data/fixtures/books/.gitkeep create mode 100644 data/fixtures/media/.gitkeep create mode 100644 data/recorded/.gitkeep create mode 100644 deploy/compose/README.md create mode 100644 deploy/systemd/README.md create mode 100644 design/DECISIONS.md create mode 100644 design/DESIGN_PLAN.md create mode 100644 design/README.md create mode 100644 design/det-vs-inf.md create mode 100644 design/diagrams/README.md create mode 100644 design/mcp-integrations.md create mode 100644 design/planes.md create mode 100644 design/research/platform-notes.md create mode 100644 design/scenarios.md create mode 100644 design/updates-lifecycle.md create mode 100644 design/use-cases.md create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/DEPLOYER_HOST.md create mode 100644 docs/HERMES_MODELS.md create mode 100644 docs/INSTALL.md create mode 100644 docs/OPERATIONS.md create mode 100644 docs/POLICY.md create mode 100644 docs/README.md create mode 100644 docs/SETUP_UX.md create mode 100644 docs/UPGRADE.md create mode 100644 docs/adr/README.md create mode 100644 docs/install/README.md create mode 100644 docs/ops/README.md create mode 100644 docs/providers/channels.md create mode 100644 docs/providers/quickbooks.md create mode 100644 docs/providers/square.md create mode 100644 docs/providers/vagaro.md create mode 100644 migrations/.gitkeep create mode 100644 migrations/README.md create mode 100644 observability/README.md create mode 100644 observability/schema/.gitkeep create mode 100644 policy/openshell/README.md create mode 100644 policy/openshell/overlays/.gitkeep create mode 100644 scripts/README.md create mode 100644 scripts/connect/.gitkeep create mode 100644 scripts/install/.gitkeep create mode 100644 scripts/lib/.gitkeep create mode 100644 services/README.md create mode 100644 services/qbo-mcp/README.md create mode 100644 services/salon-ops-api/README.md create mode 100644 services/vagaro-webhooks/README.md create mode 100644 skills/README.md create mode 100644 skills/_lib/lumina_skills/README.md create mode 100644 skills/_lib/lumina_skills/providers/books/.gitkeep create mode 100644 skills/_lib/lumina_skills/providers/mcp/.gitkeep create mode 100644 skills/_lib/lumina_skills/providers/scheduling/.gitkeep create mode 100644 skills/ap-bills-due/README.md create mode 100644 skills/ap-bills-due/scripts/.gitkeep create mode 100644 skills/ar-open-invoices/README.md create mode 100644 skills/ar-open-invoices/scripts/.gitkeep create mode 100644 skills/availability/README.md create mode 100644 skills/availability/scripts/.gitkeep create mode 100644 skills/books-snapshot/README.md create mode 100644 skills/books-snapshot/scripts/.gitkeep create mode 100644 skills/client-card/README.md create mode 100644 skills/client-card/scripts/.gitkeep create mode 100644 skills/daily-board/README.md create mode 100644 skills/daily-board/scripts/.gitkeep create mode 100644 skills/draft-client-message/README.md create mode 100644 skills/draft-client-message/scripts/.gitkeep create mode 100644 skills/draft-invoice/README.md create mode 100644 skills/draft-invoice/scripts/.gitkeep create mode 100644 skills/publish-boundary-test/README.md create mode 100644 skills/publish-boundary-test/scripts/.gitkeep create mode 100644 skills/remember-forget/README.md create mode 100644 skills/remember-forget/scripts/.gitkeep create mode 100644 skills/retail-stock/README.md create mode 100644 skills/retail-stock/scripts/.gitkeep create mode 100644 skills/service-menu/README.md create mode 100644 skills/service-menu/scripts/.gitkeep create mode 100644 skills/setup-education/README.md create mode 100644 skills/setup-education/scripts/.gitkeep create mode 100644 skills/social-draft/README.md create mode 100644 skills/social-draft/scripts/.gitkeep create mode 100644 skills/vendor-inbox/README.md create mode 100644 skills/vendor-inbox/scripts/.gitkeep create mode 100644 skills/vendor-spend/README.md create mode 100644 skills/vendor-spend/scripts/.gitkeep create mode 100644 skills/weekly-digest/README.md create mode 100644 skills/weekly-digest/scripts/.gitkeep create mode 100644 tests/README.md create mode 100644 tests/contract/.gitkeep create mode 100644 tests/fixtures/.gitkeep create mode 100644 tests/integration/.gitkeep create mode 100644 tests/unit/.gitkeep create mode 100644 tools/.gitkeep create mode 100644 tools/README.md 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**.