From 69b67498ff3b71d727777912b3b435baa47fc4d1 Mon Sep 17 00:00:00 2001 From: Ty Date: Mon, 27 Jul 2026 12:51:07 -0700 Subject: [PATCH] Document project strategy and flow in READMEs. Replace stale scaffold-only status with install progress, actor split, and design vs docs vs skills maps so operators can follow the product narrative. --- README.md | 150 ++++++++++++++++++++++++++++++++++++------- design/README.md | 64 ++++++++++++++---- docs/ARCHITECTURE.md | 4 ++ docs/README.md | 34 ++++++++-- skills/README.md | 70 +++++++++++++------- 5 files changed, 258 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 027e1f4..3c610da 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/design/README.md b/design/README.md index b43ed77..8ddb0d4 100644 --- a/design/README.md +++ b/design/README.md @@ -1,18 +1,56 @@ # Design pack (product SSOT) -This folder is the **product design source of truth** for Salon_Assistant / Lumina. +This folder is the **product design source of truth** for Salon_Assistant / Lumina. Operator runbooks live under [`../docs/`](../docs/) and link here for design rationale. -| 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. +## Reading order -**Implementation** of code under `skills/`, `scripts/`, etc. requires an explicit **build** / **implement** order. +1. **[DESIGN_PLAN.md](DESIGN_PLAN.md)** — Architecture, install stages, MCP strategy, update lifecycle, success criteria. Read this first. +2. **[use-cases.md](use-cases.md)** — Use-case catalog (SSOT — do not duplicate full matrices elsewhere). +3. **[scenarios.md](scenarios.md)** — Narrative scenarios for design validation and future tests. +4. **[DECISIONS.md](DECISIONS.md)** — Resolved decisions from planning. +5. **Specialty docs** (as needed): + +| Document | When to read | +|----------|-------------| +| [planes.md](planes.md) | Capability planes (scheduling, books, comms, drafts, social, identity, setup, control, observability) | +| [det-vs-inf.md](det-vs-inf.md) | Deterministic code vs model inference boundary | +| [mcp-integrations.md](mcp-integrations.md) | Square / QBO / Vagaro / channel integration details | +| [updates-lifecycle.md](updates-lifecycle.md) | Software update model, vectors, rollback | + +--- + +## IMPLEMENT_QUEUE.md + +[IMPLEMENT_QUEUE.md](IMPLEMENT_QUEUE.md) contains the first 5 implementation tasks. Paste **one line at a time** into the orchestrator (Grok Build). Do not paste the whole file. + +| 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 | + +--- + +## What each file is for + +- **DESIGN_PLAN.md** — The master plan. Architecture, install stages S0–S7, MCP strategy, update lifecycle, success criteria, non-goals. If you need to know "how does this product work at a high level," start here. +- **use-cases.md** — Every use case the product supports. This is the catalog that skills implement against. Do not copy full use-case matrices into other docs. +- **scenarios.md** — Narrative walkthroughs (e.g., "S8: Morning board on WhatsApp"). Used for design validation and as the basis for future integration tests. +- **DECISIONS.md** — Decisions already made during planning. Read before proposing alternatives. +- **planes.md** — Capability planes: what each domain (scheduling, books, comms, etc.) covers and which systems it touches. +- **det-vs-inf.md** — The boundary between deterministic code (always correct, testable offline) and model inference (ranking, wording, drafts). Skills must respect this split. +- **mcp-integrations.md** — How each SaaS (Square, QBO, Vagaro) connects: remote vs local MCP, allow/deny lists. +- **updates-lifecycle.md** — Full update model: 30 content vectors, rollback, suppressing Hermes interactive updates, instrumentation. + +--- + +## Current implementation state (high level) + +- **Install stages S0–S6:** Implemented (scripts, `make install`, `make doctor`). S7 pending. +- **Skills:** `daily-board/` + `_lib/` implemented (fixtures-only, with unit tests). All other skill directories have SKILL.md scaffolds only. +- **Upgrade:** `upgrade.sh` pending. +- **Connect helpers:** `connect/*.sh` pending. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index d3731fb..b0a2069 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -12,6 +12,10 @@ Host (bootstrap, Docker, product scripts, nemohermes/openshell CLIs) → External OpenAI-compatible model (outside containers OK) ``` +## How it flows + +For the end-to-end narrative (design → implement → install → runtime → owner chat), see the **[root README](../README.md)** section "How the project flows." + ## Related design docs - [Planes](../design/planes.md) diff --git a/docs/README.md b/docs/README.md index 3a2f0d8..f08171a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,16 +2,36 @@ Runbooks and how-tos. **Product design SSOT** is under [`../design/`](../design/). +| Location | Purpose | +|----------|---------| +| `design/` | Why and what — architecture, use cases, scenarios, decisions | +| `docs/` | How-to — install, upgrade, operations, providers, policy | + +--- + +## Document status + | 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 | +| [DEPLOYER_HOST.md](DEPLOYER_HOST.md) | Create/baseline host requirements | ✅ Procedural — ready for operator use | +| [INSTALL.md](INSTALL.md) | Install stages S0–S6 | ✅ Implemented | +| [HERMES_MODELS.md](HERMES_MODELS.md) | Main + auxiliary models | ✅ S2-ready | +| [OPERATIONS.md](OPERATIONS.md) | Day-2 logs, doctor | ✅ Doctor (S6) implemented | | [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) | +| [UPGRADE.md](UPGRADE.md) | Upgrade / rollback | Outline — full design in [design/updates-lifecycle.md](../design/updates-lifecycle.md) | +| [ARCHITECTURE.md](ARCHITECTURE.md) | Operator-facing architecture summary | Outline → links design | | [providers/](providers/) | Square, QBO, Vagaro, channels | Outlines | -Implementation of install scripts is **not** started until **build**. +--- + +## What's done vs planned + +**Done (scripts implemented, callable via `make`):** +- S0b: Docker bootstrap (`make bootstrap`) +- S1–S5: Full install (`make install`) +- S6: Doctor health checks (`make doctor`) + +**Pending:** +- S7: Owner connect + operator connect helpers (`connect/*.sh`) +- Upgrade: `upgrade.sh` (snapshot, pull, migrate, re-apply policy, doctor) diff --git a/skills/README.md b/skills/README.md index 77d3078..a934691 100644 --- a/skills/README.md +++ b/skills/README.md @@ -1,30 +1,56 @@ -# Skills (scaffold) +# Skills -**Status:** Directory layout only. No skill scripts or SKILL.md bodies until **build**. +Product behavior: deterministic scripts, fixtures, and SKILL.md contracts. See use-case catalog: [design/use-cases.md](../design/use-cases.md). -## Planned skill families +--- + +## How skills fit the flow + +``` +design/use-cases.md skills// skills/_lib/ +(use-case spec) (SKILL.md + scripts/) (shared providers) + │ │ │ + ├─ A1 daily-board ├─ SKILL.md ├─ domain.py + ├─ B1 books-snapshot ├─ scripts/*.py ├─ board_builder.py + ├─ ... └─ fixtures/ └─ providers/ + │ (scheduling, books, mcp) +``` + +Each skill directory maps to one or more use cases. The SKILL.md defines the contract (inputs, outputs, constraints). Scripts implement deterministic logic. Providers fetch data from fixtures (now) or live SaaS (later via MCP/REST). + +--- + +## Status | 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** | +| `daily-board/` | ✅ Implemented — fixtures-only, with `build_board.py` script | +| `_lib/lumina_skills/` | ✅ Implemented — domain models, board builder, fixture providers | +| `availability/` | Scaffold — SKILL.md only | +| `client-card/` | Scaffold — SKILL.md only | +| `service-menu/` | Scaffold — SKILL.md only | +| `retail-stock/` | Scaffold — SKILL.md only | +| `books-snapshot/` | Scaffold — SKILL.md only | +| `ar-open-invoices/` | Scaffold — SKILL.md only | +| `ap-bills-due/` | Scaffold — SKILL.md only | +| `vendor-spend/` | Scaffold — SKILL.md only | +| `vendor-inbox/` | Scaffold — SKILL.md only | +| `draft-invoice/` | Scaffold — SKILL.md only | +| `draft-client-message/` | Scaffold — SKILL.md only | +| `social-draft/` | Scaffold — SKILL.md only | +| `weekly-digest/` | Scaffold — SKILL.md only | +| `remember-forget/` | Scaffold — SKILL.md only | +| `setup-education/` | Scaffold — SKILL.md only (Task 5 next) | +| `publish-boundary-test/` | Scaffold — SKILL.md only | -Rules (from design): draft-first outbound; no agent payments; deterministic facts from tools; refuse silent send/publish. +--- + +## Rules (from design) + +- **Draft-first outbound.** Skills draft messages; the owner sends. No silent send, publish, or pay. +- **Deterministic facts from tools.** Code computes appointments, gaps, thresholds, JSON→domain objects. The model ranks and words. +- **Fixture data is labeled.** Output always marks `📋 FIXTURE DATA` so the owner never sees silent fake live data. +- **Refuse pay / silent send / publish.** Enforced by OpenShell policy + skill hard-fail + model refusal. +- **Det vs inference boundary:** [design/det-vs-inf.md](../design/det-vs-inf.md)