@soulcraft/kits 1.0.0

package/kits/escape-vault/skills/staff-briefing/SKILL.md

@@ -0,0 +1,159 @@
+---
+id: staff-briefing
+name: Staff Shift Briefing
+description: Generates a structured operations briefing for the opening Game Master shift at the escape room venue, covering today's sessions by room, team sizes, reset schedule between sessions, maintenance alerts, and a pre-shift action checklist.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: true
+---
+
+# Staff Shift Briefing
+
+You generate a clear, organized shift operations briefing for the opening Game Master team at **{{locationName}}**. Think shift-manager energy: calm, thorough, and ready to run a tight schedule.
+
+## When to Trigger
+
+Invoke this skill when staff ask:
+- "What's the briefing for today?"
+- "What sessions are running today?"
+- "Good morning — what do I need to know?"
+- "Daily briefing" / "shift check-in" / "morning briefing"
+- Any question about today's schedule at the start of a shift
+
+## Data to Pull
+
+Before generating the briefing, gather:
+
+1. **Today's bookings** — Query `Event` entities with `metadata.entityType = 'booking'` and `metadata.date = [today's date]` and `metadata.locationId = [location]`. Group by time slot and experienceSlug.
+2. **Time slots** — Query `Event` entities with `metadata.entityType = 'time-slot'` for today to get capacity and `reservedCount` per session.
+3. **Session attributes** — For each booking, check `data.sessionAttributes` for `roomName`, `teamName`, `companyName`, and any special notes.
+4. **Revenue comparison** — Query the `Measurement` aggregate for the same weekday last week (same day-of-week, one week prior) to produce a comparison figure.
+5. **Inventory alerts** — Query `Thing` entities with `metadata.entityType = 'inventory-item'` and `metadata.locationId = [location]`. Flag any where `metadata.quantity <= metadata.reorderThreshold`.
+
+## Briefing Structure
+
+Generate the briefing in exactly this structure:
+
+---
+
+### Good morning, {{locationName}}!
+
+> **[Full date — e.g., Wednesday, February 19, 2026]**
+> **GM on duty**: [from staff assignment if available, otherwise "Check schedule"]
+
+---
+
+### 1. Today's Sessions
+
+For each room in use today, produce a block ordered by time:
+
+```
+🔐 [Time] — [Room Name] ([Experience Type])
+   Team: [teamName from session attributes, or "Walk-in / TBD"]
+   Party size: [guestCount] guests
+   Type: [Standard | Advanced | Family | Private | Corporate]
+   Booking: [bookingNumber]
+   Notes: [companyName if corporate | ageRange if family | any booking notes]
+```
+
+If multiple sessions are in the same room back-to-back, flag the reset window:
+```
+   ⏱ Reset window: [duration between session end and next session start]
+   [OK — 15+ min reset window | ⚠️ TIGHT — under 15 min | 🔴 CRITICAL — under 10 min]
+```
+
+If no sessions are scheduled: "No sessions scheduled today. Good day for room maintenance, prop inventory, and reset procedure review."
+
+---
+
+### 2. Room Reset Schedule
+
+Show the full day's timeline as a reset planning tool:
+
+```
+[Room Name]:
+  [Start time] – [End time]: [Team name / Booking #]
+  [End time] – [Next start]: RESET WINDOW ([N] min) [OK/⚠️ TIGHT/🔴 CRITICAL]
+  [Next start] – [Next end]: [Next team]
+```
+
+Flag any room with two or more consecutive back-to-back sessions — these are the highest reset pressure points of the day.
+
+---
+
+### 3. Revenue Forecast
+
+```
+Confirmed revenue today:   $[sum of totalInCents for confirmed bookings ÷ 100]
+Last [weekday] revenue:    $[comparison figure ÷ 100]
+Variance:                  [+/- $X and percentage]
+```
+
+Note whether today is tracking above, on par, or below last week's same day. Flag any private bookings or corporate groups — these carry higher ticket value and may have specific setup requirements.
+
+---
+
+### 4. Maintenance Check
+
+List any items requiring pre-session verification:
+
+```
+⚠️  [Room Name] — [item or issue flagged]
+    Category: [props | locks | electronics | costumes]
+    Last flagged: [date or "today — from previous session log"]
+    Action needed: [replace / repair / test before next session]
+```
+
+If no maintenance items: "No maintenance flags from previous sessions. Confirm all rooms against the standard pre-session checklist."
+
+---
+
+### 5. Inventory Alerts
+
+If any items are at or below reorder threshold:
+
+```
+⚠️  [Item name] — [quantity] remaining (threshold: [reorderThreshold])
+    Category: [category]
+    Action: Reorder before end of shift
+```
+
+If all inventory is healthy: "All supplies are well-stocked. No reorder alerts."
+
+---
+
+### 6. Pre-Shift Action Checklist
+
+Generate a session-specific checklist. Always include universal items; add session-specific items based on today's data.
+
+**Universal items (every shift):**
+- [ ] Confirm all room resets are complete from last night's final sessions
+- [ ] Test emergency override on all room doors — confirm they open from inside
+- [ ] Verify hint communication system is operational in each active room (intercom / screen / call button)
+- [ ] Confirm camera feeds are live for all rooms scheduled today
+- [ ] Test audio/lighting cue systems in each room
+- [ ] POS terminal confirmed and float counted
+- [ ] Locker keys tagged and accessible at front desk
+- [ ] Briefing script reviewed — especially for any new team member running briefings today
+
+**Session-specific additions (add based on data):**
+- If a Corporate Team Build is scheduled: `[ ] Debrief area set up — whiteboard, seating for [guestCount] guests, printed team summary template`
+- If a Family Room session is scheduled: `[ ] Confirm Family Room difficulty settings are at family mode — check any adjustable puzzle parameters`
+- If a back-to-back tight reset window exists: `[ ] Pre-position reset kit for [Room Name] — fastest reset sequence is [N steps]; confirm second GM available for parallel reset`
+- If inventory alerts exist: `[ ] Initiate reorder for flagged items before end of shift`
+- If any prop is flagged for maintenance: `[ ] Verify [item] is resolved before first session in [Room Name]`
+
+---
+
+## Tone Guidelines
+
+- **Calm and operational** — Like a shift manager who has run a hundred of these days and knows exactly how to set the team up for success
+- **Specific, not generic** — Use actual room names, team names, booking numbers, and guest counts from the data
+- **Actionable** — Every section ends with something the team can verify or do right now
+- **Concise** — The briefing should be scannable in under 2 minutes on a tablet
+- **Safety-first framing** — Emergency system checks always come before revenue and inventory — that ordering matters
+
+## Output Format
+
+Produce the briefing as clean, readable markdown. Headers for each section, emoji sparingly for visual anchoring. The output should render well in both a web staff dashboard and a printed daily sheet.

package/kits/escape-vault/skills/venue-data-model/SKILL.md

@@ -0,0 +1,335 @@
+---
+id: venue-data-model
+name: Venue Data Model
+description: Teaches the AI assistant the complete Venue platform data architecture, Brainy entity types, relationship model, and all available query APIs for building analytics and data-driven responses.
+type: background
+version: 1.0.0
+requiresVision: false
+requiresData: false
+---
+
+# Venue Data Model
+
+You are operating within the **Venue platform**, powered by **@soulcraft/brainy** — a graph-based entity store with vector search, aggregate analytics, neural clustering, and streaming APIs. This document is your complete reference for data architecture and query patterns.
+
+## Core Concepts
+
+Every piece of data is a **Brainy entity** with:
+- A `type` (the NounType — the broad category)
+- A `metadata` object (filterable, indexed fields — queryable via `where`)
+- A `data` object (full-text/vector searchable content)
+- An `id` (UUID string)
+- Relationships to other entities (directed, typed edges)
+
+**Key invariant**: Amounts are always stored in cents (integer). $55.00 = `5500`. Divide by 100 for display.
+
+**Key invariant**: Every entity scoped to a franchise location carries `metadata.locationId`. Always include this filter when querying per-location data.
+
+**Key invariant**: `Event`, `Person`, `Document`, `Measurement`, and `Thing` are the five NounTypes. Sub-entity kinds are distinguished by `metadata.entityType`. Always include the `metadata.entityType` filter when querying a specific sub-kind within a NounType.
+
+---
+
+## Entity Types Reference
+
+| NounType | `metadata.entityType` | Purpose | Key Metadata Fields |
+|---|---|---|---|
+| `Location` | `location` | Franchise venue location | `address`, `hours`, `timezone`, `stripeAccountId`, `locationId` |
+| `Product` | `experience` | Room type / ticket offering | `slug`, `name`, `priceInCents`, `durationMinutes`, `minGuests`, `maxGuests`, `locationId` |
+| `Event` | `booking` | Guest reservation | `status`, `experienceSlug`, `guestCount`, `totalInCents`, `locationId`, `date`, `bookingNumber`, `checkedIn` |
+| `Event` | `time-slot` | Capacity block on the schedule | `date`, `hour`, `experienceSlug`, `capacity`, `reservedCount`, `locationId` |
+| `Event` | `audit-event` | Append-only operation log | `action`, `actorId`, `actorName`, `entityId`, `entityType`, `locationId` |
+| `Event` | `experience-memory` | Shareable post-visit storybook | `bookingId`, `token`, `published`, `locationId` |
+| `Person` | `customer` | Guest profile | `email`, `displayName`, `totalBookings`, `totalSpentInCents`, `loyaltyTier`, `locationId` |
+| `Person` | `staff` | Employee record | `email`, `role`, `permissions`, `locationId` |
+| `Person` | `loyalty-account` | Points and tier balance | `customerId`, `pointsBalance`, `tier`, `locationId` |
+| `Document` | `content-page` | CMS-managed website section | `pageSlug`, `section`, `locationId` |
+| `Document` | `blog-post` | Blog article | `slug`, `title`, `status`, `tags`, `authorId`, `locationId` |
+| `Thing` | `inventory-item` | Physical supply / room prop | `name`, `category`, `quantity`, `reorderThreshold`, `costInCents`, `locationId` |
+| `Thing` | `gift-card` | Digital or physical gift card | `code`, `balanceInCents`, `originalAmountInCents`, `locationId` |
+| `Measurement` | `transaction` | Revenue, expense, or refund record | `type`, `amountInCents`, `experienceSlug`, `category`, `date`, `locationId` |
+| `Measurement` | `loyalty-transaction` | Points earned, redeemed, or expired | `customerId`, `points`, `reason`, `locationId` |
+
+### Booking `status` values
+`pending` | `confirmed` | `completed` | `cancelled`
+
+### Transaction `type` values
+`revenue` | `expense` | `refund`
+
+### Session Attributes (stored in `data.sessionAttributes` on booking entities)
+Escape-specific attributes logged per booking:
+- `roomName` — which room the team was assigned
+- `teamName` — team name chosen by the group
+- `completionTime` — string in `MM:SS` format, filled after session
+- `hintsUsed` — number of hints taken, filled after session
+- `escaped` — outcome: `"Yes! Escaped"` | `"Almost — X seconds remaining"` | `"Not this time"`
+- `companyName` — for corporate bookings
+- `roomsUsed` — for corporate multi-room bookings
+- `ageRange` — for family room bookings
+
+---
+
+## Relationships Reference
+
+Brainy relationships are directed edges with a typed verb. Query via `brain.related()` or use `brain.find()` with relationship traversal.
+
+| From Entity | Verb | To Entity | Purpose |
+|---|---|---|---|
+| `Location` | Contains | `Experience`, `TimeSlot` | What a location offers |
+| `Experience` | OccursAt | `TimeSlot` | Schedule mapping |
+| `Booking` | ParticipatesIn | `TimeSlot` | Seat reservation |
+| `Customer` | Creates | `Booking` | Ownership |
+| `Booking` | Contains | `Experience` | Line items |
+| `Transaction` | References | `Booking` | Revenue attribution |
+| `Experience` | Consumes | `InventoryItem` | COGS / prop tracking |
+| `Location` | Owns | `Transaction` | Multi-location P&L |
+| `Staff` | MemberOf | `Location` | Staff assignment |
+| `Memory` | References | `Booking` | Visit → memory link |
+
+---
+
+## Aggregate API
+
+Use `brain.defineAggregate()` to register a named aggregate, then `brain.find()` with the `aggregate` key to query it. Results are materialized and cached.
+
+### Full example — revenue by experience and month
+
+```typescript
+brain.defineAggregate('revenueByExperienceMonth', {
+  source: {
+    type: 'Measurement',
+    where: [
+      { field: 'metadata.entityType', value: 'transaction' },
+      { field: 'metadata.type', value: 'revenue' }
+    ]
+  },
+  groupBy: [
+    { field: 'metadata.experienceSlug' },
+    { field: 'metadata.date', window: 'month' }
+  ],
+  metrics: {
+    totalRevenue:    { op: 'SUM',      field: 'metadata.amountInCents' },
+    bookingCount:    { op: 'COUNT' },
+    avgTicket:       { op: 'AVG',      field: 'metadata.amountInCents' },
+    maxTicket:       { op: 'MAX',      field: 'metadata.amountInCents' },
+    minTicket:       { op: 'MIN',      field: 'metadata.amountInCents' },
+    revenueStdDev:   { op: 'STDDEV',   field: 'metadata.amountInCents' },
+    revenueVariance: { op: 'VARIANCE', field: 'metadata.amountInCents' }
+  }
+});
+
+const results = await brain.find({
+  aggregate: 'revenueByExperienceMonth',
+  where: [{ field: 'metadata.locationId', value: 'loc-abc' }],
+  orderBy: 'totalRevenue',
+  order: 'desc',
+  limit: 100
+});
+```
+
+### Available aggregation operators
+
+| Operator | Description |
+|---|---|
+| `SUM` | Total of all values in the group |
+| `COUNT` | Number of entities in the group |
+| `AVG` | Arithmetic mean |
+| `MIN` | Minimum value |
+| `MAX` | Maximum value |
+| `STDDEV` | Population standard deviation |
+| `VARIANCE` | Population variance |
+
+### Available time windows for `groupBy`
+
+`hour` | `day` | `week` | `month` | `quarter` | `year`
+
+### Example — expenses by category and month
+
+```typescript
+brain.defineAggregate('expensesByCategory', {
+  source: {
+    type: 'Measurement',
+    where: [
+      { field: 'metadata.entityType', value: 'transaction' },
+      { field: 'metadata.type', value: 'expense' }
+    ]
+  },
+  groupBy: [
+    { field: 'metadata.category' },
+    { field: 'metadata.date', window: 'month' }
+  ],
+  metrics: {
+    totalExpense: { op: 'SUM',   field: 'metadata.amountInCents' },
+    entryCount:   { op: 'COUNT' },
+    avgExpense:   { op: 'AVG',   field: 'metadata.amountInCents' }
+  }
+});
+```
+
+### Example — bookings by room and day of week
+
+```typescript
+brain.defineAggregate('bookingsByRoomDayHour', {
+  source: {
+    type: 'Event',
+    where: [
+      { field: 'metadata.entityType', value: 'booking' },
+      { field: 'metadata.status', value: 'confirmed' }
+    ]
+  },
+  groupBy: [
+    { field: 'metadata.experienceSlug' },
+    { field: 'metadata.date', window: 'day' }
+  ],
+  metrics: {
+    bookingCount: { op: 'COUNT' },
+    totalGuests:  { op: 'SUM', field: 'metadata.guestCount' },
+    avgGuests:    { op: 'AVG', field: 'metadata.guestCount' }
+  }
+});
+```
+
+---
+
+## Counts API
+
+For fast total counts without full aggregation:
+
+```typescript
+// Count all entities by NounType
+const totals = await brain.counts.byType();
+// Returns: { Location: 2, Product: 5, Event: 3840, Person: 1204, ... }
+
+// Count with specific criteria
+const todayBookings = await brain.counts.byCriteria({
+  type: 'Event',
+  criteria: [
+    { field: 'metadata.entityType', value: 'booking' },
+    { field: 'metadata.date',       value: '2026-02-19' }
+  ]
+});
+// Returns: { count: 22 }
+
+// Global database statistics
+const stats = await brain.getStats();
+// Returns: { totalEntities, totalRelationships, indexedAt, storeSizeBytes, ... }
+```
+
+---
+
+## Neural API
+
+Brainy exposes ML-style operations over entity embeddings without an external model:
+
+```typescript
+// Cluster customers into behavioral segments
+const segments = await brain.neural().clusters({
+  numClusters: 5,
+  entityType: 'Person'
+});
+// Returns array of clusters, each with centroid, memberIds[], and summary stats
+
+// Detect statistical outliers (VIPs, anomalies, churn risks)
+const outliers = await brain.neural().outliers({
+  threshold: 2.5,     // Z-score threshold
+  method: 'zscore',   // 'zscore' | 'iqr'
+  entityType: 'Measurement'
+});
+
+// Find semantically similar entities
+const similar = await brain.neural().similar('entity-id-uuid', {
+  limit: 10
+});
+// Returns entities with similarity scores, ordered descending
+```
+
+---
+
+## Streaming API
+
+For large result sets or real-time feeds, use async generators:
+
+```typescript
+// Stream all entities of a NounType
+for await (const entity of brain.streaming.entities({ type: 'Event' })) {
+  // Process one entity at a time — memory-efficient for large sets
+}
+
+// Stream search results
+for await (const result of brain.streaming.search('clockmaker puzzle escape', { type: 'Event' })) {
+  // result.entity, result.score
+}
+```
+
+---
+
+## Tabular Export API
+
+Export entity data as CSV or OData for spreadsheet and BI tool consumption:
+
+```typescript
+import { TabularExporter } from '@soulcraft/brainy';
+
+const exporter = new TabularExporter(brain);
+
+// Export to CSV buffer
+const csv = await exporter.exportCsv({
+  type: 'Measurement',
+  where: [{ field: 'metadata.entityType', value: 'transaction' }]
+});
+
+// Export as OData JSON (compatible with Power BI, Excel)
+const odata = await exporter.exportOData({
+  type: 'Measurement',
+  where: [{ field: 'metadata.entityType', value: 'transaction' }]
+});
+```
+
+---
+
+## Standard Query Patterns
+
+### Find all bookings for a location on a date
+```typescript
+await brain.find({
+  type: 'Event',
+  where: [
+    { field: 'metadata.entityType', value: 'booking' },
+    { field: 'metadata.locationId', value: locationId },
+    { field: 'metadata.date',       value: '2026-02-19' }
+  ],
+  orderBy: 'metadata.hour',
+  order: 'asc'
+});
+```
+
+### Find inventory items below reorder threshold
+```typescript
+await brain.find({
+  type: 'Thing',
+  where: [
+    { field: 'metadata.entityType', value: 'inventory-item' },
+    { field: 'metadata.locationId', value: locationId }
+  ]
+  // Filter client-side: items where quantity <= reorderThreshold
+});
+```
+
+### Full-text + vector search
+```typescript
+await brain.search('clockmaker workshop escape puzzle', {
+  type: 'Event',
+  limit: 20
+});
+```
+
+---
+
+## Rules Summary
+
+1. **Amounts in cents** — `3500` = $35.00. Always divide by 100 before displaying.
+2. **Always filter `metadata.locationId`** when the user's question is about a specific venue location.
+3. **Always include `metadata.entityType`** when querying Event, Person, Document, Thing, or Measurement sub-kinds.
+4. **Use aggregates for analytics** — don't load all entities and sum client-side.
+5. **Use `brain.neural().clusters()`** for customer segmentation, never hard-code segments.
+6. **Session attributes live in `data.sessionAttributes`** — they are not in `metadata` and cannot be used in `where` filters directly. Load the booking entity and inspect `data` client-side.
+7. **Never write files directly to brainy-data/** — all data mutations go through `brain.add()`, `brain.update()`, `brain.relate()`.