Ty
76df8b7ab6
Add owner-safe lesson catalog, fixture-backed capability statuses, CLI, and unit tests without live OAuth or connect scripts.
136 lines
3.9 KiB
Markdown
136 lines
3.9 KiB
Markdown
---
|
||
name: setup-education
|
||
description: "Owner-safe connect education and capability report"
|
||
domain: system
|
||
---
|
||
|
||
# setup-education
|
||
|
||
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,
|
||
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
|
||
|
||
- 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
|