@soulcraft/kits 1.0.0

package/kits/canvas-and-corks/skills/guest-letter/SKILL.md

@@ -0,0 +1,127 @@
+---
+id: guest-letter
+name: Guest Thank-You Letter
+description: Writes personalized post-class follow-up emails for paint studio guests, referencing their specific painting, skill level, session details, loyalty points earned, and a warm invitation to return.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: true
+---
+
+# Guest Thank-You Letter
+
+You write the post-class follow-up email that guests receive after their visit to **{{businessName}}**. This is not a mass marketing email — it's a personal note from the studio that references what actually happened in their session. It should feel like it was written by the instructor, not a marketing department.
+
+## When to Trigger
+
+Invoke this skill when:
+- A class has just completed (automated post-checkout trigger)
+- Staff ask: "Send a thank-you to tonight's guests"
+- "Follow up with the people from last Saturday's Date Night"
+- "Write a post-visit email for the [painting name] class"
+
+---
+
+## Input Data Available
+
+You will receive a structured object with session details. Use all available fields — the more specific the letter, the better the guest relationship.
+
+```json
+{
+  "guestNames": ["Alice", "Marcus"],
+  "date": "2026-02-14",
+  "locationName": "Canvas & Corks Midtown",
+  "experienceName": "BYOB Date Night",
+  "sessionAttributes": [
+    { "key": "paintingName", "value": "Moonlit Harbor" },
+    { "key": "medium", "value": "Acrylic" },
+    { "key": "colorPalette", "value": "Cool tones" },
+    { "key": "canvasSize", "value": "16×20" },
+    { "key": "skillLevel", "value": "First timer", "guestName": "Alice" },
+    { "key": "skillLevel", "value": "Beginner", "guestName": "Marcus" }
+  ],
+  "staffNotes": "Alice was nervous to start but completely nailed the reflection on the water. Marcus kept making Alice laugh which made for a beautiful, relaxed painting.",
+  "loyaltyPointsEarned": 45,
+  "currentLoyaltyTier": "Bronze",
+  "pointsToNextTier": 105
+}
+```
+
+---
+
+## Letter Structure
+
+Write a 150–250 word letter in this structure. Every section must reference real data when available — no generic filler.
+
+### 1. Personalized Opener
+Address the guest(s) by first name. If there are multiple guests (e.g., a couple or a group), address them together. Warm, not formal. "Hey Alice and Marcus," or "Hi Alice," — never "Dear Valued Guest."
+
+### 2. Reference Their Painting
+Name the painting specifically. Use one or two sensory or visual details about it — the colors, the subject, the mood. This line must feel like the writer was actually in the room watching them create it.
+
+**Good example:**
+"Moonlit Harbor in cool blues and silver-grey — there's something quietly stunning about a harbor at night, and you both captured it."
+
+**Bad example:**
+"We hope you enjoyed painting with us tonight."
+
+### 3. Acknowledge the Session
+If `staffNotes` is present, incorporate the specific observation naturally — a breakthrough moment, a funny exchange, a technique that clicked. This is the most personalized moment in the letter and the hardest to fake.
+
+If `skillLevel` is "First timer" or "Beginner," acknowledge the specific achievement of completing their first (or early) painting.
+
+**Good example:**
+"Alice — that water reflection you painted in the second half of class? That's not a beginner move. That's just good instincts."
+
+### 4. "Your Painting Is Ready to Hang"
+One short, affirming sentence that marks the painting as a real, finished piece of art — not a class project. This is an important psychological moment for first-timers who may still think their work "doesn't count."
+
+**Good example:**
+"When you get home, give it a day to dry completely, then find it a wall. It deserves one."
+
+### 5. Loyalty Points (if applicable)
+If `loyaltyPointsEarned` is provided, mention it simply — not as a promotional hook, but as a nice-to-know:
+
+"You earned [N] points tonight — your account is now at [total] points. [X] more and you'll hit Silver tier."
+
+If no loyalty data is available, skip this section entirely.
+
+### 6. Return Invitation
+One sentence, genuinely warm — not "book now" language. Point them toward the next class or featured painting if that data is available.
+
+**Good example:**
+"Come back and see what we're painting next month — the March lineup just went up."
+
+### 7. Sign-Off
+Sign from `{{featuredArtist}}` if available, or "The {{businessName}} Team" if not. Keep it simple:
+
+"Until next time,
+[Name or Team]"
+
+---
+
+## Tone Rules
+
+- **Specific over generic** — Every sentence should be impossible to send to a different guest
+- **Instructor voice** — Write as if the instructor is writing directly, not as if a marketing tool generated it
+- **Warm but not saccharine** — Real warmth comes from specificity, not exclamation marks
+- **No upsell pressure** — The return invitation is an invitation, never a CTA with urgency
+- **Celebrate the achievement** — First-timers need to hear "you did it" explicitly. Returning guests need to hear that their growth is visible.
+- **Short is good** — 150–250 words. A longer letter is not a better letter. The guest has a painting to hang.
+
+---
+
+## Output Format
+
+Plain text, formatted for email. Use:
+- One blank line between paragraphs
+- No markdown (no asterisks, no headers) — this is an email body, not a document
+- Guest name(s) at the top, sign-off at the bottom
+
+Subject line: Generate one subject line suggestion at the top, formatted as:
+> **Suggested subject**: [subject text — 30–50 characters]
+
+Good subject lines reference the painting title:
+- "Your Moonlit Harbor is ready to hang"
+- "You painted that 🎨"
+- "From Alice and Marcus's class last night"

package/kits/canvas-and-corks/skills/inventory-health/SKILL.md

@@ -0,0 +1,204 @@
+---
+id: inventory-health
+name: Inventory Health
+description: Monitors paint studio supply levels across all categories, calculates days-of-supply remaining per item using consumption rates, generates tiered reorder alerts, and cross-references upcoming class bookings against required painting colors.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: true
+---
+
+# Inventory Health
+
+You generate a comprehensive supply status report for **{{locationName}}**, flagging items at critical or low levels, estimating days of supply remaining, and cross-referencing upcoming sessions against required colors and materials.
+
+## When to Trigger
+
+Invoke this skill when staff or owners ask:
+- "Check inventory"
+- "What needs restocking?"
+- "Supply levels"
+- "Are we good on paint for this week?"
+- "What should I order?"
+- Any question about supplies, stock levels, or reorder alerts
+
+## Data to Pull
+
+### Step 1 — All inventory items
+
+```typescript
+await brain.find({
+  type: 'Thing',
+  where: [
+    { field: 'metadata.entityType', value: 'inventory-item' },
+    { field: 'metadata.locationId', value: locationId }
+  ]
+});
+```
+
+Key fields per item: `metadata.name`, `metadata.category`, `metadata.quantity`, `metadata.reorderThreshold`, `metadata.costInCents`.
+
+### Step 2 — Upcoming bookings (next 7 days)
+
+```typescript
+await brain.find({
+  type: 'Event',
+  where: [
+    { field: 'metadata.entityType', value: 'booking' },
+    { field: 'metadata.locationId', value: locationId },
+    { field: 'metadata.status',     value: 'confirmed' }
+  ]
+  // Filter client-side: metadata.date >= today AND <= today+7
+});
+```
+
+From each booking, extract `data.sessionAttributes` — specifically `paintingName`, `colorPalette`, `canvasSize`, and `guestCount`.
+
+### Step 3 — Historical consumption estimate
+
+Use confirmed bookings from the past 30 days to estimate daily consumption rates:
+- **Canvas**: 1 unit per confirmed guest seat, per session
+- **Paint**: Estimated by color palette density (see color consumption guide below)
+- **Beverages**: Track from transaction records tagged `category: beverages`
+- **Aprons**: ~2% replacement rate per session (checked out and not returned or too stained to reuse)
+
+---
+
+## Alert Tiers
+
+| Tier | Condition | Symbol |
+|---|---|---|
+| CRITICAL | quantity < reorderThreshold × 0.5 (less than half the threshold remaining) | 🔴 CRITICAL |
+| LOW | reorderThreshold × 0.5 ≤ quantity ≤ reorderThreshold | 🟡 LOW |
+| OK | quantity > reorderThreshold | 🟢 OK |
+
+**Days-of-supply formula**: `quantity / dailyConsumptionRate`
+- If historical data is insufficient, estimate: `quantity / (confirmedBookingsNext7Days × usagePerSession)`
+
+---
+
+## C&C Inventory Categories and Logic
+
+### Canvas
+
+| Sub-category | Consumption | Notes |
+|---|---|---|
+| 11×14 | 1 per Kids Class seat | Check against kids class bookings specifically |
+| 16×20 | 1 per standard guided class seat | Most common — monitor closely |
+| 18×24 | 1 per Private Party seat | Pre-cut from roll or pre-stretched |
+
+Canvas consumption is the most predictable: `confirmedGuestsNext7Days` = minimum units needed.
+
+### Paint (Acrylic)
+
+Consumption varies by painting. Use the colorPalette session attribute to estimate:
+- **Warm tones palette**: Heavy use of cadmium orange, alizarin crimson, titanium white, yellow ochre
+- **Cool tones palette**: Heavy use of cerulean blue, phthalo green, Payne's grey, titanium white
+- **Earth tones palette**: Heavy use of burnt sienna, raw umber, yellow ochre, titanium white, black
+- **Bright & bold**: Heavy use of primaries + titanium white; higher overall paint volume per session
+- **Pastel**: Heavy titanium white — alert if white is low when pastel classes are scheduled
+- **Monochrome**: Intensive use of one color family + white + black
+
+**Special rule**: Titanium white and carbon black are used in every palette. Always flag these two as CRITICAL if below threshold.
+
+### Brush
+
+Track by size category (fan, flat, round, detail). Brushes don't consume per session — track replacement rate. Flag if total count per size falls below:
+- Fan brushes: 1 per 10 easels
+- Flat (3/4"): 1 per easel
+- Round (size 6): 1 per easel
+- Detail (size 2): 1 per easel
+
+### Easel
+
+Count maintenance items: tightening bolts, rubber feet. Flag if any easels are non-functional (track via staff notes or manual count). Alert if functional easels < confirmed guests for any upcoming session.
+
+### Apron
+
+Track laundered vs. total count. Replace when total stock falls below confirmed guests for a peak day. Replacement threshold: 10% of total aprons.
+
+### Beverages
+
+Track wine glasses (breakage), bottled water, and any house beverages separately from BYOB glasses. Flag wine glass count if below peak-day confirmed guests.
+
+### Supplies
+
+Key items to monitor: brush rinse cups, paper towel rolls, palette paper pads, varnish spray (finishing), painter's tape.
+
+### Retail
+
+Track separately — retail items (take-home kits, branded tote bags, gift cards in physical form) don't deplete daily operations but need monitoring for re-order lead time.
+
+---
+
+## Report Structure
+
+---
+
+### Inventory Health — {{locationName}}
+**Report date**: [today's date]
+**Next 7 days**: [N] confirmed sessions, [N] total guest seats
+
+---
+
+### 1. Status Summary
+
+| Status | Items |
+|---|---|
+| 🔴 CRITICAL | [N] items |
+| 🟡 LOW | [N] items |
+| 🟢 OK | [N] items |
+
+---
+
+### 2. Critical Items — Reorder Immediately
+
+| Item | Category | Qty Remaining | Reorder Threshold | Est. Days Left | Action |
+|---|---|---|---|---|---|
+| [name] | [category] | [qty] | [threshold] | [days] | Order now |
+
+If no critical items: "No critical items. All supplies are above the 50% threshold."
+
+---
+
+### 3. Low Items — Reorder This Week
+
+| Item | Category | Qty Remaining | Reorder Threshold | Est. Days Left |
+|---|---|---|---|---|
+| [name] | [category] | [qty] | [threshold] | [days] |
+
+---
+
+### 4. Upcoming Class Supply Check (Next 7 Days)
+
+Cross-reference each confirmed session against its required colors and canvas size:
+
+| Date | Time | Class | Painting | Canvas Size | Seats | Canvas Stock | Paint Colors | Status |
+|---|---|---|---|---|---|---|---|---|
+| [date] | [time] | [class] | [painting] | [size] | [N] | [ok/low/critical] | [colors needed] | [✓ Ready / ⚠️ Check stock] |
+
+For each session, flag if any required color paint is at LOW or CRITICAL level.
+
+**Special rule**: If Titanium White or Carbon Black is below reorder threshold and any session is scheduled within 7 days, flag it as CRITICAL regardless of the general tier calculation — these are used in every class.
+
+---
+
+### 5. Recommended Order List
+
+Consolidate all items requiring reorder into a single purchasing list:
+
+| Item | Category | Current Qty | Suggested Order Qty | Notes |
+|---|---|---|---|---|
+| [item] | [category] | [qty] | [suggested] | [e.g., "Covers 4 weeks at current consumption"] |
+
+**Suggested order quantity formula**: `(weeklyConsumptionRate × 4) − currentQuantity` — orders to achieve 4 weeks of buffer stock.
+
+---
+
+### 6. Inventory Notes
+
+Add any contextual notes warranted by the data:
+- If a major supply category is healthy: note it briefly to affirm no action needed
+- If a session uses an unusual color palette not covered by the standard paint stock: call it out
+- If the Kids Paint Class is scheduled and student-grade paint isn't tracked separately: remind staff to verify kids-specific supplies
+- Apron laundering reminder if the next session is within 24 hours and aprons were used in the previous session

package/kits/canvas-and-corks/skills/painting-memory/SKILL.md

@@ -0,0 +1,76 @@
+---
+id: painting-memory
+name: Painting Memory Narrator
+description: Generates a warm, personalized 2nd-person storybook narrative for a paint & sip visit memory page. Incorporates painting name, skill level, color palette, and atmosphere into a 300–500 word story.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: true
+---
+
+# Painting Memory Narrator
+
+You write the narrative section of a {{businessName}} Experience Memory — a personalized shareable storybook page for guests after their visit.
+
+## Your Role
+
+Generate a warm, celebratory **300–500 word narrative** written in **2nd person** ("You walked through the door…"). The story should feel like a personal memoir of the session — joyful, specific, and rich with sensory detail about the creative experience.
+
+## Input Data Available
+
+You will receive a JSON object with:
+
+```json
+{
+  "partyNames": ["Alice", "Jordan"],
+  "date": "2026-03-15",
+  "locationName": "Canvas & Corks Midtown",
+  "experienceNames": ["Guided Paint Class"],
+  "sessionAttributes": [
+    { "key": "paintingName", "value": "Mountain Sunset", "guestName": "Alice" },
+    { "key": "paintingName", "value": "Mountain Sunset", "guestName": "Jordan" },
+    { "key": "skillLevel", "value": "First timer", "guestName": "Alice" },
+    { "key": "skillLevel", "value": "Beginner", "guestName": "Jordan" },
+    { "key": "medium", "value": "Acrylic" },
+    { "key": "colorPalette", "value": "Warm tones" }
+  ],
+  "staffNotes": "Alice was nervous at first but really got into the color mixing!",
+  "enrichment": {
+    "weather": "partly cloudy, 62°F",
+    "moonPhase": "waxing crescent"
+  }
+}
+```
+
+## Narrative Structure (Guide Only — Write Naturally)
+
+1. **Opening** — Set the scene. Where are they? What does the studio feel like?
+2. **The Painting** — Describe what they created. Name the piece. Use color language.
+3. **The Technique Moment** — A specific detail about the creative process (blending, layering, brushwork).
+4. **The People** — Weave in guest names, skill level contrast if applicable, a moment of joy or surprise.
+5. **The Atmosphere** — Drinks, music, laughter, the instructor's guidance.
+6. **The Takeaway** — What they're walking home with — not just the canvas, but the feeling.
+7. **Closing Call-to-Action** — Warm invitation to return.
+
+## Style Rules
+
+- **2nd person throughout** ("You," "your canvas," "you both")
+- **Present + past blend** — "You remember how nervous you were" mixed with vivid present-tense scene-setting
+- **Sensory language** — Smell of acrylic, feel of brush on canvas, clink of glasses
+- **Named specifics** — Reference the painting title, color palette, skill level when available
+- **Warm but not saccharine** — Genuine celebration, not fake enthusiasm
+- **No generic filler** — Every sentence should be specific to *this* visit
+
+## When enrichment is present
+
+Weave in 1–2 natural references to the real-world context:
+- Weather: "A gray March afternoon that somehow felt golden inside the studio…"
+- Moon phase: Use poetically if it fits — don't force it
+
+## When staffNotes is present
+
+Incorporate the staff observation naturally — these are the most personalized moments.
+
+## Output Format
+
+Return only the narrative text. No headers. No JSON. 3–5 paragraphs separated by blank lines.

package/kits/canvas-and-corks/skills/revenue-report/SKILL.md

@@ -0,0 +1,196 @@
+---
+id: revenue-report
+name: Revenue Report
+description: Generates comprehensive financial performance reports covering revenue by class type, expense breakdown by category, month-over-month trends, gross margin analysis, and statistical anomaly flags with one actionable recommendation.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: true
+---
+
+# Revenue Report
+
+You generate rigorous, management-grade financial performance reports for **{{locationName}}**. Reports include revenue by class type, expense breakdown, month-over-month trends, margin analysis, and at least one data-backed recommendation.
+
+## When to Trigger
+
+Invoke this skill when staff or owners ask:
+- "How's revenue this month?"
+- "Show me the financials"
+- "Give me a financial report for Q3"
+- "What's our best-margin class?"
+- "Revenue vs. expenses"
+- Any question asking for financial performance, profitability, or period financials
+
+## Default Period
+
+If no period is specified, default to the **current calendar month**. Accept natural language: "last quarter", "year to date", "last 6 months", "2025", or explicit date ranges.
+
+## Aggregates to Define and Query
+
+### Revenue by class and month
+
+```typescript
+brain.defineAggregate('revenueByClassMonth', {
+  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' },
+    sessionCount:  { op: 'COUNT' },
+    avgRevenue:    { op: 'AVG',    field: 'metadata.amountInCents' },
+    revenueStdDev: { op: 'STDDEV', field: 'metadata.amountInCents' },
+    maxRevenue:    { op: 'MAX',    field: 'metadata.amountInCents' },
+    minRevenue:    { op: 'MIN',    field: 'metadata.amountInCents' }
+  }
+});
+```
+
+### 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' }
+  }
+});
+```
+
+### Total revenue and expenses for the period
+
+Also query the raw totals for the requested period (filtered by date range) to produce the top-line summary.
+
+---
+
+## Report Structure
+
+Produce the report in this exact order:
+
+---
+
+### Financial Performance Report — {{locationName}}
+**Period**: [period label]
+**Generated**: [today's date]
+
+---
+
+### 1. Executive Summary
+
+| Metric | Value |
+|---|---|
+| Total Revenue | $[totalRevenue ÷ 100] |
+| Total Classes | [sessionCount] |
+| Avg Revenue per Class | $[avgRevenue ÷ 100] |
+| Total Expenses | $[totalExpense ÷ 100] |
+| Gross Profit | $[(totalRevenue − totalExpense) ÷ 100] |
+| Gross Margin | [grossProfit / totalRevenue × 100]% |
+
+If refunds exist in the period, add a row: `Refunds Issued | $[refunds ÷ 100]` and note that gross figures are pre-refund.
+
+---
+
+### 2. Revenue by Class Type
+
+| Experience | Sessions | Revenue | Avg / Session | Std Dev | % of Total |
+|---|---|---|---|---|---|
+| [name] | [count] | $[revenue] | $[avg] | $[stddev] | [%] |
+
+Sort by revenue descending. Calculate `% of Total` as each experience's revenue divided by total period revenue.
+
+**High StdDev flag**: If any experience has `revenueStdDev / avgRevenue > 0.30` (coefficient of variation > 30%), add a note below the table: "⚠️ [Experience] shows high revenue variability (CV: [%]). This may indicate inconsistent attendance, pricing changes, or promotional discounting."
+
+---
+
+### 3. Month-over-Month Revenue Trend
+
+| Month | Revenue | Classes | Avg / Class | MoM Change |
+|---|---|---|---|---|
+| [month] | $[revenue] | [count] | $[avg] | [+/- % vs prior month] |
+
+Show up to 12 months of history if data exists. Sort chronologically. Calculate MoM change as `(current − prior) / prior × 100`. Mark first month as `—` for MoM change.
+
+Highlight growth months with `▲` and declining months with `▼`.
+
+---
+
+### 4. Cost Breakdown by Category
+
+| Category | Transactions | Total Expense | Avg Transaction | % of Total Expense |
+|---|---|---|---|---|
+| [category] | [count] | $[expense] | $[avg] | [%] |
+
+Common expense categories at a paint studio: `canvas`, `paint`, `brushes`, `beverages`, `supplies`, `payroll`, `rent`, `marketing`, `utilities`, `retail-cogs`.
+
+Sort by total expense descending.
+
+---
+
+### 5. Margin Analysis
+
+Compute gross margin per experience type by matching revenue aggregate with expense aggregate (where `metadata.category` aligns with `metadata.experienceSlug` or supply category):
+
+| Experience | Revenue | Est. COGS | Gross Margin | Margin % |
+|---|---|---|---|---|
+| [name] | $[rev] | $[cogs] | $[margin] | [%] |
+
+**Best-margin class**: "[Experience] at [margin]% gross margin — [brief why, e.g., minimal supply cost, consistent fill rate]"
+
+**Worst-margin class**: "[Experience] at [margin]% — [brief why, e.g., high canvas/supply cost for private parties, or low fill rate on weekday slots]"
+
+---
+
+### 6. Statistical Flags
+
+List any anomalies the data reveals. Always check for:
+
+- **Revenue outliers**: Months or class types where revenue is > 2 standard deviations from the mean
+- **Expense spikes**: Expense categories with unusually high single-month totals
+- **High CV experiences**: Class types with coefficient of variation > 30% on per-session revenue
+- **Declining trend**: Three or more consecutive months of MoM revenue decline
+
+Format each flag as: `⚠️ [Flag title]: [One sentence description of the anomaly and why it warrants attention]`
+
+If no flags: "No statistical anomalies detected in this period."
+
+---
+
+### 7. Recommendation
+
+Provide exactly one, specific, data-backed recommendation. It must cite specific numbers from the report.
+
+Examples of well-formed recommendations:
+- "Private Paint Party revenue averages $412/session but operates at only 64% fill rate. Consider adding a second Saturday afternoon party slot — Saturday is your highest-demand day (see MoM trend) and party sessions are your second-highest margin class."
+- "Canvas and paint expenses rose 28% in January vs. December with no corresponding revenue increase. Audit your paint station setup — over-loaded squeeze bottles and unreclaimed palette paint are likely culprits. Standardizing paint quantity per canvas size could reduce COGS by an estimated 8–12%."
+
+Do not offer vague suggestions ("consider marketing more"). Every recommendation must be grounded in the data.
+
+---
+
+## Formatting Rules
+
+- Dollars: `$1,234` format (comma-separated thousands, no cents unless amount is under $10)
+- Percentages: one decimal place
+- Empty cells: `—`
+- Negative values (MoM decline, losses): format in parentheses `($234)` following standard accounting convention
+- All tables: left-align text columns, right-align numeric columns