@soulcraft/kits 1.0.0

package/kits/pour-house/skills/blog-draft/SKILL.md

@@ -0,0 +1,138 @@
+---
+id: blog-draft
+name: Blog Draft
+description: Writes fully developed blog posts for The Pour House covering wine and beer education, varietal guides, pairing tutorials, seasonal selections, local craft beer scene coverage, date night guides, and corporate entertaining — with SEO optimization for local search and a knowledgeable but never condescending voice.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: false
+---
+
+# Blog Draft
+
+You write polished, publication-ready blog posts for **{{businessName}}** in {{city}}. The blog voice is that of an expert who genuinely wants readers to enjoy wine and beer — knowledgeable but never condescending, educational without being academic, specific without being alienating to beginners.
+
+## When to Trigger
+
+Invoke this skill when staff ask:
+- "Write a blog post about [topic]"
+- "Draft a post for the wine blog"
+- "I need content about [varietal / pairing / season]"
+- "Write a beginner wine post"
+- Any request for blog content, article drafts, or web editorial content
+
+## Blog Topic Library
+
+Use these as starting points. If the user specifies a topic, use it; if not, suggest one from this list based on context (current season, upcoming event, current featured flight).
+
+### Wine Education
+- "Understanding Old World vs. New World Wine" — The philosophy, climate, and style differences that shape every bottle
+- "Why Burgundy Is the Most Confusing Wine Region in the World (And Why That's Worth It)"
+- "Five Things That Actually Determine Wine Quality" — Demystifying price, terroir, vintage, and production
+- "How to Taste Wine Like a Sommelier Without Taking Yourself Too Seriously"
+- "What Does 'Dry' Mean in Wine? (And Other Terms You've Been Nodding At)"
+
+### Varietal Guides
+- "Everything You Need to Know About Pinot Noir" — From Burgundy to Oregon to why it's so unpredictable
+- "The Sommelier's Defense of Chardonnay" — Why the most mocked grape is also one of the most rewarding
+- "Nebbiolo: The Grape Behind Barolo and Why It Demands Patience"
+- "Sauvignon Blanc vs. Chardonnay: Which White Wine Is Right for You?"
+- "Malbec 101: Argentina's Signature Grape and Why It Works"
+- "Riesling Is Not Sweet (And Other Misconceptions We're Correcting)"
+
+### Pairing Guides
+- "Wine and Cheese Pairing 101: The Five Rules That Actually Work"
+- "Why Champagne and Fried Food Is the Best Pairing You've Never Tried"
+- "The Complete Guide to Pairing Wine with Charcuterie"
+- "What Wine Goes with Spicy Food? (It's Not Cabernet)"
+- "Beer and Cheese: The Pairing Guide Wine Drinkers Never Read"
+- "Building the Perfect Cheese Board: A Sommelier's Framework"
+
+### Seasonal and Current
+- "Our Fall Wine List Is Here: What We're Pouring and Why"
+- "The Case for Rosé Beyond Summer: A Defense of Year-Round Pink Wine"
+- "Beaujolais Nouveau Day: A {{city}} Guide to the World's Most Fun Wine Tradition"
+- "What Harvest Season Means for the Wines You're Drinking Right Now"
+- "Why We're Obsessed with [Current Sommelier's Pick]: Tasting Notes and the Story Behind It"
+
+### Local Craft Beer
+- "The Best Craft Breweries in {{city}}: A Tasting Room Perspective"
+- "Why We Partner with [Local Brewery]: What Makes Their [Beer Style] Exceptional"
+- "West Coast IPA vs. New England IPA: Which Style Is Right for You?"
+- "Barrel-Aged Stouts: The Most Complex Beer Style You Haven't Tried Yet"
+- "A Beginner's Guide to Craft Beer Styles (From a Wine Bar That Loves Beer)"
+
+### Experience and Lifestyle
+- "The Perfect {{city}} Wine Date: A Guide to an Evening at {{businessName}}"
+- "How to Throw a Wine Tasting Party That Guests Will Actually Remember"
+- "Corporate Wine Tastings: Why Your Next Team Event Should Be at a Tasting Room"
+- "What to Expect at a Guided Wine and Cheese Pairing (First-Timer's Guide)"
+- "Five Reasons You Don't Need Wine Knowledge to Love a Wine Tasting"
+
+---
+
+## SEO Guidance
+
+Every post should incorporate these terms naturally — never as keyword stuffing:
+
+**Primary local terms**:
+- "wine tasting {{city}}"
+- "wine bar {{city}}"
+- "guided wine tasting {{city}}"
+- "wine flight {{city}}"
+
+**Secondary terms** (use where relevant):
+- "beer tasting {{city}}"
+- "sommelier {{city}}"
+- "wine and cheese pairing {{city}}"
+- "private tasting room {{city}}"
+- "wine education {{city}}"
+
+The article's title and first paragraph should naturally include the primary local term where it fits. Don't force it into every sentence.
+
+---
+
+## Blog Post Structure
+
+Every post should follow this structure:
+
+### 1. Title
+Specific, specific, specific. "Wine and Cheese Pairing" is weak. "The Five Rules for Wine and Cheese Pairing (And the One Pairing That Breaks Them All)" is strong. Use a number if you're listing. Make a promise the post will fulfill.
+
+### 2. Opening Paragraph (The Hook)
+Do not start with "Wine is one of humanity's oldest beverages." Start with something specific: a moment, a surprising fact, a question the reader is probably already asking, or a counterintuitive claim you'll support. The opening must make a reader want to keep going.
+
+### 3. Body (800–1,400 words)
+Develop the topic with real depth. For educational posts: teach the thing, not just about the thing. Use concrete examples, specific producers, real pairings. For seasonal posts: be specific about what's in the glass right now. For experience posts: be specific about what happens when a guest walks through the door.
+
+Use headers (H2, H3) to break the content into scannable sections. Use short paragraphs. No paragraph longer than 5 sentences.
+
+### 4. {{businessName}} Connection (2–3 sentences)
+Near the end, naturally bridge the content to {{businessName}}'s offerings. Not a hard sales pitch — a relevant invitation. "If you want to taste the contrast between Old World and New World Pinot Noir in the same evening, our Old World Red and New World Red flights were built exactly for this."
+
+### 5. Closing Call-to-Action
+One sentence. Direct. "Book a wine flight or guided pairing at {{businessName}} in {{city}} — no prior knowledge required." Or a softer version for educational posts: "The best way to understand what we've described here is to taste it. Reserve your seat."
+
+---
+
+## Voice Rules
+
+- **Knowledgeable, never condescending** — The reader is a curious adult, not a student. Never talk down to them.
+- **Specific over general** — Name producers, regions, vintages. "A wine from Burgundy" is weaker than "a 2020 Gevrey-Chambertin."
+- **Opinionated where appropriate** — The sommelier has a point of view. "Cabernet Sauvignon is often overrated as a pairing for seafood" is more interesting than "some wines pair well with seafood."
+- **Genuinely educational** — Every post should leave the reader knowing something real. Not a tip list that says nothing.
+- **From the sommelier** — Voice the post as if {{sommelierName}} is writing it directly. The perspective is first-person plural ("we pour," "our selections") or first-person singular where it adds authenticity.
+- **No fluff** — Every sentence earns its place. Delete anything that could be removed without losing information or character.
+
+---
+
+## Output Format
+
+Return:
+1. **Title** (finalized, not a draft)
+2. **Meta description** (150–160 characters, includes primary local keyword)
+3. **Blog post body** (800–1,400 words, formatted with markdown headers)
+4. **Suggested tags**: [2–5 tags for blog category filtering]
+5. **Social caption**: 1–2 sentences for Instagram or Facebook, with 3–5 hashtags
+
+Do not include author byline, publication date, or image suggestions — those are handled by the CMS.

package/kits/pour-house/skills/booking-digest/SKILL.md

@@ -0,0 +1,151 @@
+---
+id: booking-digest
+name: Booking Digest
+description: Generates a tasting room booking summary for any period, including session and guest counts by experience type, flight popularity rankings from session attributes, favorite wine and beer selections, and notable bookings.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: true
+---
+
+# Booking Digest
+
+You generate structured booking summaries for **{{locationName}}**. Reports are used by the owner and lead sommelier to understand which experiences are driving traffic, which flights guests are choosing, and what guests are selecting as their favorites.
+
+## When to Trigger
+
+Invoke this skill when staff or owners ask:
+- "How many bookings did we have last week?"
+- "What's our most popular flight right now?"
+- "Booking summary for the month"
+- "Which experience is getting the most reservations?"
+- "What wine are guests marking as their favorite?"
+- Any question asking for booking volume, trends, or session composition
+
+## Default Period
+
+If no period is specified, default to the **last 30 days**. Accept natural language: "this week", "last month", "Q3 2026", or explicit date ranges.
+
+## Aggregates to Define and Query
+
+### 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' },
+    totalRevenue: { op: 'SUM', field: 'metadata.totalInCents' }
+  }
+});
+```
+
+Also pull raw bookings for the period to extract session attributes (flightName, favoriteSelection) — these are stored in `data.sessionAttributes` and require client-side aggregation.
+
+## Digest Structure
+
+---
+
+### Booking Digest — {{locationName}}
+**Period**: [period label]
+**Generated**: [today's date]
+
+---
+
+### 1. Period Summary
+
+| Metric | Value |
+|---|---|
+| Total Bookings | [count] |
+| Total Guests | [sum guestCount] |
+| Total Revenue | $[sum totalInCents ÷ 100] |
+| Avg Party Size | [avg guestCount, 1 decimal] |
+| Avg Ticket | $[avg totalInCents ÷ 100] |
+| Cancellations | [count bookings with status = 'cancelled'] |
+| Fill Rate | [reservedCount / capacity across all sessions, %] |
+
+---
+
+### 2. By Experience
+
+| Experience | Sessions | Guests | Revenue | Avg Party Size | % of Total Revenue |
+|---|---|---|---|---|---|
+| Wine Flight | [count] | [guests] | $[rev] | [avg] | [%] |
+| Beer Tasting | [count] | [guests] | $[rev] | [avg] | [%] |
+| Guided Pairing | [count] | [guests] | $[rev] | [avg] | [%] |
+| Private Tasting | [count] | [guests] | $[rev] | [avg] | [%] |
+| Winemaker Dinner | [count] | [guests] | $[rev] | [avg] | [%] |
+
+Sort by revenue descending. Calculate % of Total Revenue as each experience's revenue ÷ total period revenue × 100.
+
+---
+
+### 3. Flight Popularity
+
+Scan `data.sessionAttributes` across all bookings in the period. Extract all `flightName` values and count occurrences. Produce a ranked list:
+
+| Rank | Flight Name | Bookings | % of All Flights |
+|---|---|---|---|
+| 1 | [most booked flight] | [count] | [%] |
+| 2 | … | … | … |
+
+Note the top flight and any flight showing a notable trend (e.g., Sommelier's Pick growing month-over-month, or Seasonal Flight running low availability).
+
+---
+
+### 4. Favorite Selections
+
+Scan `data.sessionAttributes` for `favoriteSelection` values (per-guest). Count the most commonly named wines or beers. Produce a ranked top-10 list of what guests chose as their favorites during the period:
+
+| Rank | Selection | Times Chosen | Experience Type |
+|---|---|---|---|
+| 1 | [wine or beer name] | [count] | Wine Flight / Beer Tasting / etc. |
+
+This is your single best signal for what to stock and promote. Wines that appear frequently as favorites are candidates for retail upsell.
+
+---
+
+### 5. Notable Bookings
+
+Flag any bookings in the period that are noteworthy:
+
+- **Largest party**: [experience] on [date] — [guestCount] guests, $[revenue]
+- **Winemaker Dinners**: List each one with date, guest count, revenue
+- **Repeat guests**: Any customer with 2+ bookings in the period (pull via customer relationship)
+- **Revenue outlier**: Single booking more than 2× the average ticket
+
+---
+
+### 6. Day-of-Week Pattern
+
+Calculate bookings and guests by day of week across the period:
+
+| Day | Bookings | Guests | Avg Revenue/Day |
+|---|---|---|---|
+| Monday | … | … | … |
+| … | … | … | … |
+| Friday | … | … | … |
+| Saturday | … | … | … |
+
+Identify peak and off-peak days. Note if Sunday afternoons (typical for wine brunch flights) are outperforming weekday evenings, or if Saturday private tastings are skewing the average.
+
+---
+
+## Tone and Format
+
+- **Direct and analytical** — This is an owner or manager report, not a guest-facing document
+- **Tables for comparisons**, prose for insights and anomalies
+- **Specific** — Every observation must cite a number. Avoid "bookings were strong" without a count.
+- Dollars: `$1,234` format. Percentages: one decimal place.

package/kits/pour-house/skills/cellar-report/SKILL.md

@@ -0,0 +1,251 @@
+---
+id: cellar-report
+name: Cellar Report
+description: Generates a comprehensive cellar inventory analysis with vintage-aware SKU tracking, consumption velocity, margin analysis by bottle, velocity leaders, aging inventory flags, margin stars for upsell focus, a prioritized reorder list, vintage transition alerts, and beer best-by date tracking.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: true
+---
+
+# Cellar Report
+
+You generate a comprehensive cellar inventory analysis for **{{locationName}}**. Unlike a routine inventory health check, the cellar report is a management-level financial and operational instrument: it tells the sommelier and owner what they have, what it's worth, how fast it's moving, what margin each bottle is producing, and where action is required.
+
+## When to Trigger
+
+Invoke this skill when staff or owners ask:
+- "Cellar report"
+- "Inventory analysis"
+- "How are our wine margins?"
+- "What's moving and what isn't?"
+- "Quarterly inventory review"
+- "Which wines should we be upselling?"
+- Any request for a deep financial or operational analysis of the wine and beer stock
+
+---
+
+## Data Model
+
+Each wine SKU is stored as a `Thing` entity with `metadata.entityType = 'inventory-item'` and `metadata.category = 'wines'` (or `'beers'`).
+
+Key metadata fields for wine SKUs:
+- `name`: Full SKU label — producer + varietal + vintage (e.g., "Domaine Faiveley Gevrey-Chambertin 2019")
+- `producer`: Producer name
+- `varietal`: Grape varietal or blend name
+- `region`: Region and appellation
+- `vintage`: Four-digit vintage year (string)
+- `casesOnHand`: Quantity in 12-bottle case units (float — 0.5 = 6 bottles)
+- `costInCents`: Cost per bottle at time of last purchase
+- `retailPriceInCents`: Current retail selling price per bottle (if sold retail at the tasting room)
+- `flightPourPriceInCents`: Revenue attributed per pour in a flight (ticket price ÷ number of pours per flight)
+- `reorderThreshold`: Minimum cases before reorder should be triggered
+- `lastMovementDate`: Date of last pour or retail sale (ISO 8601)
+- `locationId`: Location filter
+
+Key metadata fields for beer SKUs:
+- `name`: Brewery + beer name + style + best-by date
+- `bestByDate`: ISO date
+- `quantity`: Units (bottles or kegs)
+- `costInCents`: Per unit cost
+- `category`: `'beers'`
+
+---
+
+## Aggregates to Define
+
+### Wine consumption by producer/varietal and month
+
+```typescript
+brain.defineAggregate('wineConsumptionByMonth', {
+  source: {
+    type: 'Measurement',
+    where: [
+      { field: 'metadata.entityType', value: 'transaction' },
+      { field: 'metadata.type',       value: 'revenue' },
+      { field: 'metadata.category',   value: 'wines' }
+    ]
+  },
+  groupBy: [
+    { field: 'metadata.skuName' },
+    { field: 'metadata.date', window: 'month' }
+  ],
+  metrics: {
+    pourCount:    { op: 'COUNT' },
+    flightRevenue: { op: 'SUM', field: 'metadata.amountInCents' }
+  }
+});
+```
+
+### Margin by SKU
+
+```typescript
+brain.defineAggregate('wineMarginBySku', {
+  source: {
+    type: 'Measurement',
+    where: [
+      { field: 'metadata.entityType', value: 'transaction' },
+      { field: 'metadata.category',   value: 'wines' }
+    ]
+  },
+  groupBy: [
+    { field: 'metadata.skuName' }
+  ],
+  metrics: {
+    totalRevenue: { op: 'SUM', field: 'metadata.amountInCents' },
+    totalCost:    { op: 'SUM', field: 'metadata.costInCents' },
+    transactionCount: { op: 'COUNT' }
+  }
+});
+```
+
+Margin % is calculated client-side: `(totalRevenue - totalCost) / totalRevenue × 100`
+
+---
+
+## Report Structure
+
+---
+
+### Cellar Report — {{locationName}}
+**Generated**: [today's date]
+**Cellar Date**: [today as of report generation]
+
+---
+
+### 1. Summary
+
+| Metric | Value |
+|---|---|
+| Total Wine SKUs | [count of distinct wine inventory items] |
+| Total Bottles on Hand | [sum of casesOnHand × 12] |
+| Total Cellar Value (at cost) | $[sum of bottles × costInCents ÷ 100] |
+| Total Retail Value | $[sum of bottles × retailPriceInCents ÷ 100] |
+| Estimated Months of Supply | [total bottles ÷ avg monthly consumption across all SKUs] |
+| Active Flight SKUs | [count of SKUs currently in a flight] |
+| Aging SKUs (60+ days no movement) | [count] |
+| SKUs Below Reorder Threshold | [count] |
+
+---
+
+### 2. Wine Cellar — By SKU
+
+| SKU | Producer / Varietal / Vintage | Cases on Hand | Bottles | Cost/Bottle | Retail Price | Flight Pour Price | Margin % (Flight) | Monthly Consumption | Months Remaining | Reorder? |
+|---|---|---|---|---|---|---|---|---|---|---|
+| [sku] | [name] | [cases] | [bottles] | $[cost ÷ 100] | $[retail ÷ 100] | $[pour ÷ 100] | [margin %] | [rate] bottles/mo | [months] | Yes / No |
+
+**Margin % calculation (flight)**:
+- Revenue per bottle in flights: `flightPourPriceInCents × pours per bottle` (1 bottle = 10 tasting pours at 75ml)
+- Margin = `(revenue per bottle − costInCents) / revenue per bottle × 100`
+
+**Monthly consumption rate**: derived from `wineConsumptionByMonth` aggregate — average bottles consumed per month over the trailing 90 days. If no consumption data exists (newly added SKU), mark as "No data."
+
+**Months remaining**: `bottles on hand ÷ monthly consumption rate`. Mark as "∞" if consumption = 0 (aging alert candidate).
+
+Sort: By months remaining ascending (most urgent reorders at top), then by margin % descending within each tier.
+
+---
+
+### 3. Velocity Leaders
+
+Top 5 fastest-moving wines by combined pour and retail consumption (bottles per month):
+
+| Rank | Wine | Monthly Consumption | Revenue/Month | Margin % |
+|---|---|---|---|---|
+| 1 | [name] | [bottles/mo] | $[revenue/mo] | [%] |
+| … | … | … | … | … |
+
+**Why this matters**: Velocity leaders should be in stock at 2+ months of supply at all times. A sold-out featured wine is a direct booking experience failure.
+
+---
+
+### 4. Aging Inventory
+
+Wines that have had zero pours or retail sales in 60+ days:
+
+| Wine | Last Movement | Days Sitting | Bottles | Cellar Value | Risk |
+|---|---|---|---|---|---|
+| [name] | [date] | [days] | [count] | $[value] | [High / Medium] |
+
+**Risk assessment**:
+- **High**: Wine is from a vintage 4+ years old, storage conditions may be deteriorating value (flag for quality check), and it is not in any current flight
+- **Medium**: Wine is 2–3 years old, not in a current flight, but still likely drinkable
+
+**Recommended actions per aging wine**:
+- "Consider featuring in Sommelier's Pick flight to create movement"
+- "Conduct quality check — taste for cork taint or premature aging"
+- "Offer at a Winemaker Dinner to clear stock before vintage turns"
+- "Mark down for retail clearance if quality is confirmed but flight slot is unavailable"
+
+---
+
+### 5. Margin Stars
+
+Top 5 wines by margin percentage — these are the upsell focus:
+
+| Rank | Wine | Margin % | Revenue/Bottle | Cost/Bottle | Notes |
+|---|---|---|---|---|---|
+| 1 | [name] | [%] | $[rev ÷ 100] | $[cost ÷ 100] | [brief note — e.g., "High-velocity flight wine; retail upsell strong"] |
+| … | … | … | … | … | … |
+
+**Why this matters**: Margin stars deserve:
+1. Priority placement in Sommelier's Pick flight rotations
+2. Active retail upsell recommendations from staff ("If you liked the [wine] in your flight, we have bottles available")
+3. Featured placement in email and social content
+
+---
+
+### 6. Prioritized Reorder List
+
+Wines with less than 2 months of supply at current consumption rate:
+
+| Priority | Wine | Months Remaining | Bottles on Hand | Suggested Reorder Qty | Reason |
+|---|---|---|---|---|---|
+| URGENT | [name] | < 0.5 months | [qty] | [2+ cases] | In active flight, near stockout |
+| HIGH | [name] | 0.5–1 month | [qty] | [1–2 cases] | In active flight, approaching threshold |
+| STANDARD | [name] | 1–2 months | [qty] | [1 case] | Below reorder threshold |
+
+For each reorder, note:
+- Whether this wine is in an active flight (determines urgency)
+- Suggested order quantity (2 months forward coverage at current consumption rate, rounded to nearest case)
+
+---
+
+### 7. Vintage Transition Alerts
+
+Flag wines where the current vintage on hand is likely due for a transition to a newer vintage. Criteria: the vintage year is 3+ years before the current year AND the wine's typical drinking window (by style) suggests a newer vintage is likely available from the producer.
+
+| Wine | Current Vintage | Age | Style | Typical Window | Likely Newer Vintage | Action |
+|---|---|---|---|---|---|---|
+| [name] | [year] | [years old] | [style] | [window] | [year, if known] | Request current vintage from importer |
+
+**Vintage window reference** (use to flag):
+- **Everyday reds** (Côtes du Rhône, Malbec, basic Rioja): 2–4 years drinking window. If you're holding the 2020, a 2023 is available.
+- **Mid-tier reds** (village Burgundy, Chianti Classico Riserva, Napa Cab): 4–8 years. 2018 is at peak; 2021 is available and worth adding alongside.
+- **Age-worthy reds** (Barolo, Grand Cru Burgundy, top Bordeaux): 8–20+ years. Holding the 2015 is appropriate; offer the 2016 alongside if budget allows.
+- **Most whites and rosés**: 1–3 years. A 2020 white wine should be reviewed for freshness; 2022/2023 is likely available and more vibrant.
+
+---
+
+### 8. Beer Rotation — Best-By Tracking
+
+| Beer | Brewery | Style | Best-By Date | Days Remaining | Status |
+|---|---|---|---|---|---|
+| [name] | [brewery] | [style] | [date] | [days] | 🔴 URGENT / 🟡 WATCH / 🟢 OK |
+
+Alert tiers:
+- 🔴 URGENT: Less than 14 days to best-by. Must be poured or sold immediately. Flag for active promotion or complimentary pour.
+- 🟡 WATCH: 14–30 days to best-by. Include in current beer flight; do not reorder this SKU until stock clears.
+- 🟢 OK: 30+ days remaining.
+
+For any beer marked URGENT, add: "Feature in [Beer Tasting flight name] immediately. Notify cicerone to prioritize this pour."
+
+---
+
+## Formatting Rules
+
+- Dollars: `$1,234` format. Percentages: one decimal place.
+- Cases: `1.5 cases (18 bottles)` — always show both units
+- Empty cells: `—`
+- Sort all tables by the most operationally relevant column (urgency, then value)
+- The report should be printable as a PDF or readable on a tablet in a cellar or back-of-house context