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.
2026-07-27 12:51:07 -07:00
parent 15f6a6c713
commit 69b67498ff
5 changed files with 258 additions and 64 deletions
@@ -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.