@soulcraft/kits 1.0.0

package/kits/escape-vault/skills/guest-letter/SKILL.md

@@ -0,0 +1,143 @@
+---
+id: guest-letter
+name: Guest Follow-Up Letter
+description: Generates a dramatic, personalized post-session follow-up letter for escape room guests referencing their team name, room, escape outcome, completion time, hints used, and specific performance moments — in Game Master voice.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: true
+---
+
+# Guest Follow-Up Letter
+
+You write personalized post-session follow-up letters for guests of **{{businessName}}**. Each letter is written in Game Master voice — admiring, conspiratorial, and specific. No two letters should feel the same. Every detail from the session data should be used.
+
+## When to Trigger
+
+Invoke this skill when staff or owners ask:
+- "Write a follow-up letter for [team name]"
+- "Post-session message for [booking]"
+- "Thank you letter for [guest name]"
+- "Personalized follow-up for today's sessions"
+
+## Input Data Available
+
+You will receive booking and session data including:
+
+```json
+{
+  "guestNames": ["Alex", "Jordan", "Sam"],
+  "teamName": "The Puzzle Breakers",
+  "date": "2026-05-17",
+  "locationName": "The Escape Vault Downtown",
+  "experienceSlug": "standard-room",
+  "sessionAttributes": [
+    { "key": "roomName",        "value": "The Clockmaker's Workshop" },
+    { "key": "completionTime",  "value": "54:32" },
+    { "key": "hintsUsed",       "value": "2" },
+    { "key": "escaped",         "value": "Yes! Escaped" },
+    { "key": "teamName",        "value": "The Puzzle Breakers" }
+  ],
+  "staffNotes": "Alex found the hidden gear mechanism in the clock immediately — huge help to the team. Jordan called out the cipher connection that most teams miss entirely.",
+  "loyaltyPointsEarned": 350
+}
+```
+
+---
+
+## Letter Structure (150–250 words)
+
+**1. Address the team**
+Open to the team name. Not "Dear Customer" — never generic.
+
+**2. Reference their specific outcome dramatically**
+The outcome is the emotional hook. Use it.
+
+- **Escaped**: Acknowledge the achievement with specific detail — not "great job" but reference the time, the hints used (or not used), how close or far from the record they were.
+  - "54:32. Two hints. The Clockmaker's Workshop completed. That puts you in the top quarter of all teams that have faced that room."
+- **Almost — X seconds remaining**: This is actually the most powerful outcome for re-engagement. Make the near-miss feel more dramatic than a win.
+  - "47 seconds. FORTY-SEVEN SECONDS. The workshop was yours, and then it wasn't. That is going to bother you for longer than you'd like to admit."
+- **Did not escape**: Be honest but non-deflationary. The room is hard. The team learned something.
+  - "The Clockmaker's Workshop has a 52% escape rate. You weren't in that half this time. Most of the teams who don't make it on the first try come back knowing exactly where they lost time. We'll see you again."
+
+**3. Acknowledge a specific performance detail**
+Use `staffNotes` if present. This is the most personal moment in the letter.
+- "One of you spotted something in the first five minutes that most teams don't notice until they're halfway through. That kind of observation under pressure is rare."
+- If staff notes name a specific person: acknowledge them by name.
+
+**4. Loyalty points earned**
+Mention briefly if present: "You earned [N] points toward your next visit."
+
+**5. The invitation to the next room**
+- If they escaped: invite them to the next room in the difficulty sequence. Name it specifically if possible.
+- If they didn't escape: invite them back to finish the business they started.
+- If they've done multiple rooms: acknowledge this and suggest the next challenge.
+
+**6. Closing**
+Short, in character. Signed as "The Vault" or "Your Game Master" — not a person's name (they don't need to know your name, they need to feel the venue's personality).
+
+---
+
+## Tone Guidelines
+
+**Game Master energy**: You've watched hundreds of teams. You've seen every pattern. You're impressed when teams earn it, and honest when they don't. You never condescend, but you never inflate — your praise means something because it's specific.
+
+**Conspiratorial**: The letter should feel like a note passed from someone who was watching the whole time and noticed everything. Not surveillance — acknowledgment.
+
+**A little daring**: End on a challenge. The invitation to return should never feel like a polite "hope to see you again." It should feel like "the room is still there. Come finish this."
+
+---
+
+## Outcome-Specific Templates (Guide Only — Write Naturally)
+
+### Escaped
+```
+[Team Name] —
+
+[Outcome statement with time and hints — dramatic, specific]
+
+[Performance acknowledgment from staffNotes]
+
+[Loyalty points note if applicable]
+
+[The vault has more. Name the next room or challenge. Dare them forward.]
+
+Your Game Master,
+{{locationName}}
+```
+
+### Almost — Seconds Remaining
+```
+[Team Name] —
+
+[The specific time remaining — name it. Make them feel it.]
+
+[What they did right — because they clearly did things right to get that close]
+
+[The specific moment they lost — if known from staffNotes]
+
+[The vault remembers. The clock is reset. When you're ready.]
+
+Your Game Master,
+{{locationName}}
+```
+
+### Did Not Escape
+```
+[Team Name] —
+
+[Honest assessment — the room is hard. The rate. The context.]
+
+[What they did right — there is always something]
+
+[The invitation — not sympathy, a rematch]
+
+Your Game Master,
+{{locationName}}
+```
+
+---
+
+## Output Format
+
+Return only the letter text. No headers. No JSON. No meta-commentary about the letter. The output IS the letter, ready to copy and send.

package/kits/escape-vault/skills/inventory-health/SKILL.md

@@ -0,0 +1,222 @@
+---
+id: inventory-health
+name: Inventory Health
+description: Monitors escape room prop and maintenance inventory across all rooms and categories, flags damaged props and locks approaching mechanical cycle limits, generates a room-by-room status report, and produces a prioritized maintenance and replacement queue.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: true
+---
+
+# Inventory Health
+
+You generate a comprehensive prop and maintenance inventory status report for **{{locationName}}**, flagging items requiring immediate attention, tracking lock cycle counts, and producing a prioritized replacement queue. Escape room inventory behaves fundamentally differently from consumable-based venues — props and locks are not used up, they are maintained and eventually replaced based on wear cycles and condition.
+
+## When to Trigger
+
+Invoke this skill when staff or owners ask:
+- "Check inventory"
+- "What needs replacing?"
+- "Prop status"
+- "Are the locks okay?"
+- "What should we order?"
+- "Maintenance queue"
+- Any question about room props, lock mechanisms, or operational supply levels
+
+## Data to Pull
+
+### Step 1 — All inventory items
+
+```typescript
+await brain.find({
+  type: 'Thing',
+  where: [
+    { field: 'metadata.entityType', value: 'inventory-item' },
+    { field: 'metadata.locationId', value: locationId }
+  ]
+});
+```
+
+Key fields per item: `metadata.name`, `metadata.category`, `metadata.quantity`, `metadata.reorderThreshold`, `metadata.costInCents`.
+
+Check `data` for condition notes — staff may have added condition flags ("cracked", "faded", "mechanism stiff", "battery replaced", "needs calibration") when logging inventory.
+
+### Step 2 — Upcoming sessions (next 7 days)
+
+```typescript
+await brain.find({
+  type: 'Event',
+  where: [
+    { field: 'metadata.entityType', value: 'booking' },
+    { field: 'metadata.locationId', value: locationId },
+    { field: 'metadata.status',     value: 'confirmed' }
+  ]
+  // Filter client-side: metadata.date >= today AND <= today+7
+});
+```
+
+From each booking, extract `data.sessionAttributes.roomName` to determine which rooms are active and require all props to be in service.
+
+### Step 3 — Session volume for cycle estimation
+
+Query the trailing 30 days of confirmed bookings, grouped by room, to estimate session count per room. Use this to calculate cumulative lock cycle counts.
+
+**Lock cycle estimation**: Each session = approximately 10–15 lock uses (opening + resetting). Use `sessions × 12` as a conservative cycle estimate per lock per room. Add to any baseline count stored in inventory item data.
+
+---
+
+## Inventory Categories and Alert Logic
+
+### Props (Room Props & Decorations)
+
+Props do not deplete per session but degrade over time. Alert logic:
+- **CRITICAL**: any prop flagged with condition note containing "broken", "non-functional", or "replace immediately"
+- **LOW**: any prop flagged with "worn", "faded", "cracked", "repair needed" — functional but degrading
+- **OK**: no condition notes, or condition notes indicating minor cosmetic wear only
+
+Props in a "damaged" or "non-functional" state must be removed from the room before the next session. Running a session with a broken prop that guests interact with undermines the puzzle and the experience.
+
+### Locks (Locks & Mechanisms)
+
+Locks have mechanical cycle limits. Replace at 5,000 cycles; flag for inspection at 4,500.
+
+**Cycle tracking formula**:
+```
+totalCycles = baselineCycles (stored in data) + (roomSessionsLast30Days × 12 × projectedMonthsInService)
+```
+
+If baseline cycles are not stored, estimate from the lock's install date and average session volume.
+
+| Cycle Count | Alert Level |
+|---|---|
+| < 4,500 cycles | OK |
+| 4,500 – 4,999 cycles | LOW — inspect at next opportunity, order replacement |
+| 5,000+ cycles | CRITICAL — replace before next session |
+
+Lock types to track separately: 4-digit combination, directional, word/letter, key lock, magnetic release.
+
+### Electronics (Electronics & Tech)
+
+Electronics degrade in different ways — track:
+- **Battery-powered items**: flag if battery replacement is overdue (typically every 30–60 days depending on usage)
+- **Firmware-dependent items** (smart locks, UV panels, custom electronics): flag if firmware update is available or last update was > 6 months ago
+- **UV lights**: track bulb hours; commercial UV bulbs degrade at approximately 1,000 hours
+
+| Electronics Item | Maintenance Trigger |
+|---|---|
+| UV flashlights | Battery check weekly; replacement after [N] sessions |
+| UV bulbs (fixed) | Bulb hours > 800 — inspect; > 1,000 — replace |
+| Digital locks | Firmware check quarterly |
+| Audio systems | Test before each session; no routine replacement cycle |
+| Custom Arduino / Raspberry Pi props | Log any error reports; replace failing components immediately |
+
+### Costumes (Costumes & Accessories)
+
+Track laundering count. Most costumes can be professionally laundered 50–100 times before fabric degradation becomes noticeable. Flag if:
+- Total laundering count is unknown (no tracking = no assurance of hygiene)
+- Any item shows visible staining, tears, or odor reports from previous session
+
+### Retail (Retail & Merchandise)
+
+Retail items (branded merchandise, souvenir items, gift cards in physical form) don't deplete through room use. Track stock levels separately and flag if any SKU falls below reorder threshold. Retail COGS tracking is separate from operational inventory.
+
+### Maintenance Supplies
+
+Track consumables used in room reset and maintenance:
+- Replacement lock hasps and shackles
+- UV-reactive ink and UV pens (single-use puzzle elements)
+- Breakaway seals and tamper-evident stickers
+- Batteries (AA, AAA, 9V) — stock at least 2 weeks of buffer
+- Cleaning supplies specific to prop materials
+
+---
+
+## Alert Tiers
+
+| Tier | Condition | Symbol |
+|---|---|---|
+| CRITICAL | Item non-functional, lock at 5,000+ cycles, or critical prop missing from room | 🔴 CRITICAL |
+| LOW | Item degrading but functional, lock at 4,500–4,999 cycles, electronics overdue for service | 🟡 LOW |
+| OK | All items within normal operating parameters | 🟢 OK |
+
+---
+
+## Report Structure
+
+---
+
+### Inventory Health — {{locationName}}
+**Report date**: [today's date]
+**Next 7 days**: [N] confirmed sessions across [N] rooms
+
+---
+
+### 1. Status Summary
+
+| Status | Items |
+|---|---|
+| 🔴 CRITICAL | [N] items |
+| 🟡 LOW | [N] items |
+| 🟢 OK | [N] items |
+
+---
+
+### 2. Critical Items — Action Required Before Next Session
+
+| Item | Room | Category | Issue | Action |
+|---|---|---|---|---|
+| [name] | [room name] | [category] | [description of issue] | Replace / Remove from room immediately |
+
+If no critical items: "No critical items. All props and locks are within operational parameters."
+
+---
+
+### 3. Low Priority — Address This Week
+
+| Item | Room | Category | Issue | Est. Days Until Critical |
+|---|---|---|---|---|
+| [name] | [room name] | [category] | [description] | [N] days |
+
+---
+
+### 4. Room-by-Room Status
+
+For each active room, produce a status block:
+
+```
+[Room Name]
+  Props:       [N OK | N LOW | N CRITICAL]
+  Locks:       [status — cycle counts for each lock if available]
+  Electronics: [status — battery/firmware check dates]
+  Overall:     [🟢 Ready | 🟡 Minor issues — action this week | 🔴 Not ready for session]
+```
+
+Flag any room with a CRITICAL item as **Not ready for session** until the item is resolved.
+
+---
+
+### 5. Lock Cycle Tracker
+
+| Lock ID / Name | Room | Type | Est. Cycles | Status | Action |
+|---|---|---|---|---|---|
+| [lock name] | [room] | [4-digit / directional / word / key / magnetic] | [N] | [OK / LOW / CRITICAL] | [None / Order replacement / Replace now] |
+
+---
+
+### 6. Recommended Replacement / Order List
+
+Consolidate all items requiring action into a single purchasing list:
+
+| Item | Category | Room | Priority | Suggested Qty | Notes |
+|---|---|---|---|---|---|
+| [item] | [category] | [room] | [CRITICAL / LOW] | [N] | [e.g., "Replace directional lock — 4,800 cycles, order spare before it hits 5,000"] |
+
+---
+
+### 7. Maintenance Notes
+
+Add contextual notes warranted by the data:
+- If a room has no condition flags on any props: note it briefly to affirm the room is in good shape
+- If a recently introduced prop or mechanism has logged condition issues quickly: flag for design review — it may not be durable enough for session volume
+- If any room is approaching a scheduled full reset / redecoration: note props that can be retired rather than replaced
+- If batteries are low across multiple rooms simultaneously: suggest a bulk battery restock rather than room-by-room replacement

package/kits/escape-vault/skills/leaderboard-report/SKILL.md

@@ -0,0 +1,204 @@
+---
+id: leaderboard-report
+name: Leaderboard Report
+description: Generates leaderboard reports showing all-time and monthly fastest escape times per room using raw and hint-adjusted times, room completion rates, team size performance analysis, trend detection for room difficulty drift, and new record alerts.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: true
+---
+
+# Leaderboard Report
+
+You generate leaderboard reports for **{{locationName}}** — the fastest escape times, completion rates by room, team size performance analysis, and trend detection. This is a guest-facing analytics product as much as an operations tool: the leaderboard creates community, drives repeat bookings, and gives guests a tangible reason to improve.
+
+## When to Trigger
+
+Invoke this skill when staff or owners ask:
+- "Show me the leaderboard"
+- "Top escape times"
+- "Room stats"
+- "Who's the fastest team?"
+- "How are completion rates?"
+- "Performance review for [room]"
+- Any question about escape times, records, or room performance metrics
+
+## Data Sources
+
+Session attributes on completed bookings:
+- `completionTime` — string in `MM:SS` format
+- `hintsUsed` — integer
+- `escaped` — string outcome (`"Yes! Escaped"` | `"Almost — X seconds remaining"` | `"Not this time"`)
+- `roomName` — which room
+- `teamName` — team display name
+- `guestCount` (from booking `metadata.guestCount`) — team size
+
+**Preprocessing required** (client-side):
+- Convert `completionTime` from `MM:SS` to seconds: `minutes × 60 + seconds`
+- Infer `escaped = true` when `escaped = "Yes! Escaped"`, `false` otherwise
+- Calculate adjusted time: `adjustedTimeSeconds = completionTimeSeconds + (hintsUsed × 30)`
+
+Only include bookings with `escaped = true` in time-based rankings. Include all completed bookings (escaped or not) in completion rate calculations.
+
+---
+
+## Aggregates to Define
+
+### Completion time statistics by room
+
+```typescript
+brain.defineAggregate('completionTimeByRoom', {
+  source: {
+    type: 'Event',
+    where: [
+      { field: 'metadata.entityType', value: 'booking' },
+      { field: 'metadata.status',     value: 'completed' }
+    ]
+  },
+  groupBy: [
+    { field: 'metadata.experienceSlug' }
+  ],
+  metrics: {
+    totalAttempts:     { op: 'COUNT' },
+    avgGuests:         { op: 'AVG', field: 'metadata.guestCount' }
+  }
+  // Note: completionTime and escaped are in data.sessionAttributes — query
+  // individual bookings and compute completion rate + time stats client-side
+});
+```
+
+**Client-side calculations** (load individual completed bookings and compute):
+- Filter to `escaped = true`, parse completion times, sort ascending for rankings
+- Completion rate per room: (escaped count) / (total attempts) × 100
+- AVG, MIN, MAX, STDDEV of completion time in seconds for escaped sessions
+- Adjusted time per session: `completionTimeSeconds + (hintsUsed × 30)`
+
+### Team size analysis
+
+Group escaped sessions by `guestCount`. For each team size, compute:
+- Average completion time (raw and adjusted)
+- Completion rate (escaped / total attempts at that size)
+- Session count
+
+---
+
+## Report Structure
+
+---
+
+### Leaderboard Report — {{locationName}}
+**Generated**: [today's date]
+**Data coverage**: [first booking date] – [today] ([N] total sessions across all rooms)
+
+---
+
+### 1. All-Time Records per Room
+
+For each room, show the fastest escape:
+
+| Room | Fastest Raw Time | Adjusted Time | Team Name | Team Size | Date | Hints Used |
+|---|---|---|---|---|---|---|
+| [room] | [MM:SS] | [MM:SS] | [team name] | [N] | [date] | [N] |
+
+Display both raw time and adjusted time. A team that escaped in 43:00 with 0 hints ranks above a team that escaped in 41:00 with 5 hints when sorted by adjusted time (41:00 + 2:30 = 43:30 adjusted vs. 43:00 raw).
+
+**Format**: Times as `MM:SS` for readability. Hints penalty: `N hints × 0:30`.
+
+---
+
+### 2. Current Month Top 10 (All Rooms Combined)
+
+Rank by **adjusted time** — across all rooms and all team sizes:
+
+| # | Team Name | Room | Raw Time | Hints | Adjusted Time | Team Size | Date |
+|---|---|---|---|---|---|---|---|
+| 1 | [team] | [room] | [MM:SS] | [N] | [MM:SS] | [N] | [date] |
+
+Cap at 10. Include room name because different rooms have different difficulty — context matters for interpreting rankings across rooms.
+
+**Month header**: "Top 10 Fastest Escapes — [Month Year]"
+
+---
+
+### 3. Room Completion Rates
+
+| Room | Total Attempts | Escaped | Completion Rate | Avg Time (Escaped) | Avg Hints Used |
+|---|---|---|---|---|---|
+| Standard Room | [N] | [N] | [%] | [MM:SS] | [avg hints] |
+| Advanced Room | [N] | [N] | [%] | [MM:SS] | [avg hints] |
+| Family Room | [N] | [N] | [%] | [MM:SS] | [avg hints] |
+| Private Booking | [N] | [N] | [%] | [MM:SS] | [avg hints] |
+| Corporate Team Build | [N] | [N] | [%] | [MM:SS] | [avg hints] |
+
+**Target ranges** (from escape-expertise knowledge):
+- Family Room: 70–80% target
+- Standard Room: 50–60% target
+- Advanced Room: 35–40% target
+
+Flag rooms outside their target range:
+- `⚠️ [Room] completion rate is [X]% — [above/below] the [target]% target. [If above: room may need additional difficulty. If below: identify the highest hint-request puzzle and consider simplifying the input.`
+
+---
+
+### 4. Team Size Sweet Spot
+
+For each common team size, show performance across all rooms:
+
+| Team Size | Sessions | Completion Rate | Avg Adjusted Time | Best Room for This Size |
+|---|---|---|---|---|
+| 2 guests | [N] | [%] | [MM:SS] | [room with highest completion rate at this size] |
+| 3–4 guests | [N] | [%] | [MM:SS] | [room] |
+| 5–6 guests | [N] | [%] | [MM:SS] | [room] |
+| 7–8 guests | [N] | [%] | [MM:SS] | [room] |
+
+**Data-driven booking recommendation**: Based on the performance data, which team size performs best in each room? This recommendation can inform the booking guidance on the website and in front-desk conversations.
+
+Example recommendation: "Teams of 4–5 have the highest completion rate in the Standard Room at 64%. Teams of 2 struggle most with the Advanced Room (28% completion). Recommend groups of 2 start with Standard Room."
+
+---
+
+### 5. Month-over-Month Completion Rate Trends
+
+Compare this month's completion rate to last month's for each room:
+
+| Room | This Month Rate | Last Month Rate | Change | Interpretation |
+|---|---|---|---|---|
+| [room] | [%] | [%] | [+/- pp] | [Rising / Stable / Declining] |
+
+**Drift detection**: A consistent month-over-month increase in completion rate for a room may indicate that the puzzle solutions are becoming known — either through players sharing online or return guests who've done the room before. Flag if any room shows a 3+ month consecutive increase in completion rate above the target ceiling:
+
+`⚠️ [Room] completion rate has risen [X] percentage points over [N] consecutive months. Consider refreshing 1–2 puzzles to reestablish difficulty baseline.`
+
+A consistent decline may indicate a puzzle is too hard or a prop/mechanism issue is frustrating teams unfairly. Investigate the most-hinted puzzle for that room.
+
+---
+
+### 6. Record Alert
+
+Check if any record was set or tied in the past 7 days:
+
+```
+🏆 NEW RECORD — [Room Name]
+   Team: [Team Name] ([N] guests)
+   Date: [date]
+   Raw time: [MM:SS] | Adjusted time: [MM:SS] ([N] hints used)
+   Previous record: [MM:SS] (adjusted) by [previous team] on [date]
+   Margin: [N] seconds faster
+```
+
+If no new records this week: "No new records set in the past 7 days. Current records remain as listed in Section 1."
+
+**Staff action**: When a new record is set, congratulate the team personally at checkout and invite them to share on social media (tagging {{instagram}} if applicable). This is a free, high-authenticity marketing moment.
+
+---
+
+## Data Quality Notes
+
+Session attribute data (`completionTime`, `hintsUsed`, `escaped`) is entered manually by Game Masters at the end of each session. Before generating this report:
+
+- Flag any completed bookings where `escaped = "Yes! Escaped"` but `completionTime` is missing — these cannot be ranked
+- Flag any `completionTime` values that fall outside the room's duration (e.g., a time of "72:15" logged for a 60-minute Standard Room indicates a data entry error)
+- If `hintsUsed` is null for an escaped session, treat as 0 hints for ranking purposes but note the data gap
+
+Data quality issues should be flagged at the top of the report before the rankings:
+`⚠️ [N] completed sessions are missing completion time data and cannot be ranked. Ask Game Masters to log session attributes immediately after each session.`