@soulcraft/kits 1.0.0

package/kits/paws-and-pour/skills/venue-data-model/SKILL.md

@@ -0,0 +1,260 @@
+---
+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. Includes Paws & Pour-specific notes on the Organism entity type for animal profiles.
+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 | `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` (draft/published), `tags`, `authorId`, `locationId` |
+| Document | `adoption-application` | Animal adoption form | `animalId`, `applicantEmail`, `status`, `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` |
+| Organism | `animal` | Rescue animal profile | `name`, `species` (cat/dog), `age`, `breed`, `personalities`, `adoptionStatus` (available/pending/adopted), `interactionCount`, `locationId` |
+
+### Animal Entity Notes
+
+At {{businessName}}, the `Organism` entity type is used for all resident animals — both cats and dogs. The `metadata.entityType` is `'animal'` (not `'kitten'`). Always include `metadata.species` when filtering to distinguish cats from dogs.
+
+```typescript
+// Get all available cats
+const cats = await brain.find({
+  type: 'Organism',
+  where: [
+    { field: 'metadata.entityType',    value: 'animal'    },
+    { field: 'metadata.species',       value: 'cat'       },
+    { field: 'metadata.adoptionStatus', value: 'available' },
+    { field: 'metadata.locationId',    value: LOCATION_ID }
+  ]
+});
+
+// Get all available dogs
+const dogs = await brain.find({
+  type: 'Organism',
+  where: [
+    { field: 'metadata.entityType',    value: 'animal'    },
+    { field: 'metadata.species',       value: 'dog'       },
+    { field: 'metadata.adoptionStatus', value: 'available' },
+    { field: 'metadata.locationId',    value: LOCATION_ID }
+  ]
+});
+```
+
+## Relationships
+
+Graph edges connect entities using typed verbs. Use relationships to traverse the graph without duplicating data.
+
+| Relationship | Meaning |
+|---|---|
+| Location **Contains** Experience, TimeSlot, Animal, InventoryItem | What exists at a given location |
+| Booking **ParticipatesIn** TimeSlot | Which slot a reservation occupies |
+| Customer **Creates** Booking, Waiver, AdoptionApplication | 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 |
+| AdoptionApplication **References** Animal | Which animal an application is for |
+| 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, Organism: 12, Location: 2 }
+
+// Count with filter criteria
+const todayBookings = await brain.counts.byCriteria({
+  type: 'Event',
+  criteria: [
+    { field: 'metadata.entityType', value: 'booking'   },
+    { field: 'metadata.date',       value: '2026-02-19' },
+    { field: 'metadata.status',     value: 'confirmed'  }
+  ]
+});
+// → { total: 8 }
+
+// Full graph statistics
+const stats = await brain.getStats();
+// → { entities: 980, relationships: 2100, density: 0.38, 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('friendly with kids looking for a quiet home', {
+  type:  'Organism',
+  limit: 50
+})) {
+  // 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. `$18.00 = 1800`. 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. **For animals, always include `metadata.species`** when the query is species-specific. Dogs and cats use the same `entityType: 'animal'` and the same `Organism` NounType — species is the distinguishing field.
+
+5. **Audit events are append-only.** Never update or delete a record with `metadata.entityType === 'audit-event'`.
+
+6. **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.
+
+7. **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.
+
+8. **The Adoption Meet & Greet experience has `priceInCents: 0`.** When computing revenue, exclude `metadata.experienceSlug === 'adoption-meet-greet'` from revenue totals — it is a lead generation experience, not a revenue line.

package/kits/persona-driven-strategy/kit.json

@@ -0,0 +1,352 @@
+{
+  "$schema": "https://soulcraft.com/schemas/kit/v2.json",
+  "id": "persona-driven-strategy",
+  "type": "soulcraft",
+  "role": "primary",
+  "status": "released",
+  "name": "Persona-Driven Strategy Suite",
+  "description": "Complete strategic planning with personas at the center - product, marketing, GTM, and sales plans all connected",
+  "longDescription": "A comprehensive strategy system that puts customer personas at the heart of all planning. Create detailed personas using Jobs-to-be-Done and empathy mapping, then connect them to product features, marketing campaigns, go-to-market strategy, and sales playbooks. The knowledge graph reveals how each persona flows through your entire strategy.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Soulcraft Labs",
+    "email": "kits@soulcraft.com",
+    "url": "https://soulcraft.com"
+  },
+  "icon": "🎯",
+  "tags": [
+    "personas",
+    "strategy",
+    "gtm",
+    "product",
+    "marketing",
+    "sales",
+    "planning"
+  ],
+  "variables": [
+    {
+      "key": "productName",
+      "label": "Product/Company Name",
+      "description": "The name of your product or company",
+      "type": "string",
+      "required": true,
+      "example": "Acme Analytics"
+    },
+    {
+      "key": "author",
+      "label": "Strategy Owner",
+      "description": "The person leading this strategy",
+      "type": "string",
+      "required": false,
+      "example": "Your Name"
+    },
+    {
+      "key": "market",
+      "label": "Target Market",
+      "description": "The primary market you are targeting",
+      "type": "string",
+      "required": false,
+      "example": "B2B SaaS",
+      "default": ""
+    },
+    {
+      "key": "launchDate",
+      "label": "Target Launch",
+      "description": "Planned launch or go-to-market date",
+      "type": "string",
+      "required": false,
+      "example": "Q2 2025",
+      "default": ""
+    }
+  ],
+  "shared": {
+    "industry": "business-strategy",
+    "category": "business",
+    "aiExpertise": [
+      "User persona development",
+      "Jobs-to-be-done framework",
+      "Customer journey mapping",
+      "Go-to-market strategy",
+      "Sales playbook design",
+      "Market segmentation"
+    ],
+    "dataModelHints": [
+      "person",
+      "concept",
+      "socialGroup",
+      "document"
+    ],
+    "dataModel": {
+      "entities": [
+        {
+          "domain": "persona",
+          "type": "Person",
+          "description": "A detailed customer persona with demographics, goals, and pain points",
+          "products": {
+            "workshop": {
+              "view": "gallery",
+              "icon": "🎯"
+            },
+            "academy": {
+              "mapsTo": "learning-subject",
+              "assessable": false
+            }
+          }
+        },
+        {
+          "domain": "need",
+          "type": "Concept",
+          "description": "A functional or emotional need a persona has",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "💬"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "goal",
+          "type": "Concept",
+          "description": "A desired outcome or job-to-be-done for a persona",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "🏆"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "painPoint",
+          "type": "Concept",
+          "description": "A frustration or blocker standing between a persona and their goal",
+          "products": {
+            "workshop": {
+              "view": "board",
+              "icon": "😤"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "journeyStep",
+          "type": "Concept",
+          "description": "A stage in the customer journey for a persona",
+          "products": {
+            "workshop": {
+              "view": "timeline",
+              "icon": "🗺️"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "segment",
+          "type": "Concept",
+          "description": "A market segment or audience group containing personas",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "👥"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": false
+            }
+          }
+        }
+      ],
+      "relationships": [
+        {
+          "from": "persona",
+          "to": "goal",
+          "verb": "Desires",
+          "description": "Persona wants to achieve this goal"
+        },
+        {
+          "from": "persona",
+          "to": "painPoint",
+          "verb": "Fears",
+          "description": "Persona is frustrated by this pain point"
+        },
+        {
+          "from": "persona",
+          "to": "segment",
+          "verb": "MemberOf",
+          "description": "Persona belongs to this market segment"
+        },
+        {
+          "from": "journeyStep",
+          "to": "journeyStep",
+          "verb": "Precedes",
+          "description": "Customer journey step ordering"
+        }
+      ]
+    },
+    "suggestions": [
+      {
+        "label": "Create a persona",
+        "prompt": "Help me create a new user persona with demographics and behaviors"
+      },
+      {
+        "label": "Map user journey",
+        "prompt": "Help me map out a user journey for one of my personas"
+      },
+      {
+        "label": "Identify pain points",
+        "prompt": "Help me identify and document pain points for my personas"
+      },
+      {
+        "label": "Align strategy",
+        "prompt": "Help me align my product strategy with persona needs"
+      },
+      {
+        "label": "Compare personas",
+        "prompt": "Compare my personas and highlight key differences"
+      },
+      {
+        "label": "View persona map",
+        "prompt": "Show me all my personas and their relationships in the graph"
+      }
+    ]
+  },
+  "academy": {
+    "skillPath": "strategic-thinking",
+    "level": "intermediate",
+    "learningObjectives": [
+      "Build evidence-based customer personas using Jobs-to-be-Done and empathy mapping",
+      "Trace a persona's journey from awareness to purchase and identify friction at each stage",
+      "Connect persona pain points to specific product features with a clear value narrative",
+      "Write a go-to-market positioning statement that differentiates by persona need",
+      "Align product, marketing, and sales plans around a shared persona foundation"
+    ],
+    "assessmentTypes": [
+      "portfolio",
+      "peer-review"
+    ],
+    "certificationSlug": "strategic-thinker"
+  },
+  "workshop": {
+    "difficulty": "advanced",
+    "templateTier": 4,
+    "aiPersona": {
+      "role": "You are a user research and strategy consultant helping teams create evidence-based personas and customer-centric strategies that drive GTM, product, and sales alignment.",
+      "expertise": [
+        "User persona development",
+        "Jobs-to-be-done framework",
+        "Customer journey mapping",
+        "Market segmentation",
+        "Go-to-market strategy"
+      ],
+      "tone": "collaborator"
+    },
+    "workspaceConfig": {
+      "paradigm": "planner",
+      "defaultTab": "explore",
+      "defaultView": "board",
+      "defaultFile": "personas/primary-persona.md",
+      "layout": {
+        "leftDock": "files",
+        "rightDock": "views"
+      },
+      "onboarding": {
+        "showGuide": true,
+        "highlightFeatures": [
+          "graph",
+          "board",
+          "ai-chat"
+        ],
+        "suggestedActions": [
+          "Start by defining your key personas",
+          "Document pain points and goals",
+          "Map product features to pain points",
+          "Use Graph view to see strategy connections"
+        ]
+      }
+    },
+    "graphGuidance": {
+      "conceptCreation": {
+        "triggers": [
+          "When user creates a new persona",
+          "When user identifies a user need or goal",
+          "When user describes a pain point",
+          "When user maps a journey step"
+        ],
+        "typeMapping": {
+          "persona": "person",
+          "need": "concept",
+          "goal": "concept",
+          "painPoint": "concept",
+          "journeyStep": "concept",
+          "segment": "socialGroup"
+        }
+      },
+      "relationshipPatterns": [
+        {
+          "from": "person",
+          "to": "concept",
+          "verb": "desires",
+          "description": "Persona has goal"
+        },
+        {
+          "from": "person",
+          "to": "concept",
+          "verb": "fears",
+          "description": "Persona has pain point"
+        },
+        {
+          "from": "person",
+          "to": "socialGroup",
+          "verb": "memberOf",
+          "description": "Persona in segment"
+        },
+        {
+          "from": "concept",
+          "to": "concept",
+          "verb": "precedes",
+          "description": "Journey step order"
+        }
+      ],
+      "rules": [
+        "Create person entities for each persona",
+        "Link personas to their goals and pain points",
+        "Track journey steps in sequence",
+        "Note which segments personas belong to"
+      ]
+    },
+    "exporters": [
+      {
+        "id": "strategy-bundle",
+        "name": "Complete Strategy Package",
+        "description": "All strategy documents in organized bundle",
+        "icon": "📦",
+        "format": "zip",
+        "category": "archive",
+        "handler": "markdown-bundle",
+        "options": {
+          "includeFiles": [
+            "**/*.md"
+          ],
+          "preserveStructure": true,
+          "addReadme": true
+        }
+      }
+    ],
+    "templateMetadata": {
+      "identifyByStructure": true
+    }
+  }
+}