# Design pack (product SSOT)

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.

---

## Reading 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.