@soulcraft/kits 1.0.0

package/kits/axe-house/skills/staff-briefing/SKILL.md

@@ -0,0 +1,231 @@
+---
+id: staff-briefing
+name: Staff Operations Briefing
+description: Generates a structured shift briefing for the opening or afternoon team covering today's lane schedule, waiver status, equipment and maintenance alerts, beverage inventory flags, and tonight's league status if applicable.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: true
+---
+
+# Staff Operations Briefing
+
+You generate the daily shift briefing for {{businessName}} staff. When triggered, pull live data from Brainy and produce a structured, scannable briefing that gives the opening or afternoon team everything they need before the first session begins.
+
+## When to Trigger
+
+Invoke this skill when staff ask:
+
+- "What's on today?"
+- "Give me the morning briefing"
+- "Daily briefing"
+- "What do we have this shift?"
+- "How many bookings today?"
+- Any shift check-in request at shift start
+
+## Data to Pull
+
+Run these queries before generating the briefing. All queries must filter by `metadata.locationId`.
+
+### 1. Today's Bookings by Session Type
+
+```typescript
+brain.defineAggregate('todayBookingsByExperience', {
+  source: {
+    type: 'Event',
+    where: [
+      { field: 'metadata.entityType', value: 'booking'   },
+      { field: 'metadata.date',       value: TODAY        },
+      { field: 'metadata.status',     value: 'confirmed'  }
+    ]
+  },
+  groupBy: [{ field: 'metadata.experienceSlug' }],
+  metrics: {
+    bookingCount: { op: 'COUNT' },
+    totalGuests:  { op: 'SUM', field: 'metadata.guestCount'   },
+    totalRevenue: { op: 'SUM', field: 'metadata.totalInCents' }
+  }
+});
+
+const byExperience = await brain.find({
+  aggregate: 'todayBookingsByExperience',
+  where: [{ field: 'metadata.locationId', value: LOCATION_ID }]
+});
+```
+
+### 2. Time-Slot Schedule (Lane by Lane)
+
+```typescript
+const slots = await brain.find({
+  type: 'Event',
+  where: [
+    { field: 'metadata.entityType', value: 'time-slot'  },
+    { field: 'metadata.date',       value: TODAY         },
+    { field: 'metadata.locationId', value: LOCATION_ID  }
+  ],
+  orderBy: 'metadata.hour',
+  order:   'asc'
+});
+// Each slot: { hour, experienceSlug, capacity, reservedCount }
+```
+
+Also pull the full booking list for today to show waivers:
+
+```typescript
+const todayBookings = await brain.find({
+  type: 'Event',
+  where: [
+    { field: 'metadata.entityType', value: 'booking'    },
+    { field: 'metadata.date',       value: TODAY         },
+    { field: 'metadata.status',     value: 'confirmed'   },
+    { field: 'metadata.locationId', value: LOCATION_ID  }
+  ],
+  orderBy: 'metadata.hour',
+  order:   'asc'
+});
+// Check .data.waiversSigned for each booking
+```
+
+### 3. Inventory Alerts (Safety & Equipment Priority)
+
+```typescript
+const inventoryItems = await brain.find({
+  type: 'Thing',
+  where: [
+    { field: 'metadata.entityType', value: 'inventory-item' },
+    { field: 'metadata.locationId', value: LOCATION_ID      }
+  ]
+});
+// Filter client-side: items.filter(i => i.metadata.quantity < i.metadata.reorderThreshold)
+// CRITICAL: flag safety and hatchet/big-axe category items first
+```
+
+## Briefing Structure
+
+Output the briefing in this exact order. Use markdown formatting so it renders cleanly in the assistant UI.
+
+---
+
+### 1. Greeting
+
+```
+Welcome to {{locationName}}!
+[Day of week], [Full date]
+Coach on duty: [staff name if available from schedule data]
+```
+
+### 2. Today's Sessions
+
+Present every time slot in chronological order. For each block:
+
+- **Time** (e.g., 4:00 PM)
+- **Session type** (Open Throw, League Night, Private Party, Corporate Event, Axe 101 Lesson)
+- **Lanes assigned** (laneNumber from session attributes if already set, otherwise "TBD")
+- **Guests** (reservedCount / capacity — show percentage)
+- **Party name** (for private parties and corporate events — pull from booking data or session attributes)
+- **Waiver status** — flag any bookings where not all guests have signed
+
+Flag slots at 100% capacity as **SOLD OUT**. Flag slots at 80%+ as **NEARLY FULL**.
+
+Example:
+```
+4:00 PM — Open Throw Session
+  Lane 3 · 4/6 guests (67%)
+  Booking AX-0219-A · All waivers signed ✓
+
+6:00 PM — Private Party
+  Lanes 1–3 · 12/12 guests (SOLD OUT)
+  Party: "Rodriguez Bachelorette" · ⚠️ 3 waivers not yet signed
+  Competition format: tournament
+
+8:00 PM — League Night
+  Lanes 4–8 · Week 3 of Season 2 · 8 teams registered
+```
+
+### 3. Equipment Check
+
+Pull from inventory items with category `hatchet` or `big-axe`:
+
+- List any axes currently flagged in maintenance notes (check `metadata.maintenanceStatus` if available)
+- Show count of available hatchets and big axes
+- If any axes are past their sharpening threshold (based on session count in item notes), flag them
+
+```
+Equipment Status:
+  Hatchets: 14 available (2 flagged for sharpening — remove before first session)
+  Big Axes: 6 available (all OK)
+
+⚠️  Maintenance Queue: Hatchet #7 and #12 — due for edge sharpening based on session count.
+    Pull from rotation before opening.
+```
+
+If all equipment is clear: "All axes inspected and in rotation. No maintenance flags."
+
+### 4. Target Board Status
+
+Check inventory items in category `targets` for rotation notes:
+
+- Flag any boards approaching the flip threshold
+- If a board was recently noted for replacement, surface it here
+
+If no flags: "All target boards are in good condition."
+
+### 5. Bar & Beverage Status
+
+Pull inventory items with category `beverages`:
+
+```typescript
+const beverages = inventoryItems.filter(i => i.metadata.category === 'beverages');
+const low = beverages.filter(i => i.metadata.quantity < i.metadata.reorderThreshold);
+```
+
+If low items exist: show a table (item | in stock | reorder point | status).
+If all OK: "Bar inventory is fully stocked."
+
+### 6. League Night Note
+
+If today is a league night (check if any time-slot has `experienceSlug === 'league-night'`):
+
+```
+Tonight: League Night — Season [N], Week [N]
+  Teams scheduled: [team names from booking session attributes]
+  Standings reminder: See league-manager skill for current standings
+  Action: Set up scoreboard on all league lanes before 7:00 PM
+```
+
+### 7. Opening Action Items
+
+Always end with this checklist. Check inventory and waiver status to add conditional items:
+
+```
+Pre-Shift Checklist
+[ ] Inspect all hatchets and big axes — remove any flagged for maintenance
+[ ] Confirm target boards are set and boards not flagged for rotation
+[ ] Waiver station powered on — tablet charged, link tested, backup paper forms available
+[ ] POS confirmed — opening float counted, card reader online
+[ ] Lane scoreboard systems powered up and tested
+[ ] Bar stocked and opening prep complete
+[ ] House rules posted visibly at each lane
+[ ] Parking and entrance signage in place
+```
+
+If waivers are missing for today's bookings, add:
+```
+[ ] ⚠️  [N] guests have not signed waivers — text reminder link before session start
+```
+
+If axes are flagged for maintenance, add:
+```
+[ ] ⚠️  Pull Hatchet #7 and #12 from rotation — sharpen before returning to floor
+```
+
+If any beverage items are low, add:
+```
+[ ] ⚠️  Reorder [item] — below par level
+```
+
+## Tone
+
+Direct, practical, and confident. The briefing should read like it was written by a senior coach who has already done the hard work of pulling the data and just needs to hand it off. No fluff. Staff should be able to scan it in 60 seconds and know exactly what needs attention.
+
+Use tables and bullet points. Keep prose to a minimum. If everything is clear, say so in one line — don't pad.

package/kits/axe-house/skills/venue-data-model/SKILL.md

@@ -0,0 +1,225 @@
+---
+id: venue-data-model
+name: Venue Data Model
+description: Background skill teaching the AI assistant the complete Venue platform data architecture — entity types, relationships, and the full Brainy API including aggregates, neural clustering, streaming, and counts.
+type: background
+version: 1.0.0
+requiresVision: false
+requiresData: false
+---
+
+# Venue Data Model
+
+You are operating on the Venue platform, built on **@soulcraft/brainy** — a graph database with vector search, neural clustering, and aggregate query capabilities. This skill gives you a complete map of every entity type, relationship, and API call available to you when answering data-driven questions for {{businessName}}.
+
+## Entity Types
+
+Every entity has a `type` (NounType) and a `metadata.entityType` string that further classifies it within that type. Always filter by both when querying.
+
+| NounType | `metadata.entityType` | Purpose | Key Metadata Fields |
+|---|---|---|---|
+| Location | `location` | Franchise location record | `address`, `hours`, `timezone`, `stripeAccountId`, `locationId` |
+| Product | `experience` | Bookable experience / ticket type | `slug`, `name`, `priceInCents`, `durationMinutes`, `minGuests`, `maxGuests`, `locationId` |
+| Event | `booking` | Guest reservation | `status` (pending/confirmed/completed/cancelled), `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 action log | `action`, `actorId`, `actorName`, `entityId`, `entityType`, `locationId` |
+| Person | `customer` | Guest profile | `email`, `displayName`, `totalBookings`, `totalSpentInCents`, `loyaltyTier`, `locationId` |
+| Person | `staff` | Employee record | `email`, `role`, `permissions`, `locationId` |
+| Person | `loyalty-account` | Points balance and tier | `customerId`, `pointsBalance`, `tier` (bronze/silver/gold/platinum), `locationId` |
+| Document | `waiver` | Signed digital waiver | `bookingId`, `signerName`, `signedAt`, `locationId` |
+| Document | `content-page` | CMS-managed website section | `pageSlug`, `section`, `locationId` |
+| Document | `blog-post` | Blog article | `slug`, `title`, `status` (draft/published), `tags`, `authorId`, `locationId` |
+| Thing | `inventory-item` | Stock item with quantity tracking | `name`, `category`, `quantity`, `reorderThreshold`, `costInCents`, `locationId` |
+| Thing | `gift-card` | Digital or physical gift card | `code`, `balanceInCents`, `originalAmountInCents`, `redeemedAt`, `locationId` |
+| Measurement | `transaction` | Revenue, expense, or refund record | `type` (revenue/expense/refund), `amountInCents`, `experienceSlug`, `category`, `date`, `stripeId`, `locationId` |
+| Measurement | `loyalty-transaction` | Points earned, redeemed, or expired | `customerId`, `points`, `reason` (earned/redeemed/expired), `locationId` |
+
+## Relationships
+
+Graph edges connect entities using typed verbs. Use relationships to traverse the graph without duplicating data.
+
+| Relationship | Meaning |
+|---|---|
+| Location **Contains** Experience, TimeSlot, InventoryItem | What exists at a given location |
+| Booking **ParticipatesIn** TimeSlot | Which slot a reservation occupies |
+| Customer **Creates** Booking, Waiver | Ownership of guest-initiated records |
+| Booking **Contains** Experience | Line items on a reservation |
+| Transaction **References** Booking | Revenue record linked back to a booking |
+| Staff **MemberOf** Location | Employee location assignment |
+| LoyaltyAccount **BelongsTo** Customer | One loyalty account per customer |
+
+## Brainy Aggregate API
+
+Aggregates are the primary tool for financial summaries, trend analysis, and operational reporting. Define them once, then query them with filters.
+
+### Defining and Running an Aggregate
+
+```typescript
+// Step 1: Define a named aggregate (do this once at startup or on demand)
+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' }
+  }
+});
+
+// Step 2: Execute with runtime filters, ordering, and limits
+const results = await brain.find({
+  aggregate: 'revenueByExperienceMonth',
+  where: [{ field: 'metadata.locationId', value: 'loc-abc123' }],
+  orderBy: 'totalRevenue',
+  order:   'desc',
+  limit:   100
+});
+// Returns: Array<{ groupKey: string, metrics: Record<string, number>, count: number }>
+```
+
+### Supported Aggregation Operations
+
+| `op` value | Meaning |
+|---|---|
+| `SUM` | Sum all values in the group |
+| `COUNT` | Count records in the group |
+| `AVG` | Arithmetic mean of values |
+| `MIN` | Minimum value in the group |
+| `MAX` | Maximum value in the group |
+| `STDDEV` | Population standard deviation |
+| `VARIANCE` | Population variance |
+
+### Supported Time Windows (for `groupBy` with `window`)
+
+`hour` | `day` | `week` | `month` | `quarter` | `year`
+
+---
+
+## Counts API
+
+O(1) fast counts without loading entities into memory. Use for dashboards and health checks.
+
+```typescript
+// Count by NounType — always O(1)
+const totals = await brain.counts.byType();
+// → { Event: 820, Person: 340, Measurement: 1240, Thing: 180, Document: 95, Location: 2 }
+
+// Count with filter criteria
+const todayBookings = await brain.counts.byCriteria({
+  type: 'Event',
+  criteria: [
+    { field: 'metadata.entityType', value: 'booking'    },
+    { field: 'metadata.date',       value: '2026-02-19' },
+    { field: 'metadata.status',     value: 'confirmed'  }
+  ]
+});
+// → { total: 18 }
+
+// Full graph statistics
+const stats = await brain.getStats();
+// → { entities: 2675, relationships: 4800, density: 0.38, byType: { ... } }
+```
+
+---
+
+## Neural API
+
+Machine-learning operations on the graph. Use for segmentation, anomaly detection, and similarity search.
+
+```typescript
+// Cluster customers into behavioral segments
+const segments = await brain.neural().clusters({
+  numClusters: 5,
+  entityType:  'Person',
+  where: [{ field: 'metadata.entityType', value: 'customer' }]
+});
+// → Array<{ label: string, members: Entity[], centroid: number[] }>
+
+// Detect anomalous entities (outliers and VIPs)
+const outliers = await brain.neural().outliers({
+  threshold:    2.5,          // z-score cutoff — higher = fewer results
+  method:       'zscore',     // 'zscore' | 'iqr' | 'isolation'
+  entityType:   'Measurement',
+  minNeighbors: 3
+});
+// → Array<{ entity: Entity, reason: string, score: number }>
+
+// Find semantically similar entities via vector embedding
+const similar = await brain.neural().similar('entity-id-123', { limit: 10 });
+// → Array<{ entity: Entity, similarity: number }>
+```
+
+---
+
+## Streaming API
+
+Process large result sets without loading everything into memory. Use for bulk exports, batch jobs, and anything where result count may exceed a few thousand.
+
+```typescript
+// Stream entities by type with optional filter
+for await (const booking of brain.streaming.entities({
+  type:  'Event',
+  where: [{ field: 'metadata.entityType', value: 'booking' }]
+})) {
+  // process one booking at a time — no memory accumulation
+}
+
+// Stream vector search results
+for await (const result of brain.streaming.search('private party axe throwing corporate', {
+  type:  'Event',
+  limit: 200
+})) {
+  // result.entity, result.score
+}
+```
+
+---
+
+## Export API
+
+Generate tabular exports from any entity type for spreadsheets, finance tools, or OData consumers.
+
+```typescript
+import { TabularExporter } from '@soulcraft/brainy';
+
+const exporter = new TabularExporter(brain);
+
+// CSV export
+const { data, rowCount } = await exporter.exportCsv({ type: 'Measurement' });
+
+// OData export (for Power BI, Excel, etc.)
+const odata = await exporter.exportOData({ type: 'Measurement' });
+```
+
+---
+
+## Critical Rules
+
+These rules govern every query you run on this platform. Violating them produces wrong or corrupt data.
+
+1. **All monetary amounts are stored as integers in cents.** Always divide by 100 for display. `$25.00 = 2500`. Never store or compute floats.
+
+2. **Always filter by `metadata.locationId`** when producing per-location reports. The database is shared across all franchise locations.
+
+3. **Always include `metadata.entityType`** when querying Event, Person, Document, Thing, or Measurement types. Without it, you will mix bookings with time-slots and transactions with loyalty records.
+
+4. **Audit events are append-only.** Never update or delete a record with `metadata.entityType === 'audit-event'`.
+
+5. **Stripe is the source of truth for payments.** `metadata.stripeId` links to Stripe; Brainy stores reference IDs only. Do not compute refunds or charges from Brainy data alone.
+
+6. **Do not write files directly to `brainy-data/`.** All mutations must go through the Brainy API (`brain.add()`, `brain.update()`, `brain.relate()`). Direct filesystem writes bypass indexes and cause corruption.
+
+7. **Session attributes for axe throwing bookings** are stored in `booking.data.sessionAttributes` as an array of per-guest or per-session objects. Key fields include `laneNumber`, `throwStyle` (hatchet/big-axe), `bestScore`, `teamName`, `leagueSeason`, `competitionFormat`, and `coachNotes`. Always check session attribute scope (per-guest vs per-session) when aggregating.