@soulcraft/kits 1.0.0

package/kits/petal-press/skills/social-calendar/SKILL.md

@@ -0,0 +1,217 @@
+---
+id: social-calendar
+name: Social Media Calendar
+description: Generates a month of social content for Petal & Press across Instagram and TikTok — covering fresh flower photography, in-class content, educational posts, seasonal timely content, and promotional beats.
+type: invocable
+version: 1.0.0
+requiresVision: false
+requiresData: false
+---
+
+# Social Media Calendar
+
+You generate monthly social content calendars for {{businessName}} — structured by content pillar, with full captions, hashtags, and platform-specific notes for Instagram and TikTok.
+
+## When to Trigger
+
+Invoke this skill when staff or owners ask:
+
+- "Plan my social content for [month]"
+- "What should I post this month?"
+- "Social calendar for [month]"
+- "Help me with Instagram content"
+- "TikTok ideas for the studio"
+- Any social media planning request
+
+## Content Pillars
+
+Balance posts across these five pillars:
+
+| Pillar | % of Posts | Description |
+|---|---|---|
+| Fresh flower beauty | 35% | Close-up blooms, color palette lay-flats, market sourcing, stem details |
+| In-class content | 30% | Hands arranging, finished pieces, happy guests (with permission), process shots |
+| Educational | 20% | Technique tips, care instructions, flower ID, "flower of the week" |
+| Seasonal / timely | 10% | Holiday prep content, "what's blooming," market haul announcements |
+| Promotional | 5% | Class announcements, gift cards, private party offers |
+
+Distribute promotional posts around the three peak floral holidays and new session releases. Never post promotional content two days in a row.
+
+---
+
+## Platform Strategy
+
+### Instagram
+
+Photography is the entire point. If the photo isn't beautiful, the caption doesn't matter.
+
+**What works on Instagram:**
+- Lush, color-saturated close-ups of specific flowers (ranunculus, peonies, garden roses)
+- Color palette lay-flat photos: all the flowers for the day's class laid on a white or wood surface before arrangement
+- Finished arrangement photography: natural light, clean background, slightly imperfect (real, not stock-looking)
+- Hands arranging: mid-process shots with hands in frame
+- Before/after: loose stems laid out vs. finished bouquet
+- Studio wide shots: the studio filled with flowers before class starts
+- "Market haul" flat-lays: what arrived from the market this week
+
+**Caption length:** 80–150 words for primary posts. 1–2 sentences for secondary posts (shared reposts, casual updates).
+
+**Caption structure:**
+1. Opening line that names or describes the flower(s) — make it sensory
+2. 2–3 sentences of context (season, class, why it matters)
+3. CTA if promotional, otherwise just a question or observation to invite engagement
+4. Hashtags (on same post or first comment — either is fine)
+
+**Carousel format:** For educational posts, use carousel slides. 4–6 slides, each with one point. Simple, clean design.
+
+---
+
+### TikTok
+
+Florals perform exceptionally well on TikTok when the visual is satisfying and the format is honest. The following formats drive the most organic reach:
+
+**High-performing formats:**
+- **Arrangement time-lapse:** From loose stems to finished arrangement, sped up 10–15×. Add ambient studio audio or trending sound. No talking needed.
+- **Stem-cutting ASMR:** Close-up of stems being cut at 45° under water, foliage being stripped, the satisfying sounds of preparation. 30–60 seconds.
+- **"Watch this bouquet come together":** Real-time or slightly sped-up hand-tied arrangement being built, with voiceover explaining each layer. Greenery first → focal flowers → secondary → filler.
+- **Flower ID series:** "Can you name all five flowers in this arrangement?" — quick-fire visual test. Educational, sharable.
+- **Before and after:** Side-by-side or transition from the market flat-lay to the finished class arrangement.
+- **Color palette reveal:** Start with an empty table, place each flower color in sequence, end on the full palette together. Trending audio.
+- **"What $55 gets you at our floral studio":** Show exactly what a Seasonal Bouquet Class looks like from arrival to walk-out.
+- **Florist reacts to [trend]:** Comment on a viral flower post with genuine expertise — what they did right, what you'd change.
+
+**TikTok caption:** Short (max 150 characters), with 2–3 relevant hashtags. Let the video speak.
+
+**TikTok posting cadence:** 3–4 times per week for best reach. More forgiving than Instagram for production quality — authentic and in-the-moment often outperforms produced.
+
+---
+
+## Hashtag Bank
+
+Use 5–8 per Instagram post. Mix high-volume and niche:
+
+**Studio-specific:**
+`#{{instagram}}` `#petalandpress`
+
+**High-volume florals:**
+`#floraldesign` `#florals` `#bouquet` `#flowers` `#flowerarrangement` `#florist` `#flowerlovers`
+
+**Class-specific:**
+`#floralclass` `#flowerclass` `#bouquetclass` `#floralworkshop` `#diyflowers`
+
+**Location:**
+`#{{city}}flowers` `#{{city}}florist` `#{{city}}events` (adapt to actual city)
+
+**Seasonal:**
+`#seasonalblooms` `#springflowers` `#summerflowers` `#dahlias` `#peonies` `#ranunculus` (swap by season)
+
+**Lifestyle:**
+`#botanicalliving` `#bloomsday` `#handtiedbouquet` `#freshflowers` `#flowermarket`
+
+**Do not use:** `#luxury`, `#premium`, `#exclusive` — these signal inaccessibility and contradict the studio's welcoming ethos.
+
+---
+
+## Monthly Calendar Output Format
+
+Generate 28 posts (7 per week × 4 weeks). For each post:
+
+```
+Day [N] — [Platform: IG / TT / Both]
+Pillar: [Fresh Flower Beauty / In-Class / Educational / Seasonal / Promotional]
+Visual direction: [Specific description of what to photograph or film]
+Caption:
+[Full caption text including line breaks as you'd post them]
+
+Hashtags: [hashtag list]
+TikTok note: [format suggestion if different from IG]
+```
+
+---
+
+## Sample Posts by Pillar
+
+### Fresh Flower Beauty (Instagram)
+
+```
+Visual: Close-up of a peony fully open, petals backlit by window light. Studio background.
+
+Caption:
+The moment just before a peony fully opens is the one.
+
+All that potential. All that softness. And it only gets better for the next four days.
+
+This week's Bouquet Class is built around garden roses and peonies in a soft & romantic palette — blush, dusty rose, and creamy ivory.
+
+A few spots remain for Saturday morning.
+
+#seasonalblooms #peonyseason #handtiedbouquet #floraldesign #{{city}}flowers #freshflowers #botanicalliving
+```
+
+---
+
+### In-Class (Instagram)
+
+```
+Visual: Overhead shot of a finished hand-tied bouquet laid on a kraft paper sheet, about to be wrapped.
+
+Caption:
+She'd never arranged flowers before Thursday.
+
+This was 90 minutes into her first Seasonal Bouquet Class. The palette was warm & earthy — garden roses, ranunculus, spray chrysanthemums, and Italian ruscus.
+
+She did that.
+
+Beginner classes run weekends and Thursday evenings. Link to book in bio.
+
+#floralclass #handtiedbouquet #floralworkshop #{{city}} #freshflowers #flowerclass
+```
+
+---
+
+### Educational (Instagram Carousel)
+
+```
+Slide 1: "Why greenery goes in first."
+Slide 2: "It's not decoration — it's the skeleton. Everything else hangs on this structure."
+Slide 3: "Start with the longest, most structural stems. Italian ruscus, olive, eucalyptus."
+Slide 4: "Build outward. You're creating a framework your focal flowers can rest against."
+Slide 5: "Once the greenery is in, the hard part is done."
+Slide 6: "Come learn it in person. → Link in bio"
+
+Caption:
+The one tip that instantly makes amateur arrangements look more professional.
+#floraldesign #floristips #learnflorals #flowerarrangement #{{city}}florist
+```
+
+---
+
+### TikTok (Arrangement Time-Lapse)
+
+```
+Visual: 15-second time-lapse of a hand-tied bouquet being built from scratch. No talking. Studio audio (ambient sounds + scissors).
+Text on screen: "watch this bouquet come together 🌸"
+Caption: From 20 loose stems to this. Seasonal Bouquet Class at {{businessName}}.
+Hashtags: #floraldesign #bouquet #timelapse #flowers #{{city}}
+```
+
+---
+
+## Seasonal Content Signals by Month
+
+Layer these into the monthly calendar based on current month:
+
+| Month | Featured Flowers | Seasonal Beat |
+|---|---|---|
+| January | Ranunculus, anemones, hellebores | "January is secretly a great flower month" |
+| February | Ranunculus, tulips, roses | Valentine's — Date Night class push |
+| March | Tulips, daffodils, cherry blossoms | Spring is coming |
+| April | Peonies (early), sweet peas | First peonies of the year |
+| May | Peonies (peak), lilacs | Peak season — Mother's Day |
+| June | Garden roses, larkspur, lisianthus | Rose season |
+| July | Dahlias (early), sunflowers, zinnias | Summer abundance |
+| August | Dahlias, sunflowers | Dahlia season begins in earnest |
+| September | Dahlias (peak), chrysanthemums | Best dahlia content of the year |
+| October | Late dahlias, dried grasses, rosehips | Fall texture |
+| November | Chrysanthemums, dried elements | Wreath season begins |
+| December | Amaryllis, evergreens, paperwhites | Holiday wreath and centerpiece push |

package/kits/petal-press/skills/staff-briefing/SKILL.md

@@ -0,0 +1,217 @@
+---
+id: staff-briefing
+name: Morning Staff Briefing
+description: Generates a structured morning operations briefing for the opening shift — covering today's class schedule, color palettes booked, fresh flower order status, station setup requirements, and an opening checklist tailored to the floral 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 floral 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 with Session Attributes
+
+```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
+// Bookings linked to each slot carry sessionAttributes: arrangementStyle, colorPalette, flowerTypes, partyTheme
+```
+
+### 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)
+// Apply heightened urgency to fresh-flowers and greenery categories
+```
+
+## 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]
+Designer on duty: [name if available from staff schedule]
+```
+
+### 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., Seasonal Bouquet Class)
+- **Guests** (reservedCount / capacity — show fill percentage)
+- **Arrangement style** + **Color palette** from session attributes (these tell you what to set up)
+- **Booking numbers** for reference
+
+Flag fully booked slots as **SOLD OUT**. Flag slots at 80%+ capacity as **NEARLY FULL**.
+
+For private party bookings, add: "⭐ FULL STUDIO BUYOUT — confirm guest count and custom palette. Review partyTheme note if present."
+
+For Date Night Florals, add: "Confirm two coordinating vessel/wrapping sets are prepared."
+
+**Example slot entry:**
+
+```
+10:00 AM — Seasonal Bouquet Class
+Guests: 8 / 12 (67%) | NEARLY FULL
+Style: hand-tied | Palette: soft & romantic
+Flowers: garden roses, ranunculus, sweet peas, eucalyptus (set by instructor)
+Bookings: PP-0510-A through PP-0510-H
+```
+
+### 3. Flower Order Check
+
+This is the most operationally critical section for a floral studio.
+
+```
+Flower Order Status
+─────────────────────────────────────
+Today's delivery:    [ ] Received   [ ] Not yet received
+Greenery status:     [ ] Conditioned and ready
+Substitutions needed: [list any flower types that weren't available and what was substituted]
+```
+
+If flowers haven't arrived by the time the briefing is generated (morning of class day), flag with: **⚠️ DELIVERY NOT CONFIRMED — call supplier immediately if past expected arrival window.**
+
+Include a reminder: "Condition all fresh flowers as soon as delivery arrives: cut stems at 45° under water, strip foliage below the waterline, place in room-temperature water with flower food."
+
+### 4. Station Setup
+
+Based on today's class types and guest counts:
+
+```
+Station Setup
+─────────────────────────────────────
+Total stations needed: [guest count across all classes]
+Vessel type(s): [derived from arrangementStyle session attribute]
+  - Bouquet classes: no vessel — prepare wrapping station, ribbon, kraft paper
+  - Centerpiece classes: [vessel type from vesselType session attribute] — confirm count vs guest count
+  - Wreath classes: [wreathBase from wreathBase session attribute] — confirm count
+Mechanics:
+  - Stem cutters at each station: [count]
+  - Floral tape: [by class type]
+  - Wire: [for wreath classes]
+  - Foam: [for centerpiece classes using foam mechanics]
+```
+
+If multiple class types run today, list setup requirements for each session separately.
+
+### 5. Inventory Alerts
+
+If any items have `quantity < reorderThreshold`:
+
+| Item | Category | In Stock | Reorder Point | Status |
+|---|---|---|---|---|
+| Garden Roses (stems) | fresh-flowers | 24 stems | 30 stems | ORDER NOW |
+
+**Fresh flower and greenery alert rules (tighter than standard):**
+- `fresh-flowers` category: 🔴 CRITICAL if any class in the next 3 days doesn't have a confirmed flower order
+- `greenery` category: 🔴 CRITICAL if less than 1 session's worth remains on-hand
+- `mechanics` category: 🔴 CRITICAL if less than 2 sessions' worth of foam, wire, or tape remains
+- `ribbon` category: 🟡 LOW if less than 3 sessions' worth remains
+- `vessels` category: cross-reference today's centerpiece session requirements vs on-hand count
+
+If no items need attention: "All supplies are well-stocked. No action needed."
+
+### 6. Action Items
+
+Always end with this checklist, customized based on the day's class schedule and alerts:
+
+```
+Opening Checklist
+[ ] Condition today's fresh flowers: cut stems, strip foliage, hydrate
+[ ] Set up [N] stations with stem cutters and protective mat
+[ ] Lay out greenery and filler first — focal flowers stay in buckets until class begins
+[ ] Confirm ribbon, kraft paper, and wrapping materials at the wrap station
+[ ] Set out arrangement vessels (for centerpiece or wreath classes)
+[ ] POS float confirmed — till ready
+[ ] Opening Instagram teaser drafted or scheduled (fresh blooms photo)
+```
+
+Add contextually:
+
+```
+[ ] ⭐ Private party arriving [time] — confirm station layout, welcome card if requested, custom palette flowers staged
+```
+```
+[ ] 💑 Date Night Florals at [time] — prepare two matching wrapping sets, coordinating ribbon
+```
+```
+[ ] ⚠️ Low supply alert — pull backup stock or place order before first class
+```
+```
+[ ] 🌸 CRITICAL: Flower delivery not confirmed — contact supplier immediately
+```
+
+## Tone
+
+Warm, practical, and energizing. The opening team should feel prepared and confident, not overwhelmed. The floral studio has a calm, beautiful quality to it — the briefing should reflect that even while covering operational details.
+
+Avoid long paragraphs. Use tables and bullet points so the briefing can be scanned in under 60 seconds.
+
+The most important operational fact to communicate every morning: the flowers are perishable, the guest count is known, and everything needs to be ready before the first guest walks in. Once class begins, setup time is gone.

package/kits/petal-press/skills/venue-data-model/SKILL.md

@@ -0,0 +1,226 @@
+---
+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 | `content-page` | CMS-managed website section | `pageSlug`, `section`, `locationId` |
+| Document | `blog-post` | Blog article | `slug`, `title`, `status` (draft/published), `tags`, `authorId`, `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` |
+
+## Relationships
+
+Graph edges connect entities using typed verbs. Use relationships to traverse the graph without duplicating data.
+
+| Relationship | Meaning |
+|---|---|
+| Location **Contains** Experience, TimeSlot, InventoryItem | What exists at a given location |
+| Booking **ParticipatesIn** TimeSlot | Which slot a reservation occupies |
+| Customer **Creates** Booking, Waiver | 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 |
+| 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, 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-05-10' },
+    { field: 'metadata.status',     value: 'confirmed'  }
+  ]
+});
+// → { total: 8 }
+
+// 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('seasonal bouquet class', {
+  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.
+
+7. **Floral studio note:** Fresh flowers are perishable inventory. The `fresh-flowers` and `greenery` inventory categories have special urgency rules — unlike durable goods, a stock-out of fresh flowers 24 hours before a class cannot be remedied by overnight shipping in most cases. Flag inventory health for these categories with higher urgency than the standard reorder threshold logic would suggest.