Ty_Tech/Salon_Assistant
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document project strategy and flow in READMEs.

Browse Source 
Replace stale scaffold-only status with install progress, actor split, and design vs docs vs skills maps so operators can follow the product narrative.
This commit is contained in:
Ty
2026-07-27 12:51:07 -07:00
parent 15f6a6c713
commit 69b67498ff
5 changed files with 258 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+128 -22
View File
@@ -4,16 +4,86 @@ Docker-based **NemoClaw + Hermes** personal ops assistant for a salon/spa owner-
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** |
## What this is
Lumina packages a minimal Hermes sandbox so a salon owner can ask, in plain language on WhatsApp/Email/Telegram, what's happening today — appointments, gaps, bills due, stock low — and get draft messages to clients or vendors. The assistant reads from the owner's existing SaaS (Vagaro, Square, QuickBooks Online) via MCP or REST. It never sends or publishes on the owner's behalf; it drafts, the owner decides.
All privileged mutations (sandbox, policy, credentials, channels, inference) go through **`nemohermes` / `openshell`** host CLIs. Product scripts wrap those CLIs. There is no custom control API.
---
## How the project flows
```
design/ docs/ scripts/ skills/
(why + what) (how-to) (host wrappers) (behavior)
│ │ │ │
├─ DESIGN_PLAN.md ├─ INSTALL.md ├─ bootstrap.sh ├─ daily-board/
├─ use-cases.md ├─ UPGRADE.md ├─ install.sh ├─ availability/
├─ scenarios.md ├─ OPERATIONS.md ├─ doctor.sh ├─ client-card/
├─ DECISIONS.md ├─ SETUP_UX.md ├─ upgrade.sh ├─ ...
└─ specialty docs └─ providers/ └─ connect/*.sh └─ _lib/
```
### Narrative flow
```
Owner says "build"
→ Agent reads design/ (SSOT) for the slice to implement
→ Agent implements: scripts, skills, tests
→ Agent runs review + check gates
→ Code lands on a branch (commit only when asked; push only when asked)
Deployer (operator) on host
→ make bootstrap (S0b: Docker if missing)
→ make install (S1–S5: env, models, sandbox, policy, skills)
→ make doctor (S6: health checks)
→ connect helpers (S7: register owner's SaaS — pending)
Runtime
→ OpenShell gateway (credentials, L7 policy, sandbox lifecycle)
→ Hermes sandbox (skills, channels, MCP clients — allowlisted)
→ External model endpoint (inference, vision aux)
Owner chats
→ WhatsApp / Email / Telegram
→ Assistant answers from deterministic facts (tools/fixtures)
→ Model ranks and words; drafts outbound; owner sends
```
---
## Strategy (plain language)
- **Platform-first.** All sandbox, policy, credential, channel, and inference mutations go through `nemohermes` / `openshell`. Product scripts wrap those CLIs. No parallel control API.
- **Two actors.** Technical operator runs host scripts (install, connect, upgrade, doctor). Salon owner chats only — never sees terminal, Docker, or editor instructions.
- **Fixtures-first.** Skills use JSON fixtures until live SaaS connect (S7 / MCP). Output always labels fixture data so the owner never sees silent fake live data.
- **Draft-only outbound.** The assistant drafts client/vendor messages; the owner sends or posts. No silent send, publish, or pay.
- **Deterministic facts, model for wording.** Code computes appointments, gaps, thresholds, and JSON→domain objects. The model ranks, paraphrases, and generates drafts within style constraints.
- **No agent pay.** Refused by OpenShell policy + skill hard-fail + model refusal.
- **Auto-updates on by default.** Owner-transparent; operator can disable. Rollback available.
---
## Install stages
| Stage | What | Status |
|-------|------|--------|
| S0 | Host baselining (human) | ✅ Procedural |
| S0b | Docker bootstrap | ✅ Implemented |
| S1 | `.env` from `.env.example` | ✅ Implemented |
| S2 | Model + vision config; vision smoke | ✅ Implemented |
| S3 | Stack alignment (OpenShell owns sandbox) | ✅ Implemented |
| S4 | Sandbox verify (attach) or onboard | ✅ Implemented |
| S5 | Policy overlays + skills sync | ✅ Implemented |
| S6 | Doctor (health checks) | ✅ Implemented |
| S7 | Owner connect + operator connect helpers | ⏳ Pending |
Full install guide: [docs/INSTALL.md](docs/INSTALL.md) · Script details: [scripts/README.md](scripts/README.md)
---
## Product planes
@@ -24,25 +94,61 @@ This directory is the **product seed** for the Gitea repository `Ty_Tech/Salon_A
| 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) |
| Identity & memory | Named assistant; confirmed preferences |
| Setup & education | Install, then connect their SaaS |
| Control | OpenShell policy + Hermes security + skill contracts |
| Observability | Logs, health, structured events, redaction |
## Doc placement
Full detail: [design/planes.md](design/planes.md)
| Folder | Purpose |
|--------|---------|
---
## Doc map
| Location | Purpose |
|----------|---------|
| **`design/`** | Product design SSOT — plan, use cases, scenarios, decisions, MCP strategy, update lifecycle |
| **`docs/`** | Operator/user manuals — install, upgrade, providers, ops |
| **`docs/`** | Operator runbooks — install, upgrade, providers, ops |
| **`AGENTS.md`** | Agent rails — execution loop, Git hygiene, orchestrator/worker split |
| **`scripts/`** | Host wrappers around Docker + `nemohermes`/`openshell` |
| **`skills/`** | Product behavior — deterministic scripts, fixtures, SKILL.md contracts |
## 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.
## Implementation progress
## Layout (scaffolds)
Implementation queue: [design/IMPLEMENT_QUEUE.md](design/IMPLEMENT_QUEUE.md)
Code under `skills/`, `scripts/`, `services/`, `policy/`, etc. is **scaffold only** until **build**. See each area’s `README.md`.
| Task | Slice | Status |
|------|-------|--------|
| Task 1 | S0–S2 (bootstrap, env, models, vision smoke) | ✅ Done |
| Task 2 | S3–S5 (stack, sandbox, policy, skills sync) | ✅ Done |
| Task 3 | S6 (doctor health checks) | ✅ Done |
| Task 4 | A1 daily-board (fixtures-only) | ✅ Done |
| Task 5 | E1 setup-education | ⏳ Next |
## Remote
---
- Gitea: `Ty_Tech/Salon_Assistant` (public)
- Git MCP for this product: **`gitea_vps`** only
- **Agents:** mandatory **execution loop**, **local-worker split** (Grok orchestrates; **Primary Subagent** / `primary-subagent` on `:8083` does product work), and **Git hygiene** in [`AGENTS.md`](AGENTS.md) (also `CLAUDE.md`, `.grok/rules/*`). Agents must follow the rails without the user restating process. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for branch/PR conventions.
## Repository layout
| Path | Purpose |
|------|---------|
| `design/` | Design SSOT (plan, use cases, scenarios, decisions, planes, det-vs-inf, MCP, updates) |
| `docs/` | Operator manuals (install, upgrade, operations, providers, policy, setup UX) |
| `scripts/` | Host scripts: bootstrap, install stages, doctor, upgrade, connect helpers |
| `skills/` | Skill directories (daily-board implemented; others scaffolded) + `_lib/` shared code |
| `policy/openshell/` | Policy overlays applied during S5 |
| `agents/hermes/` | Agent package manifest, identity templates, config fragments |
| `deploy/compose/` | Docker Compose (optional; OpenShell owns sandbox) |
| `data/fixtures/` | JSON fixtures for skills (scheduling, books, etc.) |
| `tests/` | Unit tests for deterministic code |
| `observability/` | Structured event definitions |
| `migrations/` | State migrations for upgrades |
---
## Remote / agent notes
- **Gitea:** `Ty_Tech/Salon_Assistant`
- **Git MCP:** `gitea_vps` only (never `gitea_mcp_for_ty` or localhost Git MCP)
- **Agent rails:** Mandatory execution loop, local-worker split (Grok orchestrates; Primary Subagent on `:8083` does product work), and Git hygiene — all in [`AGENTS.md`](AGENTS.md). See [`CONTRIBUTING.md`](CONTRIBUTING.md) for branch/PR conventions.