Implement E1 setup-education and capability report (fixtures).

Add owner-safe lesson catalog, fixture-backed capability statuses, CLI, and unit tests without live OAuth or connect scripts.
2026-07-27 13:10:57 -07:00
parent 69b67498ff
commit 76df8b7ab6
16 changed files with 1955 additions and 7 deletions
@@ -10,9 +10,126 @@ Owner-safe connect education and capability report.

 ## Description

-Guides the owner through connecting their SaaS integrations (Square, QBO, Vagaro) and messaging channels. Provides a capability report showing what is connected.
+Guides the owner through connecting their SaaS integrations (Square, QBO, Vagaro)
+and messaging channels. Provides a capability report showing what is connected,
+what is offline/fixtures, and what was skipped.
+
+All education text is **owner-safe**: browser/vendor UI steps only. Never
+terminal, docker, nano, or shell instructions.
+
+## What it does
+
+- Presents 7 setup education lessons (matching `docs/SETUP_UX.md` steps 1–7)
+- Builds a capability report from fixture or live connection state
+- Labels all fixture data as `📋 FIXTURE DATA` — never silent fake live data
+- Validates that education text never contains forbidden keywords
+- Outputs structured text or JSON
+
+## Data sources
+
+| Source | Status | Label in output |
+|--------|--------|-----------------|
+| Fixtures (JSON) | ✅ Implemented | `📋 FIXTURE DATA` |
+| Live connection state | Not yet | `LIVE DATA` (future) |

 ## Constraints

- Owner-safe: no terminal instructions.
- Browser/vendor UI steps only.
+- Deterministic facts from fixtures; no model inference for capability data.
+- Owner-safe: no terminal/docker/nano/shell instructions in education text.
+- Fixtures/stubs only — no real OAuth, no live secrets.
+- Fixture `is_fixture` flag always `true` — never silent as live.
+
+## Usage
+
+### CLI
+
+```bash
+# Build capability report from fixtures (default demo data)
+python skills/setup-education/scripts/build_capability_report.py
+
+# JSON output
+python skills/setup-education/scripts/build_capability_report.py --format json
+
+# Show a specific lesson
+python skills/setup-education/scripts/build_capability_report.py --lesson 4
+
+# Show all lessons
+python skills/setup-education/scripts/build_capability_report.py --all-lessons
+
+# Use a different fixture
+python skills/setup-education/scripts/build_capability_report.py \
+  --fixtures data/fixtures/setup/capability_matrix_all_connected.json
+```
+
+### Programmatic
+
+```python
+from lumina_skills.providers.setup.fixture_provider import load_capability_fixture
+from lumina_skills.setup.capability_report import format_capability_report_text
+from lumina_skills.setup.lesson_catalog import get_lesson, format_lesson_text
+
+# Capability report
+report = load_capability_fixture("data/fixtures/setup/capability_matrix.json")
+print(format_capability_report_text(report))
+
+# Individual lesson
+lesson = get_lesson(4)
+print(format_lesson_text(lesson))
+```
+
+## Output format
+
+### Text (default)
+
+Structured text grouped by area (identity, profile, channels, scheduling, books)
+with emoji status labels and a summary line.
+
+### JSON
+
+```json
+{
+  "salon_name": "Lumina Hair Studio & Spa",
+  "is_fixture": true,
+  "capabilities": [
+    {
+      "area": "channels",
+      "provider": "whatsapp",
+      "status": "connected",
+      "label": "✅ Connected",
+      "details": "WhatsApp channel active"
+    }
+  ],
+  "summary": {
+    "connected": 4,
+    "offline": 2,
+    "skipped_or_later": 2,
+    "errors": 0,
+    "all_connected": false
+  }
+}
+```
+
+## Files
+
+| Path | Purpose |
+|------|---------|
+| `SKILL.md` | Skill spec and usage |
+| `scripts/build_capability_report.py` | CLI entrypoint |
+| `../../skills/_lib/lumina_skills/setup/capability_report.py` | Domain model + builder |
+| `../../skills/_lib/lumina_skills/setup/lesson_catalog.py` | Static lesson steps |
+| `../../skills/_lib/lumina_skills/providers/setup/fixture_provider.py` | Fixture loader |
+| `../../data/fixtures/setup/` | Fixture JSON files |
+
+## Design references
+
+- Use case: [E1 — Educational setup](../../design/use-cases.md)
+- Use case: [E6 — Capability report](../../design/use-cases.md)
+- Use case: [E7 — Degraded mode](../../design/use-cases.md)
+- Setup UX: [docs/SETUP_UX.md](../../docs/SETUP_UX.md)
+- Deterministic boundary: [design/det-vs-inf.md](../../design/det-vs-inf.md)
+
+## Future
+
+- Live connection state provider (replaces fixtures)
+- Per-lesson progress tracking
+- Automated lesson sequencing