@soulcraft/kits 1.0.0

package/kits/canvas-and-corks/skills/venue-data-model/SKILL.md

@@ -0,0 +1,325 @@
+---
+id: venue-data-model
+name: Venue Data Model
+description: Teaches the AI assistant the complete Venue platform data architecture, Brainy entity types, relationship model, and all available query APIs for building analytics and data-driven responses.
+type: background
+version: 1.0.0
+requiresVision: false
+requiresData: false
+---
+
+# Venue Data Model
+
+You are operating within the **Venue platform**, powered by **@soulcraft/brainy** — a graph-based entity store with vector search, aggregate analytics, neural clustering, and streaming APIs. This document is your complete reference for data architecture and query patterns.
+
+## Core Concepts
+
+Every piece of data is a **Brainy entity** with:
+- A `type` (the NounType — the broad category)
+- A `metadata` object (filterable, indexed fields — queryable via `where`)
+- A `data` object (full-text/vector searchable content)
+- An `id` (UUID string)
+- Relationships to other entities (directed, typed edges)
+
+**Key invariant**: Amounts are always stored in cents (integer). $55.00 = `5500`. Divide by 100 for display.
+
+**Key invariant**: Every entity scoped to a franchise location carries `metadata.locationId`. Always include this filter when querying per-location data.
+
+**Key invariant**: `Event`, `Person`, `Document`, `Measurement`, and `Thing` are the five NounTypes. Sub-entity kinds are distinguished by `metadata.entityType`. Always include the `metadata.entityType` filter when querying a specific sub-kind within a NounType.
+
+---
+
+## Entity Types Reference
+
+| NounType | `metadata.entityType` | Purpose | Key Metadata Fields |
+|---|---|---|---|
+| `Location` | `location` | Franchise studio location | `address`, `hours`, `timezone`, `stripeAccountId`, `locationId` |
+| `Product` | `experience` | Experience type / ticket offering | `slug`, `name`, `priceInCents`, `durationMinutes`, `minGuests`, `maxGuests`, `locationId` |
+| `Event` | `booking` | Guest reservation | `status`, `experienceSlug`, `guestCount`, `totalInCents`, `locationId`, `date`, `bookingNumber`, `checkedIn` |
+| `Event` | `time-slot` | Capacity block on the schedule | `date`, `hour`, `experienceSlug`, `capacity`, `reservedCount`, `locationId` |
+| `Event` | `audit-event` | Append-only operation log | `action`, `actorId`, `actorName`, `entityId`, `entityType`, `locationId` |
+| `Event` | `experience-memory` | Shareable post-visit storybook | `bookingId`, `token`, `published`, `locationId` |
+| `Person` | `customer` | Guest profile | `email`, `displayName`, `totalBookings`, `totalSpentInCents`, `loyaltyTier`, `locationId` |
+| `Person` | `staff` | Employee record | `email`, `role`, `permissions`, `locationId` |
+| `Person` | `loyalty-account` | Points and tier balance | `customerId`, `pointsBalance`, `tier`, `locationId` |
+| `Document` | `waiver` | Signed digital waiver | `bookingId`, `signerName`, `signedAt`, `locationId` |
+| `Document` | `content-page` | CMS-managed website section | `pageSlug`, `section`, `locationId` |
+| `Document` | `blog-post` | Blog article | `slug`, `title`, `status`, `tags`, `authorId`, `locationId` |
+| `Thing` | `inventory-item` | Physical supply / stock | `name`, `category`, `quantity`, `reorderThreshold`, `costInCents`, `locationId` |
+| `Thing` | `gift-card` | Digital or physical gift card | `code`, `balanceInCents`, `originalAmountInCents`, `locationId` |
+| `Measurement` | `transaction` | Revenue, expense, or refund record | `type`, `amountInCents`, `experienceSlug`, `category`, `date`, `locationId` |
+| `Measurement` | `loyalty-transaction` | Points earned, redeemed, or expired | `customerId`, `points`, `reason`, `locationId` |
+
+### Booking `status` values
+`pending` | `confirmed` | `completed` | `cancelled`
+
+### Transaction `type` values
+`revenue` | `expense` | `refund`
+
+---
+
+## Relationships Reference
+
+Brainy relationships are directed edges with a typed verb. Query via `brain.related()` or use `brain.find()` with relationship traversal.
+
+| From Entity | Verb | To Entity | Purpose |
+|---|---|---|---|
+| `Location` | Contains | `Experience`, `TimeSlot`, `Kitten` | What a location offers |
+| `Experience` | OccursAt | `TimeSlot` | Schedule mapping |
+| `Booking` | ParticipatesIn | `TimeSlot` | Seat reservation |
+| `Customer` | Creates | `Booking`, `Waiver` | Ownership |
+| `Booking` | Contains | `Experience` | Line items |
+| `Waiver` | References | `Booking` | Waiver-to-booking link |
+| `Transaction` | References | `Booking` | Revenue attribution |
+| `Experience` | Consumes | `InventoryItem` | COGS / supply tracking |
+| `Location` | Owns | `Transaction` | Multi-location P&L |
+| `Staff` | MemberOf | `Location` | Staff assignment |
+| `Memory` | References | `Booking` | Visit → memory link |
+
+---
+
+## Aggregate API
+
+Use `brain.defineAggregate()` to register a named aggregate, then `brain.find()` with the `aggregate` key to query it. Results are materialized and cached.
+
+### Full example — revenue by experience and month
+
+```typescript
+brain.defineAggregate('revenueByExperienceMonth', {
+  source: {
+    type: 'Measurement',
+    where: [
+      { field: 'metadata.entityType', value: 'transaction' },
+      { field: 'metadata.type', value: 'revenue' }
+    ]
+  },
+  groupBy: [
+    { field: 'metadata.experienceSlug' },
+    { field: 'metadata.date', window: 'month' }
+  ],
+  metrics: {
+    totalRevenue:    { op: 'SUM',      field: 'metadata.amountInCents' },
+    bookingCount:    { op: 'COUNT' },
+    avgTicket:       { op: 'AVG',      field: 'metadata.amountInCents' },
+    revenueStdDev:   { op: 'STDDEV',   field: 'metadata.amountInCents' },
+    maxTicket:       { op: 'MAX',      field: 'metadata.amountInCents' },
+    minTicket:       { op: 'MIN',      field: 'metadata.amountInCents' },
+    revenueVariance: { op: 'VARIANCE', field: 'metadata.amountInCents' }
+  }
+});
+
+const results = await brain.find({
+  aggregate: 'revenueByExperienceMonth',
+  where: [{ field: 'metadata.locationId', value: 'loc-abc' }],
+  orderBy: 'totalRevenue',
+  order: 'desc',
+  limit: 100
+});
+```
+
+### Available aggregation operators
+
+| Operator | Description |
+|---|---|
+| `SUM` | Total of all values in the group |
+| `COUNT` | Number of entities in the group |
+| `AVG` | Arithmetic mean |
+| `MIN` | Minimum value |
+| `MAX` | Maximum value |
+| `STDDEV` | Population standard deviation |
+| `VARIANCE` | Population variance |
+
+### Available time windows for `groupBy`
+
+`hour` | `day` | `week` | `month` | `quarter` | `year`
+
+### Example — expenses by category and month
+
+```typescript
+brain.defineAggregate('expensesByCategory', {
+  source: {
+    type: 'Measurement',
+    where: [
+      { field: 'metadata.entityType', value: 'transaction' },
+      { field: 'metadata.type', value: 'expense' }
+    ]
+  },
+  groupBy: [
+    { field: 'metadata.category' },
+    { field: 'metadata.date', window: 'month' }
+  ],
+  metrics: {
+    totalExpense: { op: 'SUM',   field: 'metadata.amountInCents' },
+    entryCount:   { op: 'COUNT' },
+    avgExpense:   { op: 'AVG',   field: 'metadata.amountInCents' }
+  }
+});
+```
+
+### Example — bookings by experience and day of week
+
+```typescript
+brain.defineAggregate('bookingsByExperienceDayHour', {
+  source: {
+    type: 'Event',
+    where: [
+      { field: 'metadata.entityType', value: 'booking' },
+      { field: 'metadata.status', value: 'confirmed' }
+    ]
+  },
+  groupBy: [
+    { field: 'metadata.experienceSlug' },
+    { field: 'metadata.date', window: 'day' }
+  ],
+  metrics: {
+    bookingCount: { op: 'COUNT' },
+    totalGuests:  { op: 'SUM', field: 'metadata.guestCount' },
+    avgGuests:    { op: 'AVG', field: 'metadata.guestCount' }
+  }
+});
+```
+
+---
+
+## Counts API
+
+For fast total counts without full aggregation:
+
+```typescript
+// Count all entities by NounType
+const totals = await brain.counts.byType();
+// Returns: { Location: 3, Product: 8, Event: 1240, Person: 892, ... }
+
+// Count with specific criteria
+const todayBookings = await brain.counts.byCriteria({
+  type: 'Event',
+  criteria: [
+    { field: 'metadata.entityType', value: 'booking' },
+    { field: 'metadata.date',       value: '2026-02-19' }
+  ]
+});
+// Returns: { count: 14 }
+
+// Global database statistics
+const stats = await brain.getStats();
+// Returns: { totalEntities, totalRelationships, indexedAt, storeSizeBytes, ... }
+```
+
+---
+
+## Neural API
+
+Brainy exposes ML-style operations over entity embeddings without an external model:
+
+```typescript
+// Cluster customers into behavioral segments
+const segments = await brain.neural().clusters({
+  numClusters: 5,
+  entityType: 'Person'
+});
+// Returns array of clusters, each with centroid, memberIds[], and summary stats
+
+// Detect statistical outliers (VIPs, anomalies, churn risks)
+const outliers = await brain.neural().outliers({
+  threshold: 2.5,     // Z-score threshold
+  method: 'zscore',   // 'zscore' | 'iqr'
+  entityType: 'Measurement'
+});
+
+// Find semantically similar entities
+const similar = await brain.neural().similar('entity-id-uuid', {
+  limit: 10
+});
+// Returns entities with similarity scores, ordered descending
+```
+
+---
+
+## Streaming API
+
+For large result sets or real-time feeds, use async generators:
+
+```typescript
+// Stream all entities of a NounType
+for await (const entity of brain.streaming.entities({ type: 'Event' })) {
+  // Process one entity at a time — memory-efficient for large sets
+}
+
+// Stream search results
+for await (const result of brain.streaming.search('mountain sunset', { type: 'Event' })) {
+  // result.entity, result.score
+}
+```
+
+---
+
+## Tabular Export API
+
+Export entity data as CSV or OData for spreadsheet and BI tool consumption:
+
+```typescript
+import { TabularExporter } from '@soulcraft/brainy';
+
+const exporter = new TabularExporter(brain);
+
+// Export to CSV buffer
+const csv = await exporter.exportCsv({
+  type: 'Measurement',
+  where: [{ field: 'metadata.entityType', value: 'transaction' }]
+});
+
+// Export as OData JSON (compatible with Power BI, Excel)
+const odata = await exporter.exportOData({
+  type: 'Measurement',
+  where: [{ field: 'metadata.entityType', value: 'transaction' }]
+});
+```
+
+---
+
+## Standard Query Patterns
+
+### Find all bookings for a location on a date
+```typescript
+await brain.find({
+  type: 'Event',
+  where: [
+    { field: 'metadata.entityType', value: 'booking' },
+    { field: 'metadata.locationId', value: locationId },
+    { field: 'metadata.date',       value: '2026-02-19' }
+  ],
+  orderBy: 'metadata.hour',
+  order: 'asc'
+});
+```
+
+### Find inventory items below reorder threshold
+```typescript
+await brain.find({
+  type: 'Thing',
+  where: [
+    { field: 'metadata.entityType', value: 'inventory-item' },
+    { field: 'metadata.locationId', value: locationId }
+  ]
+  // Filter client-side: items where quantity <= reorderThreshold
+});
+```
+
+### Full-text + vector search
+```typescript
+await brain.search('mountain sunset acrylic warm tones', {
+  type: 'Event',
+  limit: 20
+});
+```
+
+---
+
+## Rules Summary
+
+1. **Amounts in cents** — `5500` = $55.00. Always divide by 100 before displaying.
+2. **Always filter `metadata.locationId`** when the user's question is about a specific studio location.
+3. **Always include `metadata.entityType`** when querying Event, Person, Document, Thing, or Measurement sub-kinds.
+4. **Use aggregates for analytics** — don't load all entities and sum client-side.
+5. **Use `brain.neural().clusters()`** for customer segmentation, never hard-code segments.
+6. **Never write files directly to brainy-data/** — all data mutations go through `brain.add()`, `brain.update()`, `brain.relate()`.

package/kits/character-relationship-map/kit.json

@@ -0,0 +1,367 @@
+{
+  "$schema": "https://soulcraft.com/schemas/kit/v2.json",
+  "id": "character-relationship-map",
+  "type": "soulcraft",
+  "role": "primary",
+  "status": "released",
+  "name": "Character Relationship Map",
+  "description": "Visual map of character relationships for fiction writing",
+  "longDescription": "Create an interactive character relationship map for your story. Shows connections, conflicts, alliances, and dynamics between characters. Perfect for novelists, screenwriters, or tabletop RPG worldbuilding.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Soulcraft Labs",
+    "email": "kits@soulcraft.com",
+    "url": "https://soulcraft.com"
+  },
+  "icon": "🎭",
+  "tags": [
+    "characters",
+    "fiction",
+    "relationships",
+    "storytelling"
+  ],
+  "variables": [
+    {
+      "key": "storyTitle",
+      "label": "Story Title",
+      "description": "The title of your story or world",
+      "type": "string",
+      "required": true,
+      "example": "My Novel"
+    },
+    {
+      "key": "genre",
+      "label": "Genre",
+      "description": "The genre of your story",
+      "type": "string",
+      "required": false,
+      "example": "Fantasy"
+    }
+  ],
+  "shared": {
+    "industry": "creative-writing",
+    "category": "creative",
+    "glossary": {
+      "protagonist": "The main character driving the story forward",
+      "antagonist": "The opposing force creating conflict for the protagonist",
+      "faction": "A group of characters with shared allegiances or goals"
+    },
+    "aiExpertise": [
+      "Character development and psychology",
+      "Relationship dynamics and conflict",
+      "Story structure and narrative arcs",
+      "Worldbuilding and faction design",
+      "Character voice and motivation"
+    ],
+    "dataModelHints": [
+      "person",
+      "thing",
+      "event",
+      "topic"
+    ],
+    "dataModel": {
+      "entities": [
+        {
+          "domain": "character",
+          "type": "Person",
+          "description": "A named character with role, backstory, and motivation",
+          "products": {
+            "workshop": {
+              "view": "gallery",
+              "icon": "🧑"
+            },
+            "academy": {
+              "mapsTo": "learning-subject",
+              "assessable": false
+            }
+          }
+        },
+        {
+          "domain": "faction",
+          "type": "Concept",
+          "description": "A group or organization with shared allegiances and goals",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "⚔️"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "group",
+          "type": "Concept",
+          "description": "A social group characters belong to",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "👥"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": false
+            }
+          }
+        },
+        {
+          "domain": "place",
+          "type": "Location",
+          "description": "A significant location associated with characters",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "📍"
+            }
+          }
+        }
+      ],
+      "relationships": [
+        {
+          "from": "character",
+          "to": "character",
+          "verb": "Conflicts",
+          "description": "Characters are in opposition or rivalry"
+        },
+        {
+          "from": "character",
+          "to": "character",
+          "verb": "FriendOf",
+          "description": "Allied or friendly relationship"
+        },
+        {
+          "from": "character",
+          "to": "character",
+          "verb": "Mentors",
+          "description": "Teacher or guide relationship"
+        },
+        {
+          "from": "character",
+          "to": "character",
+          "verb": "RelatedTo",
+          "description": "Family or romantic connection"
+        },
+        {
+          "from": "character",
+          "to": "faction",
+          "verb": "MemberOf",
+          "description": "Character belongs to this group or faction"
+        },
+        {
+          "from": "character",
+          "to": "place",
+          "verb": "LocatedAt",
+          "description": "Character's home or base location"
+        }
+      ]
+    },
+    "suggestions": [
+      {
+        "label": "Add a character",
+        "prompt": "Help me create a new character with their background and traits"
+      },
+      {
+        "label": "Define a relationship",
+        "prompt": "Help me define the relationship between two characters"
+      },
+      {
+        "label": "Develop backstory",
+        "prompt": "Help me develop a deeper backstory for one of my characters"
+      },
+      {
+        "label": "Find conflicts",
+        "prompt": "Analyze my character relationships and suggest potential conflicts or tensions"
+      },
+      {
+        "label": "Character arc planning",
+        "prompt": "Help me plan a character arc for one of my characters"
+      },
+      {
+        "label": "Explore relationships",
+        "prompt": "Show me all character relationships in the graph view"
+      }
+    ]
+  },
+  "academy": {
+    "skillPath": "creative-writing",
+    "level": "beginner",
+    "learningObjectives": [
+      "Build character profiles with distinct motivation, want vs. need, and internal contradiction",
+      "Map relationship dynamics using named relationship types (mentor, rival, ally, foil)",
+      "Identify how character relationships create or resolve narrative conflict",
+      "Trace a character arc from start state to end state through key story events"
+    ],
+    "assessmentTypes": [
+      "portfolio"
+    ],
+    "certificationSlug": "character-designer"
+  },
+  "workshop": {
+    "difficulty": "beginner",
+    "templateTier": 4,
+    "aiPersona": {
+      "role": "You are an expert narrative designer and fiction writing coach helping writers create vivid, interconnected characters with compelling relationship dynamics.",
+      "expertise": [
+        "Character psychology and motivation",
+        "Relationship dynamics and conflict arcs",
+        "Faction and group dynamics",
+        "Backstory and world history",
+        "Character voice and consistency"
+      ],
+      "tone": "collaborator"
+    },
+    "workspaceConfig": {
+      "paradigm": "creative",
+      "defaultTab": "explore",
+      "defaultView": "graph",
+      "defaultFile": "characters/protagonist.md",
+      "layout": {
+        "leftDock": "concepts",
+        "rightDock": "views"
+      },
+      "onboarding": {
+        "showGuide": true,
+        "highlightFeatures": [
+          "graph",
+          "ai-chat"
+        ],
+        "suggestedActions": [
+          "Create your main characters first",
+          "Define relationships between characters",
+          "Use Graph view to visualize the network",
+          "Ask AI to suggest relationship dynamics"
+        ]
+      }
+    },
+    "graphGuidance": {
+      "conceptCreation": {
+        "triggers": [
+          "When user introduces a new character by name",
+          "When user describes a group or faction",
+          "When user mentions a significant location",
+          "When user describes an organization"
+        ],
+        "typeMapping": {
+          "character": "person",
+          "faction": "organization",
+          "group": "socialGroup",
+          "place": "location",
+          "family": "socialGroup"
+        }
+      },
+      "relationshipPatterns": [
+        {
+          "from": "person",
+          "to": "person",
+          "verb": "conflicts",
+          "description": "Characters in opposition or rivalry"
+        },
+        {
+          "from": "person",
+          "to": "person",
+          "verb": "friendOf",
+          "description": "Allied or friendly characters"
+        },
+        {
+          "from": "person",
+          "to": "person",
+          "verb": "mentors",
+          "description": "Teacher/student or guide relationship"
+        },
+        {
+          "from": "person",
+          "to": "person",
+          "verb": "relatedTo",
+          "description": "Family or romantic connection"
+        },
+        {
+          "from": "person",
+          "to": "person",
+          "verb": "opposes",
+          "description": "Direct opposition or antagonism"
+        },
+        {
+          "from": "person",
+          "to": "organization",
+          "verb": "memberOf",
+          "description": "Character belongs to a group"
+        },
+        {
+          "from": "person",
+          "to": "location",
+          "verb": "locatedAt",
+          "description": "Character's home or base"
+        }
+      ],
+      "rules": [
+        "Create person entities for named characters",
+        "Link characters when relationships are mentioned",
+        "Track faction allegiances with memberOf relationships",
+        "Use conflicts verb for antagonistic relationships",
+        "Use relatedTo for family and romantic bonds"
+      ]
+    },
+    "sampleData": {
+      "description": "Sample character relationship map for a fantasy novel",
+      "entities": [
+        {
+          "type": "person",
+          "name": "Elena Stormbringer",
+          "properties": {
+            "role": "protagonist",
+            "age": 24,
+            "description": "A reluctant hero with hidden magical abilities. Grew up as an orphan in the coastal village of Saltmere.",
+            "status": "main",
+            "createdAt": "2025-01-05"
+          }
+        },
+        {
+          "type": "person",
+          "name": "Lord Varen Blackthorn",
+          "properties": {
+            "role": "antagonist",
+            "age": 45,
+            "description": "The power-hungry sorcerer seeking to control the realm's magic. Once a respected mage.",
+            "status": "main",
+            "createdAt": "2025-01-05"
+          }
+        },
+        {
+          "type": "person",
+          "name": "Kira Sunweaver",
+          "properties": {
+            "role": "mentor",
+            "age": 68,
+            "description": "Wise elder mage who recognizes Elena's potential. Carries secrets about her past.",
+            "status": "main",
+            "createdAt": "2025-01-06"
+          }
+        }
+      ],
+      "relationships": [
+        {
+          "from": "Elena Stormbringer",
+          "verb": "conflicts",
+          "to": "Lord Varen Blackthorn"
+        },
+        {
+          "from": "Kira Sunweaver",
+          "verb": "mentors",
+          "to": "Elena Stormbringer"
+        }
+      ]
+    },
+    "deploy": {
+      "provider": "cloud-run",
+      "buildCommand": "npm run build",
+      "outputDir": "build",
+      "config": {
+        "port": 3000,
+        "memory": "512Mi"
+      },
+      "oneClickCommand": "gcloud run deploy"
+    }
+  }
+}