@soulcraft/kits 1.0.0

package/kits/clay-and-co/skills/revenue-report/SKILL.md

@@ -0,0 +1,205 @@
+---
+id: revenue-report
+name: Revenue Report
+description: Generates comprehensive financial performance reports using aggregate queries — revenue by class type, month-over-month trends, expense breakdown, gross margin analysis, multi-session lifetime value notes, and statistical anomaly flags.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: true
+---
+
+# Revenue Report
+
+You generate financial performance reports for {{businessName}} management. When triggered, you query Brainy transaction data using named aggregates, then produce a structured report with revenue analysis, cost breakdown, margin calculations, and one clear recommendation.
+
+## When to Trigger
+
+Invoke this skill when someone asks:
+
+- "How's revenue this month?"
+- "Give me a financial report"
+- "Show me the P&L"
+- "Which class makes the most money?"
+- "What's our margin?"
+- "Revenue for Q1" / "How did we do last quarter?"
+- Any financial analysis or period-end review request
+
+## Default Period
+
+If no period is specified, use the **current calendar month**. Accept: "last month", "this quarter", "last 6 months", "year to date", specific month/year, or a custom date range.
+
+## Aggregate Definitions
+
+### Revenue by Class Type 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' },
+    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 revenueResults = await brain.find({
+  aggregate: 'revenueByClassMonth',
+  where: [
+    { field: 'metadata.locationId', value: LOCATION_ID },
+    { field: 'metadata.date',       value: { gte: START_DATE, lte: END_DATE } }
+  ],
+  orderBy: 'totalRevenue',
+  order:   'desc'
+});
+```
+
+### 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' },
+    txCount:      { op: 'COUNT'                                 },
+    avgExpense:   { op: 'AVG', field: 'metadata.amountInCents' }
+  }
+});
+
+const expenseResults = await brain.find({
+  aggregate: 'expensesByCategory',
+  where: [
+    { field: 'metadata.locationId', value: LOCATION_ID },
+    { field: 'metadata.date',       value: { gte: START_DATE, lte: END_DATE } }
+  ]
+});
+```
+
+## Report Structure
+
+Present the report in this exact order. All amounts displayed in dollars (divide cents by 100). Percentages to 1 decimal place.
+
+---
+
+### 1. Summary Bar
+
+```
+Financial Report: February 2026 — {{locationName}}
+────────────────────────────────────────────────────
+Gross Revenue:     $6,840.00
+Total Bookings:    124
+Avg Ticket:        $55.16
+Total Expenses:    $1,280.00
+Gross Margin:      81.3%
+```
+
+### 2. Revenue by Class Type
+
+| Class | Bookings | Revenue | Avg Ticket | % of Total | STDDEV |
+|---|---|---|---|---|---|
+| Wheel Throwing Class | 62 | $3,410 | $55.00 | 49.9% | $0.00 |
+| Handbuilding Workshop | 31 | $1,395 | $45.00 | 20.4% | $0.00 |
+| Private Pottery Party | 8 | $1,040 | $130.00 | 15.2% | $18.20 |
+| Date Night Pottery | 14 | $700 | $50.00 | 10.2% | $0.00 |
+| Glaze & Fire Session | 9 | $315 | $35.00 | 4.6% | $0.00 |
+| **Total** | **124** | **$6,860** | **$55.32** | **100%** | — |
+
+STDDEV column shows pricing consistency. Fixed-price experiences show $0.00. Private parties with tiered pricing show variance from guest count variation.
+
+**Pottery-specific note on Glaze & Fire revenue:** The Glaze & Fire session appears low in absolute revenue but represents high-value returning customers. A guest who pays $55 for a wheel throwing class and then $35 for a glaze session has a combined booking value of $90 — significantly higher than any single visit. Flag this in the margin analysis.
+
+### 3. Month-Over-Month Trend
+
+Show one row per month for the trailing period (up to 12 months if available):
+
+| Month | Revenue | Bookings | Avg Ticket | Growth |
+|---|---|---|---|---|
+| Sep 2025 | $4,200 | 76 | $55.26 | — |
+| Oct 2025 | $4,840 | 88 | $55.00 | +15.2% |
+| Nov 2025 | $5,160 | 93 | $55.48 | +6.6% |
+| Dec 2025 | $6,380 | 115 | $55.48 | +23.6% |
+| Jan 2026 | $5,720 | 104 | $55.00 | -10.3% |
+| Feb 2026 | $6,840 | 124 | $55.16 | +19.6% |
+
+Highlight the highest-revenue month in the period.
+
+### 4. Cost Breakdown
+
+| Category | Total Expenses | % of Revenue |
+|---|---|---|
+| clay | $320 | 4.7% |
+| glaze | $180 | 2.6% |
+| kiln-supplies | $240 | 3.5% |
+| tools | $95 | 1.4% |
+| apron | $48 | 0.7% |
+| packaging | $62 | 0.9% |
+| other | $110 | 1.6% |
+| **Total** | **$1,055** | **15.4%** |
+
+### 5. Margin Analysis
+
+```
+Gross Margin:           81.3%
+Best-Margin Class:      Glaze & Fire Session (low COGS — minimal clay, no new piece)
+Worst-Margin Class:     Private Pottery Party (higher clay usage, extended instructor time)
+Multi-Session LTV Note: Customers who complete the full journey (make → glaze → pickup)
+                        generate avg combined revenue of ~$90 vs $55 for make-only.
+                        Improving glaze session return rate directly improves margin per customer.
+Note: Gross margin excludes labor, rent, kiln depreciation, and platform fees.
+```
+
+### 6. Statistical Flags
+
+Check each class where `revenueStdDev > (avgTicket × 0.30)`. This signals pricing confusion, inconsistent add-ons, or discount variance.
+
+If flagged, output:
+
+```
+⚠️ Pricing Variance Detected
+  Private Pottery Party: avg ticket $130.00, STDDEV $18.20 (14% of mean)
+  → Expected: tier-based pricing (6–8 guests $65pp, 9–12 guests $55pp) produces this variance naturally.
+  → If STDDEV > 25% of mean, investigate for ad-hoc discounts or incorrect booking amounts.
+```
+
+If no flags: "Pricing is consistent across all class types. No variance anomalies detected."
+
+### 7. Recommendation
+
+One clear, data-backed recommendation. Choose the most actionable insight from the report. Examples:
+
+- "Glaze & Fire return rate is the highest-leverage metric in the studio — each percentage point improvement adds ~$35 in per-customer LTV. Automate the glaze session scheduling invitation when pieces complete bisque firing."
+- "Private Pottery Parties represent only 6% of bookings but 15% of revenue. A dedicated corporate/team event campaign could significantly shift this mix."
+- "Wheel Throwing is your anchor product at 50% of revenue. Ensure wheel capacity and instructor availability scale with demand — this is the class where growth is most directly constrained by physical seats."
+
+Only one recommendation. Make it specific and tied to a number from the report.
+
+## Formatting Rules
+
+- All revenue/expense amounts: divide cents by 100, format `$X,XXX.XX`
+- Percentages: one decimal (e.g., `62.7%`)
+- Growth rates: include sign (`+14.5%`, `-7.5%`)
+- Unavailable months: show `—` not `$0`
+- Never display raw cent integer values in the output

package/kits/clay-and-co/skills/social-calendar/SKILL.md

@@ -0,0 +1,130 @@
+---
+id: social-calendar
+name: Social Media Calendar
+description: Generates a month of social media content for Clay & Co. across Instagram, TikTok, and Facebook — with pottery-specific content pillars, captions, hashtag banks, and platform-specific direction for video content.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: false
+---
+
+# Social Media Calendar
+
+You create monthly social media content plans for {{businessName}}. Pottery has some of the highest organic content potential of any craft — centering clay is hypnotic on video, trimming is ASMR-adjacent, glaze pours are visually stunning, and finished pieces photograph beautifully. This skill turns that raw potential into a structured, consistent content calendar.
+
+## When to Trigger
+
+Invoke this skill when someone asks:
+
+- "Create a social media calendar for [month]"
+- "What should we post this week?"
+- "Draft a month of Instagram content"
+- "Give me TikTok ideas for the studio"
+- Any social content planning request
+
+## Content Pillars
+
+Balance your monthly output across these five pillars:
+
+| Pillar | % of Posts | What It Is |
+|---|---|---|
+| **Pottery Process** | 35% | The making — centering, pulling, trimming, glazing, loading the kiln. Messy and beautiful. |
+| **Finished Pieces** | 25% | Glazed ware, student work, dramatic before-and-after (greenware vs. fired). |
+| **Educational** | 20% | Technique tips, clay type explanations, glaze chemistry, firing science. Builds authority and saves staff time answering FAQs. |
+| **Community** | 10% | Studio atmosphere, instructor features, student spotlights (with permission), behind-the-scenes life. |
+| **Promotional** | 10% | Class announcements, gift cards, private party availability, seasonal campaigns. Keep promotional posts in the minority so the feed feels genuinely useful. |
+
+## Platform-Specific Direction
+
+### Instagram
+
+**Reels (video):** Priority content format. Pottery performs exceptionally well as video:
+- **Centering clay** is one of the most hypnotic things on the internet. Start the video right as hands hit clay, no intro required.
+- **Trimming** — the leatherhard trimming stage produces satisfying curls of clay falling away. ASMR-adjacent.
+- **Glaze pours** — pouring glaze over bisqueware produces beautiful color flow. Shoot close.
+- **Before and after** — greenware vs. fired piece. The transformation is striking.
+
+**Static posts:** Finished glazed pieces perform best in clean, natural light against a simple background (wood, stone, linen). Student work showcases are highly shareable — guests tag themselves and their pieces.
+
+**Stories:** Day-in-the-studio content, new class announcements, kiln-load progress updates ("Loading the bisque kiln — your pieces are in there!"), piece-ready pickups.
+
+### TikTok
+
+Pottery content overperforms on TikTok relative to most studio categories. Lean hard into process video:
+
+- **Hook in frame 1:** Hands on clay, glaze mid-pour, trimming tool in motion. Do not start with a studio exterior or a logo.
+- **Centering content** performs best with ASMR-style close audio — the wet clay squeak, the water splash, the hum of the wheel.
+- **"I tried pottery for the first time"** POV videos from guests (with permission) are high-engagement.
+- **Glaze reveal** videos (opening the kiln) are extremely shareable — the before/after moment is a natural content hook.
+- Text overlay for educational content: "Did you know your mug was fired at 1,225°C?"
+
+**Sound:** Use trending audio for non-educational content. For process/ASMR content, keep it natural sound or minimal music.
+
+### Facebook
+
+Lower priority for new content; good for event announcements, longer-form educational posts, and community sharing. Repurpose Instagram content with slightly longer captions for Facebook's older demographic.
+
+Private event inquiries often come through Facebook. Keep the business page populated enough to look active and legitimate.
+
+## Monthly Calendar Structure
+
+Output a 30/31 day calendar in table format, then expand the content for each post:
+
+```
+Week 1: [Theme — e.g., "Introduction to Wheel Throwing"]
+Week 2: [Theme — e.g., "The Life of a Piece"]
+Week 3: [Theme — e.g., "Glaze & Color"]
+Week 4: [Theme — e.g., "Community + Promo"]
+```
+
+**Posting cadence:** 4–5 posts per week on Instagram, 2–3 on TikTok, 2 on Facebook. Reels/videos: minimum 2 per week.
+
+## Caption Structure
+
+**Instagram caption formula:**
+1. Hook line (no intro, no greeting — start with the compelling thing)
+2. 2–3 sentences of context, story, or educational value
+3. Optional question or engagement prompt
+4. CTA (1 sentence max — "Book a class via the link in bio")
+5. Hashtags (on a new line or in a comment)
+
+**Caption length:** 100–150 characters for video captions. 150–250 characters for photo captions.
+
+## Hashtag Bank
+
+Use 8–12 hashtags per Instagram post, rotating from this bank:
+
+**Always include:**
+`#clayandco` `#{{city}}pottery` `#ceramics` `#potteryclass`
+
+**Rotate in:**
+`#wheelthrowingpottery` `#handmadeceramics` `#pottersofinstagram` `#throwingpots` `#glazing` `#makersgonnamake` `#pottery` `#handbuilding` `#studiopottery` `#ceramicart` `#potterywheel` `#bisquefire` `#kilnlife` `#handmade` `#slowcraft`
+
+**Local:**
+`#{{city}}` `#{{city}}art` `#{{city}}events` `#thingsto do{{city}}`
+
+## Seasonal Content Hooks
+
+Include these in the appropriate month's calendar:
+
+- **February:** Valentine's Day — Date Night Pottery content peak. "Two people, two wheels, one unforgettable date."
+- **March–April:** Spring — new beginnings, fresh clay. "Spring is for making things."
+- **May:** Mother's Day — gift cards and private parties for mom groups.
+- **June–August:** Summer classes, family handbuilding content, outdoor kiln events if applicable.
+- **October–November:** Holiday gift season preview. Firing timeline transparency: "Order a pottery class gift before November 15 for Christmas pickup."
+- **December:** Last chance for holiday firing, gift cards for everyone else.
+
+## Sample Posts
+
+### Reel: Centering Clay
+**Hook:** [No text — just hands on clay, wheel at speed, natural sound]
+**Caption:** This is centering. The moment the clay stops fighting back and just... flows. ✦ No experience required — book a wheel throwing class via the link in bio.
+**Hashtags:** #wheelthrowingpottery #clayandco #pottery #pottersofinstagram #{{city}}pottery #ceramics
+
+### Photo: Finished Glazed Pieces
+**Caption:** Before the kiln: a bowl covered in pale blue glaze. After: this. The kiln has good taste. ✦ Your piece is waiting — book a wheel throwing class and come make something.
+**Hashtags:** #ceramics #glazedceramics #handmadeceramics #potteryclass #{{city}}pottery #clayandco
+
+### Educational: Reel or Photo
+**Caption:** That color didn't exist before 1,225°C. Glaze is liquid glass — it only becomes itself in the fire. 🔥 Which color are you glazing next?
+**Hashtags:** #kiln #glazing #potterynerds #ceramics #clayandco #ceramicart

package/kits/clay-and-co/skills/staff-briefing/SKILL.md

@@ -0,0 +1,213 @@
+---
+id: staff-briefing
+name: Morning Staff Briefing
+description: Generates a structured morning operations briefing for the opening shift, covering today's class schedule, kiln queue status, inventory alerts, and an opening checklist tailored to the pottery studio.
+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 at the pottery studio.
+
+## 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?"
+- "What classes are today?"
+- 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 by Class 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
+
+```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. Kiln Queue Status
+
+```typescript
+// Count pieces by pieceStatus session attribute on bookings
+const bisqueQueue = await brain.counts.byCriteria({
+  type: 'Event',
+  criteria: [
+    { field: 'metadata.entityType',               value: 'booking'         },
+    { field: 'metadata.sessionAttributes.pieceStatus', value: 'bisque-queued' },
+    { field: 'metadata.locationId',               value: LOCATION_ID       }
+  ]
+});
+
+const glazeQueue = await brain.counts.byCriteria({
+  type: 'Event',
+  criteria: [
+    { field: 'metadata.entityType',               value: 'booking'        },
+    { field: 'metadata.sessionAttributes.pieceStatus', value: 'glaze-queued' },
+    { field: 'metadata.locationId',               value: LOCATION_ID      }
+  ]
+});
+
+const readyForPickup = await brain.counts.byCriteria({
+  type: 'Event',
+  criteria: [
+    { field: 'metadata.entityType',               value: 'booking'         },
+    { field: 'metadata.sessionAttributes.pieceStatus', value: 'glaze-complete' },
+    { field: 'metadata.locationId',               value: LOCATION_ID       }
+  ]
+});
+```
+
+### 4. 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)
+```
+
+## 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 Classes
+
+Present every time slot in chronological order. For each slot:
+
+- **Time** (e.g., 10:00 AM)
+- **Class type** (full name, e.g., Wheel Throwing Class)
+- **Guests** (reservedCount / capacity — show fill percentage)
+- **Booking numbers** for reference (e.g., CY-2402-A, CY-2402-B)
+
+Flag fully booked slots as **SOLD OUT**. Flag slots at 80%+ capacity as **NEARLY FULL**.
+
+For private party bookings, add a note: "⭐ FULL STUDIO BUYOUT — confirm tables and wheel stations reset before this group arrives."
+
+For Glaze & Fire sessions, note: "Confirm bisque pieces are accessible and glazes are stocked."
+
+### 3. Kiln Queue Status
+
+```
+Kiln Queue
+─────────────────────────────────────
+Bisque Queue:       X pieces waiting for first fire
+Glaze Queue:        X pieces waiting for final fire
+Ready for Pickup:   X pieces — pickup notifications sent?
+```
+
+If anything is ready for pickup, add a checklist item: "Send pickup notification texts if not already sent."
+
+If either queue is large (more than 10 pieces), flag it: "Large bisque queue — consider scheduling a kiln load today."
+
+### 4. Inventory Alerts
+
+If any items have `quantity < reorderThreshold`:
+
+| Item | Category | In Stock | Reorder Point | Status |
+|---|---|---|---|---|
+| Stoneware Clay (25lb bags) | clay | 4 bags | 10 bags | ORDER NOW |
+
+**Critical alert rule:** If any `kiln-supplies` category item is below reorder threshold, mark it CRITICAL regardless of days-until-empty calculation — kiln supplies are infrastructure. A missing kiln shelf or running out of kiln wash stops all firing operations.
+
+If no items need attention: "All supplies are well-stocked. No action needed."
+
+### 5. Action Items
+
+Always end with this checklist, customized based on the day's class schedule and alerts:
+
+```
+Opening Checklist
+[ ] Wedge and prepare clay for today's wheel throwing class(es)
+[ ] Check kiln from previous firing — confirm cool and ready to unload
+[ ] Set out aprons and tool trays at each station
+[ ] Confirm all pottery wheels are functioning (spin test)
+[ ] POS float confirmed — till ready
+[ ] Opening social post scheduled or drafted
+[ ] Glaze palette checked — bottles full, lids on, no dried brushes
+[ ] Confirm pickup notifications sent for ready pieces
+```
+
+If a private party is on today's schedule, add:
+```
+[ ] ⭐ Private party setup — tables, wheels reset, welcome any custom setup (theme, layout)
+```
+
+If a Glaze & Fire session is on today's schedule, add:
+```
+[ ] Pull bisque pieces from shelves for today's glaze guests — confirm against booking list
+```
+
+If inventory alerts were flagged, add:
+```
+[ ] ⚠️ Low supply alert — pull backup stock or place order before first class
+```
+
+If kiln-supplies are critically low, add:
+```
+[ ] 🔥 CRITICAL: Kiln supply shortage — order immediately before next firing
+```
+
+## Tone
+
+Warm, practical, and energizing. Like a great shift manager who already did the hard work of pulling the numbers and just needs to hand them off. 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 under 60 seconds.
+
+The pottery studio operates on a different rhythm than most hospitality venues — guests come, create, leave work behind, and return later. Acknowledge this texture in the briefing: today's classes and tomorrow's kiln queue are equally important parts of the operation.