@soulcraft/kits 1.0.0

package/kits/pour-house/skills/tasting-notes/SKILL.md

@@ -0,0 +1,179 @@
+---
+id: tasting-notes
+name: Tasting Note Generator
+description: Generates elegant, complete tasting note cards for each wine or beer in a flight, formatted for printing or digital display at 3×5 landscape table cards. Covers appearance, aroma (primary/secondary/tertiary categories), palate structure, food pairings, serving temperature, glassware, and a one-line memorable hook per wine.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: true
+---
+
+# Tasting Note Generator
+
+You generate complete, print-ready tasting note cards for each wine or beer in a flight at **{{businessName}}**. Tasting notes are placed at guest seats before each session and serve as guided reference cards during the tasting. They should be authoritative without being intimidating, and specific enough to give guests real vocabulary for what they're tasting.
+
+## When to Trigger
+
+Invoke this skill when staff ask:
+- "Generate tasting notes for tonight's flight"
+- "Tasting cards for the Old World Red flight"
+- "Write notes for the Guided Pairing wines"
+- "Tasting note cards before the Winemaker Dinner"
+- "Notes for the beer flight"
+- Any request for tasting cards, printed notes, or pre-session wine/beer descriptions
+
+---
+
+## Input Format
+
+You will receive a flight description with wine or beer details:
+
+```json
+{
+  "flightName": "Old World Red Flight",
+  "experienceSlug": "wine-flight",
+  "locationName": "The Pour House Midtown",
+  "date": "2026-10-15",
+  "wines": [
+    {
+      "position": 1,
+      "producer": "Château Léoville-Barton",
+      "varietal": "Cabernet Sauvignon / Merlot / Cabernet Franc",
+      "region": "Saint-Julien, Bordeaux",
+      "vintage": "2018",
+      "abv": "13.5%",
+      "staffDescription": "Classic Left Bank Bordeaux, structured but approachable for a 2018. Cassis, cedar, some tobacco."
+    },
+    {
+      "position": 2,
+      "producer": "Domaine Faiveley",
+      "varietal": "Pinot Noir",
+      "region": "Gevrey-Chambertin, Burgundy",
+      "vintage": "2019",
+      "abv": "13.0%",
+      "staffDescription": "Village-level Gevrey. Cherry, forest floor, silky tannin. Great intro to the Côte de Nuits."
+    },
+    {
+      "position": 3,
+      "producer": "Château Rayas",
+      "varietal": "Grenache",
+      "region": "Châteauneuf-du-Pape, Southern Rhône",
+      "vintage": "2017",
+      "abv": "14.5%",
+      "staffDescription": "Legendary estate. Old-vine Grenache — wild herbs, garrigue, ripe cherry, terrific length."
+    },
+    {
+      "position": 4,
+      "producer": "Mastroberardino",
+      "varietal": "Aglianico",
+      "region": "Taurasi, Campania, Italy",
+      "vintage": "2016",
+      "abv": "14.0%",
+      "staffDescription": "The Barolo of the South. Tar, dark cherry, iron, massive structure. Needs food."
+    }
+  ]
+}
+```
+
+For beer flights, the input will use `style`, `brewery`, `abv`, and `ibu` instead of `varietal`, `vintage`.
+
+---
+
+## Tasting Note Format (Per Wine)
+
+Generate each note in this exact structure. This is the layout for a 3" × 5" landscape table card:
+
+---
+
+**[Position number]. [Producer] — [Varietal] — [Region] — [Vintage]**
+ABV: [abv]%
+
+**Appearance**
+[Color and clarity description. Use precise color language: pale straw, medium lemon, deep ruby, opaque purple, translucent brick-red, etc. Note clarity: clear, slightly hazy, or note if sediment is expected in an aged wine.]
+
+**On the Nose**
+[3–5 aromatic descriptors drawn from primary, secondary, and tertiary categories as appropriate. Write as a natural sentence, not a bullet list.]
+
+Example: "On the nose: cassis and dark cherry (primary fruit), giving way to cedar and cigar box (oak aging), with a faint pencil shaving lift that signals the wine's structure."
+
+**On the Palate**
+[Body description + tannin or carbonation character + acidity + dominant flavor + finish length and character. Write as 2–3 connected sentences.]
+
+Example: "Full-bodied with firm, well-integrated tannins and fresh acid that keeps the wine from feeling heavy. Blackcurrant and plum dominate the mid-palate with a hint of graphite on the finish. Long — flavors linger for 20+ seconds."
+
+**Pairs With**
+[2–3 specific food pairings. Be concrete. Not "red meat" — "grilled ribeye, lamb shoulder braised with rosemary, or aged manchego."]
+
+**Serve At**
+[Temperature in °F and °C] in a [glass type] glass. [Decant if relevant: "Decant 30 minutes before serving to soften young tannins." or "Ready to pour from the bottle."]
+
+**The Hook**
+[One memorable sentence that captures this wine's personality without being purple prose. The hook is a gift to guests — something to repeat when describing the wine to someone else.]
+
+Examples of good hooks:
+- "The wine that makes Bordeaux skeptics reconsider." (for an approachable, elegant Bordeaux)
+- "If Burgundy is the quiet one at dinner, Gevrey-Chambertin is the one who has everything to say and takes their time saying it."
+- "Châteauneuf at its most wild — a wine that smells like a Provençal hillside in August."
+- "Taurasi earns its nickname: the Barolo of the South, which means patience is the price of admission."
+
+**Avoid**: "liquid sunshine," "a symphony in a glass," "a perfect marriage of fruit and earth," "notes of oak" (oak is not a primary note — name the tertiary descriptor specifically: vanilla, cedar, toast, coconut), "complex" without explaining the complexity.
+
+---
+
+## Beer Tasting Note Format (Per Beer)
+
+For beer flights, use this adapted structure:
+
+---
+
+**[Position]. [Brewery] — [Beer Name] — [Style]**
+ABV: [abv]% | IBU: [ibu]
+
+**Appearance**
+[Color (pale straw, golden, amber, brown, black, hazy), clarity (clear, hazy, opaque), head (white, off-white, tan; persistent, moderate, minimal).]
+
+**On the Nose**
+[Aroma descriptors using cicerone vocabulary: grain, hops (herbal, citrus, tropical, pine, resinous), esters (fruit from yeast), phenols (spice, clove from Belgian yeasts). 3–4 descriptors.]
+
+**On the Palate**
+[Bitterness (low/medium/high, relative to style), carbonation (gentle/moderate/high), body (light/medium/full), dominant flavors, finish (dry/sweet, length).]
+
+**Pairs With**
+[2–3 specific food pairings appropriate to the style.]
+
+**Serve At**
+[Temperature] in a [glass type] glass.
+
+**The Hook**
+[One memorable line that captures the beer's character.]
+
+---
+
+## Flight Card Format
+
+When producing notes for a complete flight, output all notes in sequence with consistent formatting. The complete set of notes for a flight should be presented as:
+
+---
+
+**[flightName] — {{locationName}}**
+*[Date] | [experienceName]*
+
+---
+[Note 1 through Note N in sequence]
+
+---
+
+At the bottom of the flight card set, add:
+
+**About This Flight**
+[2–3 sentences describing what makes this particular sequence meaningful — why these wines or beers were chosen together, what story they tell in order, what contrast or theme runs through the flight. This is what the sommelier will say when introducing the flight to the table.]
+
+---
+
+## Tone Rules
+
+- **Authoritative but accessible** — Write for a curious adult who is tasting attentively, not for a Masters of Wine exam
+- **Vivid, concrete descriptors** — "Ripe black cherry and cassis" is specific; "fruity" is not
+- **No filler adjectives**: "elegant," "sophisticated," "extraordinary" add nothing. Describe what's actually there.
+- **Consistent vocabulary** — Use the same structural terms (body, tannin, acidity, finish) across all notes so guests can compare wines using the same framework
+- **The hook must be memorable** — If a guest quotes the hook to a friend later, it worked. If it sounds like every other wine description they've ever read, it failed.

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

@@ -0,0 +1,323 @@
+---
+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 tasting room location | `address`, `hours`, `timezone`, `stripeAccountId`, `locationId` |
+| `Product` | `experience` | Experience 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` | Beverage, glassware, or food stock | `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`
+
+---
+
+## 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 / supply 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 experience and day
+
+```typescript
+brain.defineAggregate('bookingsByExperienceDay', {
+  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: 880, Person: 630, ... }
+
+// 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: 8 }
+
+// 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('burgundy pinot noir', { 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('old world red burgundy pinot noir', {
+  type: 'Event',
+  limit: 20
+});
+```
+
+---
+
+## Rules Summary
+
+1. **Amounts in cents** — `5500` = $55.00. Always divide by 100 before displaying.
+2. **Always filter `metadata.locationId`** when the user's question is about a specific tasting room 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. **Never write files directly to brainy-data/** — all data mutations go through `brain.add()`, `brain.update()`, `brain.relate()`.