@soulcraft/kits 1.0.0

package/kits/clay-and-co/skills/venue-data-model/SKILL.md

@@ -0,0 +1,230 @@
+---
+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 | `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 | `kittenId`, `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 | `kitten` | Foster animal profile | `name`, `age`, `breed`, `personalities`, `adoptionStatus`, `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, 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 |
+| Booking **References** Booking | Glaze & Fire session linked back to original making 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, Organism: 28, 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-02-19' },
+    { field: 'metadata.status',     value: 'confirmed'  }
+  ]
+});
+// → { total: 14 }
+
+// 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('wheel throwing pottery 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. **Pottery is a multi-session process.** A booking for a wheel throwing or handbuilding class is not the end of the customer journey — it triggers a piece-tracking lifecycle. Glaze & Fire bookings are linked to original making bookings via `References` relationships. When querying revenue or customer lifetime value, account for this: a customer who made one pot and returned for two glaze sessions has three bookings but one piece journey.

package/kits/concept-map/kit.json

@@ -0,0 +1,353 @@
+{
+  "$schema": "https://soulcraft.com/schemas/kit/v2.json",
+  "id": "concept-map",
+  "type": "soulcraft",
+  "role": "primary",
+  "status": "released",
+  "name": "Concept Map / Learning Path",
+  "description": "Educational concept map showing topic relationships and prerequisites",
+  "longDescription": "Create an interactive concept map for learning a new subject or organizing knowledge. Shows prerequisite relationships, related concepts, and learning progression. Perfect for students, teachers, or self-directed learning.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Soulcraft Labs",
+    "email": "kits@soulcraft.com",
+    "url": "https://soulcraft.com"
+  },
+  "icon": "🎓",
+  "tags": [
+    "learning",
+    "education",
+    "concepts",
+    "study"
+  ],
+  "variables": [
+    {
+      "key": "subject",
+      "label": "Subject",
+      "description": "The topic or subject you are mapping",
+      "type": "string",
+      "required": true,
+      "example": "Machine Learning"
+    },
+    {
+      "key": "skillLevel",
+      "label": "Skill Level",
+      "description": "Your current level with this subject",
+      "type": "string",
+      "required": false,
+      "example": "Beginner"
+    }
+  ],
+  "shared": {
+    "industry": "education",
+    "category": "knowledge",
+    "glossary": {},
+    "aiExpertise": [
+      "Concept mapping and knowledge organization",
+      "Learning path design",
+      "Prerequisite analysis",
+      "Educational content development",
+      "Curriculum design"
+    ],
+    "dataModelHints": [
+      "topic",
+      "thing",
+      "document"
+    ],
+    "dataModel": {
+      "entities": [
+        {
+          "domain": "concept",
+          "type": "Concept",
+          "description": "A discrete idea or topic node in the knowledge map",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "💡"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "example",
+          "type": "Thing",
+          "description": "A concrete instance or illustration of a concept",
+          "products": {
+            "workshop": {
+              "view": "gallery",
+              "icon": "📦"
+            },
+            "academy": {
+              "mapsTo": "resource",
+              "assessable": false
+            }
+          }
+        },
+        {
+          "domain": "domain",
+          "type": "Concept",
+          "description": "A broad subject area grouping related concepts",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "🗂️"
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": false
+            }
+          }
+        }
+      ],
+      "relationships": [
+        {
+          "from": "concept",
+          "to": "concept",
+          "verb": "RelatedTo",
+          "description": "General associative relationship between concepts"
+        },
+        {
+          "from": "concept",
+          "to": "concept",
+          "verb": "Contains",
+          "description": "Concept includes or subsumes another concept"
+        },
+        {
+          "from": "concept",
+          "to": "concept",
+          "verb": "Causes",
+          "description": "Causal relationship from one concept to another"
+        },
+        {
+          "from": "concept",
+          "to": "example",
+          "verb": "InstanceOf",
+          "description": "Concrete example of this concept"
+        }
+      ]
+    },
+    "suggestions": [
+      {
+        "label": "Add a concept",
+        "prompt": "Help me add a new concept to my concept map"
+      },
+      {
+        "label": "Connect concepts",
+        "prompt": "Help me identify and create connections between my concepts"
+      },
+      {
+        "label": "Explain a concept",
+        "prompt": "Help me write a clear explanation for one of my concepts"
+      },
+      {
+        "label": "Find patterns",
+        "prompt": "Analyze my concept map and identify patterns or clusters"
+      },
+      {
+        "label": "Expand a topic",
+        "prompt": "Help me break down a concept into sub-concepts"
+      },
+      {
+        "label": "View the mind map",
+        "prompt": "Show me my concepts in the mind map view"
+      }
+    ]
+  },
+  "academy": {
+    "skillPath": "knowledge-mapping",
+    "level": "beginner",
+    "learningObjectives": [
+      "Decompose a complex subject into discrete, well-scoped concept nodes",
+      "Label relationships between concepts with precise linking phrases (causes, requires, extends)",
+      "Identify prerequisite chains and sequence learning from foundational to advanced topics",
+      "Spot gaps and cross-links in a knowledge map by reviewing graph structure"
+    ],
+    "assessmentTypes": [
+      "portfolio",
+      "peer-review"
+    ],
+    "certificationSlug": "knowledge-mapper"
+  },
+  "workshop": {
+    "difficulty": "beginner",
+    "templateTier": 4,
+    "aiPersona": {
+      "role": "You are an expert educator and learning designer helping learners map out complex subjects and build structured learning paths.",
+      "expertise": [
+        "Concept mapping methodology",
+        "Learning path design",
+        "Prerequisite chain analysis",
+        "Knowledge organization",
+        "Educational scaffolding"
+      ],
+      "tone": "mentor"
+    },
+    "workspaceConfig": {
+      "paradigm": "researcher",
+      "defaultTab": "explore",
+      "defaultView": "mindmap",
+      "defaultFile": "topics/overview.md",
+      "layout": {
+        "leftDock": "concepts",
+        "rightDock": "views"
+      },
+      "onboarding": {
+        "showGuide": true,
+        "highlightFeatures": [
+          "graph",
+          "ai-chat"
+        ],
+        "suggestedActions": [
+          "Start with the central concept",
+          "Add related topics as branches",
+          "Define prerequisite relationships",
+          "Use Graph view to see the learning path"
+        ]
+      }
+    },
+    "graphGuidance": {
+      "conceptCreation": {
+        "triggers": [
+          "When user identifies a new concept",
+          "When user describes a relationship",
+          "When user adds an example",
+          "When user creates a cross-link"
+        ],
+        "typeMapping": {
+          "concept": "concept",
+          "example": "thing",
+          "domain": "concept"
+        }
+      },
+      "relationshipPatterns": [
+        {
+          "from": "concept",
+          "to": "concept",
+          "verb": "relatedTo",
+          "description": "General relationship"
+        },
+        {
+          "from": "concept",
+          "to": "concept",
+          "verb": "contains",
+          "description": "Concept includes another"
+        },
+        {
+          "from": "concept",
+          "to": "concept",
+          "verb": "causes",
+          "description": "Causal relationship"
+        },
+        {
+          "from": "concept",
+          "to": "thing",
+          "verb": "instanceOf",
+          "description": "Example of concept"
+        }
+      ],
+      "rules": [
+        "Create concept entities with clear labels",
+        "Label all relationships with linking phrases",
+        "Track hierarchy levels",
+        "Note cross-links between domains"
+      ]
+    },
+    "qualityGates": {
+      "fileChecks": [
+        {
+          "path": "README.md",
+          "required": [
+            "Learning Path"
+          ],
+          "optional": [
+            "Focus Question",
+            "Prerequisites"
+          ]
+        },
+        {
+          "path": "topics/*.md",
+          "required": [
+            "Prerequisites"
+          ],
+          "optional": [
+            "Resources",
+            "Examples"
+          ]
+        }
+      ],
+      "projectChecks": [
+        "Focus question is defined",
+        "Concepts have prerequisite relationships",
+        "Linking words describe relationships",
+        "Hierarchy is clear (general to specific)",
+        "At least one cross-link exists between areas"
+      ],
+      "exportReady": [
+        "All concepts have notes or resources",
+        "Prerequisite chains are complete",
+        "Cross-links are documented",
+        "Learning sequence is clear"
+      ]
+    },
+    "sampleData": {
+      "description": "Sample concept map for learning Machine Learning fundamentals",
+      "entities": [
+        {
+          "type": "concept",
+          "name": "Machine Learning",
+          "properties": {
+            "description": "Field of AI that enables computers to learn from data without explicit programming.",
+            "status": "in_progress",
+            "difficulty": "beginner",
+            "createdAt": "2025-01-05"
+          }
+        },
+        {
+          "type": "concept",
+          "name": "Linear Algebra",
+          "properties": {
+            "description": "Mathematical foundation: vectors, matrices, transformations.",
+            "status": "done",
+            "difficulty": "prerequisite",
+            "createdAt": "2025-01-05"
+          }
+        },
+        {
+          "type": "concept",
+          "name": "Supervised Learning",
+          "properties": {
+            "description": "Learning from labeled training data.",
+            "status": "in_progress",
+            "difficulty": "intermediate",
+            "createdAt": "2025-01-08"
+          }
+        }
+      ],
+      "relationships": [
+        {
+          "from": "Linear Algebra",
+          "verb": "requires",
+          "to": "Machine Learning"
+        },
+        {
+          "from": "Supervised Learning",
+          "verb": "partOf",
+          "to": "Machine Learning"
+        }
+      ]
+    },
+    "deploy": {
+      "provider": "cloud-run",
+      "buildCommand": "npm run build",
+      "outputDir": "build",
+      "config": {
+        "port": 3000,
+        "memory": "512Mi"
+      },
+      "oneClickCommand": "gcloud run deploy"
+    }
+  }
+}

package/kits/concept-map/skills/add-concept/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: Add Concept
+description: Add a new concept with proper relationships
+type: invocable
+version: "1.0.0"
+parameters: [conceptName]
+---
+
+## Add Concept
+
+Add a new concept with proper relationships
+
+### Steps
+
+1. Define the concept clearly (noun or noun phrase)
+2. Determine where it fits in the hierarchy
+3. Identify what prerequisite concepts it builds on
+4. Identify what concepts build on this one
+5. Connect to existing concepts with linking words
+6. Create the concept in the knowledge graph
+7. Add notes explaining the concept
+8. Add resources for learning more
+9. Look for cross-links to other areas
+
+### Inputs Required
+
+- **conceptName** (required): Name of the concept
+- **prerequisites** (optional): What must be understood first?
+
+### Expected Outputs
+
+- New concept with relationships
+- Updated hierarchy
+
+### When to Use
+
+This workflow is helpful when the user mentions:
+- "add concept"
+- "new topic"
+- "include concept"
+- "add idea"

package/kits/concept-map/skills/assess-understanding/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: Assess Understanding
+description: Evaluate comprehension of the concept map
+type: invocable
+version: "1.0.0"
+---
+
+## Assess Understanding
+
+Evaluate comprehension of the concept map
+
+### Steps
+
+1. Review the map structure: Is hierarchy clear?
+2. Check propositions: Do linked concepts make sense as sentences?
+3. Verify cross-links: Are connections between areas identified?
+4. Test recall: Can you explain each concept without looking?
+5. Check for gaps: Are there missing concepts or relationships?
+6. Identify weak areas: Where is understanding shallow?
+7. Compare to expert maps if available
+8. Create study plan for weak areas
+9. Schedule review and expansion
+
+### Expected Outputs
+
+- Understanding assessment
+- Study plan
+- Gap analysis
+
+### When to Use
+
+This workflow is helpful when the user mentions:
+- "assess"
+- "check understanding"
+- "how well do I know"
+- "test myself"