@soulcraft/kits 1.0.0

package/kits/wicks-and-whiskers/skills/staff-briefing/SKILL.md

@@ -0,0 +1,174 @@
+---
+id: staff-briefing
+name: Morning Staff Briefing
+description: Generates a structured morning operations briefing for the opening shift, covering today's schedule, revenue forecast, inventory alerts, kitten lounge status, and an opening checklist.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: true
+---
+
+# Morning Staff Briefing
+
+You generate the daily opening briefing for {{businessName}} staff. When triggered, pull live data from Brainy and produce a structured, scannable briefing that gives the opening team everything they need to start a confident shift.
+
+## 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?"
+- Any morning 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
+
+```typescript
+brain.defineAggregate('todayBookingsByExperience', {
+  source: {
+    type: 'Event',
+    where: [
+      { field: 'metadata.entityType', value: 'booking' },
+      { field: 'metadata.date',       value: TODAY      },  // ISO date string
+      { 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
+
+```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 has: hour, experienceSlug, capacity, reservedCount
+```
+
+### 3. Inventory Alerts
+
+```typescript
+const inventoryItems = await brain.find({
+  type: 'Thing',
+  where: [
+    { field: 'metadata.entityType', value: 'inventory-item' },
+    { field: 'metadata.locationId', value: LOCATION_ID      }
+  ]
+});
+// Client-side filter: items.filter(i => i.metadata.quantity < i.metadata.reorderThreshold)
+```
+
+### 4. Active Kittens
+
+```typescript
+const kittens = await brain.find({
+  type: 'Organism',
+  where: [
+    { field: 'metadata.entityType',    value: 'kitten'   },
+    { field: 'metadata.adoptionStatus', value: 'active'  },
+    { field: 'metadata.locationId',    value: LOCATION_ID }
+  ]
+});
+```
+
+## Briefing Structure
+
+Output the briefing in this exact order. Use markdown formatting so it renders cleanly in the assistant UI.
+
+---
+
+### 1. Greeting
+
+```
+Good morning, {{locationName}}! 🌅
+[Day of week], [Full date]
+```
+
+### 2. Today's Schedule
+
+Present every time slot in chronological order. For each slot:
+
+- **Time** (e.g., 10:00 AM)
+- **Experience** (full name, e.g., Kitten & Kandle Combo)
+- **Guests** (reservedCount / capacity — show capacity percentage)
+- **Booking numbers** (prefix list, e.g., WW-2402-A, WW-2402-B)
+
+Flag slots at 100% capacity as **SOLD OUT**. Flag slots at 80%+ as **NEARLY FULL**.
+
+### 3. Revenue Forecast
+
+- Today's confirmed revenue total (sum of `totalInCents` / 100, formatted as currency)
+- Total guest count across all bookings
+- If yesterday's data is available: show percentage change vs yesterday (e.g., "+12% vs yesterday")
+
+### 4. Inventory Alerts
+
+If any items have `quantity < reorderThreshold`:
+
+| Item | Category | In Stock | Reorder Point | Status |
+|---|---|---|---|---|
+| 464 Soy Wax | wax | 8 lbs | 20 lbs | ORDER NOW |
+
+If no items need attention: "All supplies are well-stocked. No action needed."
+
+### 5. Kitten Lounge
+
+- Count of active kittens in the lounge today
+- List each kitten by name with one personality trait (from `personalities` array)
+- If any kitten has a note about being shy or needing extra care, flag it
+
+Example:
+```
+🐱 5 kittens on the floor today:
+  • Mochi (playful) | Butter (cuddly) | Sage (curious) | Pixel (shy — give guests a heads-up) | Toast (bold)
+```
+
+### 6. Opening Action Items
+
+Always end with this checklist, customized based on inventory alert status:
+
+```
+Opening Checklist
+[ ] Litter boxes checked and freshened
+[ ] Fragrance oil display fully stocked and organized
+[ ] Waiver station powered on — iPad charged, link tested
+[ ] POS float confirmed ($200 starting cash)
+[ ] Opening social post scheduled (or drafted for posting)
+[ ] Kitten water bowls refreshed
+[ ] Candle bar surfaces wiped, pour stations set
+[ ] Window sign flipped to OPEN
+```
+
+If any fragrance items were flagged in the inventory alert, add:
+```
+[ ] ⚠️ Low fragrance oils — pull backup stock from storage before first session
+```
+
+## Tone
+
+Warm, practical, and energizing. Like a great shift manager who has already done the hard work of pulling the numbers and just needs to hand them off. Never corporate. Never cold. The opening team should feel prepared and excited, not overwhelmed.
+
+Avoid long paragraphs. Use tables and bullet points so the briefing can be scanned in 60 seconds.

package/kits/wicks-and-whiskers/skills/venue-data-model/SKILL.md

@@ -0,0 +1,228 @@
+---
+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` |
+| Event | `experience-memory` | Shareable visit storybook page | `bookingId`, `token` (public URL slug), `published`, `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` |
+| Document | `adoption-application` | Animal adoption form | `kittenId`, `applicantEmail`, `status`, `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` |
+| Organism | `kitten` | Foster animal profile | `name`, `age`, `breed`, `personalities`, `adoptionStatus`, `locationId` |
+
+## Relationships
+
+Graph edges connect entities using typed verbs. Use relationships to traverse the graph without duplicating data.
+
+| Relationship | Meaning |
+|---|---|
+| Location **Contains** Experience, TimeSlot, Kitten, InventoryItem | What exists at a given location |
+| Booking **ParticipatesIn** TimeSlot | Which slot a reservation occupies |
+| Customer **Creates** Booking, Waiver, AdoptionApplication | Ownership of guest-initiated records |
+| Booking **Contains** Experience | Line items on a reservation |
+| Transaction **References** Booking | Revenue record linked back to a booking |
+| Memory **References** Booking | Visit storybook linked to a booking |
+| Staff **MemberOf** Location | Employee location assignment |
+| AdoptionApplication **References** Kitten | Which kitten an application is for |
+| 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: 450, Person: 210, Measurement: 890, Thing: 340, Document: 120, Organism: 28, Location: 3 }
+
+// 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: 14 }
+
+// Full graph statistics
+const stats = await brain.getStats();
+// → { entities: 1540, relationships: 3200, density: 0.42, 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('romantic date night candle', {
+  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. `$55.00 = 5500`. 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, customers with staff, 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.