@soulcraft/kits 1.0.0

package/kits/farkle-dice-game/skills/kit-expertise/SKILL.md

@@ -0,0 +1,137 @@
+# Farkle Dice Game Kit Expertise
+
+You are an expert in this Farkle dice game implementation. This kit provides a complete turn-based dice game with AI opponent support.
+
+## Architecture Overview
+
+### Game State Management
+- **`src/lib/stores/game.svelte.ts`**: Central game state using Svelte 5 runes
+- **`src/lib/game/scoring.ts`**: Complete Farkle scoring rules
+- **`src/lib/game/ai.ts`**: AI opponent logic with difficulty levels
+
+### Components
+- **`Die.svelte`**: Single die with 3D CSS animation
+- **`DiceRoll.svelte`**: Container for all dice with selection logic
+- **`ScoreCard.svelte`**: Player score display with progress
+- **`GameControls.svelte`**: Roll/Bank action buttons
+
+### Routes
+- **`/`**: Main game page (start screen → gameplay → game over)
+- **`/rules`**: Scoring rules reference
+- **`/stats`**: High scores and game history
+
+## Farkle Scoring Rules
+
+The game implements standard Farkle scoring:
+
+```typescript
+// Single dice
+Single 1 = 100 points
+Single 5 = 50 points
+
+// Three of a kind
+Three 1s = 1,000 points
+Three 2s = 200 points
+Three 3s = 300 points
+Three 4s = 400 points
+Three 5s = 500 points
+Three 6s = 600 points
+
+// Multipliers
+Four of a kind = 2× triple score
+Five of a kind = 4× triple score
+Six of a kind = 8× triple score
+
+// Special combinations
+Straight (1-2-3-4-5-6) = 1,500 points
+Three pairs = 1,500 points
+Two triplets = 2,500 points
+```
+
+## AI Opponent
+
+The AI makes decisions based on:
+1. **Expected value calculation** - Risk vs reward analysis
+2. **Difficulty settings** - Easy/Medium/Hard risk tolerance
+3. **Game context** - Score difference, proximity to winning
+
+```typescript
+// AI decision making
+const decision = makeAIDecision(gameState, 'medium')
+// Returns: { action: 'roll' | 'bank', diceToKeep: number[], reasoning: string }
+```
+
+## Brainy Integration
+
+Games and high scores are persisted to Brainy:
+
+```typescript
+// Save game result
+await brainy.add({
+  type: 'event',
+  data: {
+    gameType: 'farkle',
+    winnerId: 'player-1',
+    winnerScore: 10500,
+    turns: 15
+  },
+  metadata: { name: 'Farkle: Player vs Briggy' }
+})
+
+// Save high score
+await brainy.add({
+  type: 'measurement',
+  data: { playerName: 'Player', score: 10500 },
+  metadata: { type: 'farkle-highscore' }
+})
+```
+
+## Common Modifications
+
+### Change Target Score
+```typescript
+// In src/lib/stores/game.svelte.ts
+const DEFAULT_SETTINGS: GameSettings = {
+  targetScore: 10000, // Change this
+  // ...
+}
+```
+
+### Add New Scoring Combinations
+```typescript
+// In src/lib/game/scoring.ts
+// Add new combination detection in findScoringCombos()
+```
+
+### Modify AI Behavior
+```typescript
+// In src/lib/game/ai.ts
+// Adjust risk multipliers or add new strategy factors
+```
+
+### Add Sound Effects
+```typescript
+// Create src/lib/game/sounds.ts
+export const sounds = {
+  roll: new Audio('/sounds/dice-roll.mp3'),
+  score: new Audio('/sounds/score.mp3'),
+  bust: new Audio('/sounds/bust.mp3')
+}
+```
+
+## Testing the Game
+
+1. Start the app with `npm run dev`
+2. Enter a player name and click "Start Game"
+3. Roll dice by clicking "Roll Dice"
+4. Click scoring dice to keep them
+5. Choose to "Keep & Roll" or "Bank" points
+6. Watch the AI take its turn
+7. First to 10,000 wins!
+
+## Multiplayer in Collaborative Mode
+
+When published in Collaborative mode:
+- Both players share the same Brainy instance
+- Game state updates are broadcast via SSE
+- Real-time turn notifications

package/kits/franchise-ops/kit.json

@@ -0,0 +1,326 @@
+{
+  "$schema": "https://soulcraft.com/schemas/kit/v2.json",
+  "id": "franchise-ops",
+  "type": "soulcraft",
+  "role": "extension",
+  "status": "released",
+  "name": "Franchise Operations",
+  "description": "Multi-location operations with comparative analytics and location-specific settings",
+  "longDescription": "A composable franchise operations extension that adds multi-location management to any Venue kit. Enables location-to-location revenue comparisons, shared inventory templates, standardised pricing across locations, and franchise owner reporting dashboards. Each location remains independently operated with its own staff and data, while the franchise layer provides the consolidated view that owners and operators need to spot outliers, share best practices, and grow the network.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Soulcraft Labs",
+    "email": "kits@soulcraft.com",
+    "url": "https://soulcraft.com"
+  },
+  "icon": "🏢",
+  "tags": [
+    "franchise",
+    "multi-location",
+    "analytics",
+    "operations",
+    "extension",
+    "reporting",
+    "standardisation"
+  ],
+  "requires": [],
+  "shared": {
+    "industry": "franchise-management",
+    "category": "business",
+    "glossary": {
+      "franchisee": "An operator who runs one or more locations under the franchisor's brand and systems, typically paying a royalty on revenue.",
+      "franchisor": "The brand owner who grants franchisees the right to operate under their systems, standards, and trademark.",
+      "royalty": "A percentage of gross revenue paid by the franchisee to the franchisor in exchange for brand rights, systems, and ongoing support.",
+      "comp store sales": "Comparable store sales — revenue for locations open for more than one year, used to measure organic growth independent of new openings.",
+      "location scorecard": "A standardised performance summary comparing a location's KPIs against network averages and top-quartile benchmarks.",
+      "compliance audit": "A periodic review confirming that a franchisee location meets the brand's operational, safety, and presentation standards."
+    },
+    "aiExpertise": [
+      "multi-location franchise operations",
+      "comparative analytics and benchmarking",
+      "standardisation across locations",
+      "franchise agreement and royalty structures",
+      "location performance diagnostics",
+      "network expansion planning",
+      "operations manual and compliance management"
+    ],
+    "dataModelHints": [
+      "franchise_location",
+      "franchise_report",
+      "location_scorecard",
+      "network_benchmark"
+    ],
+    "dataModel": {
+      "entities": [
+        {
+          "domain": "franchise_location",
+          "type": "Location",
+          "description": "A single franchise location with its own address, franchisee owner, operating hours, and Stripe account. Extends the parent kit's Location entity with franchise-specific metadata.",
+          "products": {
+            "workshop": {
+              "view": "graph",
+              "icon": "📍"
+            },
+            "venue": {
+              "mapsTo": "LocationMeta",
+              "pos": false
+            },
+            "academy": {
+              "mapsTo": "knowledge-unit",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "franchise_report",
+          "type": "Measurement",
+          "description": "A generated performance report aggregating revenue, bookings, and operational metrics across some or all franchise locations for a specified date range.",
+          "products": {
+            "workshop": {
+              "view": "stats",
+              "icon": "📊"
+            },
+            "academy": {
+              "mapsTo": "learning-artifact",
+              "assessable": true
+            }
+          }
+        },
+        {
+          "domain": "location_scorecard",
+          "type": "Measurement",
+          "description": "A standardised KPI snapshot for a single location — revenue per seat, booking fill rate, average transaction value — benchmarked against the network average.",
+          "products": {
+            "workshop": {
+              "view": "stats",
+              "icon": "🏅"
+            }
+          }
+        },
+        {
+          "domain": "network_benchmark",
+          "type": "Concept",
+          "description": "A computed network-wide average or percentile for a specific KPI, used to contextualise individual location scorecards.",
+          "products": {
+            "workshop": {
+              "view": "stats",
+              "icon": "📈"
+            }
+          }
+        }
+      ],
+      "relationships": [
+        {
+          "from": "franchise_location",
+          "to": "booking",
+          "verb": "Contains",
+          "description": "Franchise location is home to all bookings and transactions made at that address."
+        },
+        {
+          "from": "franchise_report",
+          "to": "transaction",
+          "verb": "Aggregates",
+          "description": "Franchise report summarises transaction revenue across the selected locations and date window."
+        },
+        {
+          "from": "location_scorecard",
+          "to": "franchise_location",
+          "verb": "References",
+          "description": "Scorecard is computed for and linked to a specific franchise location."
+        },
+        {
+          "from": "location_scorecard",
+          "to": "network_benchmark",
+          "verb": "References",
+          "description": "Scorecard compares the location's metrics against the applicable network benchmarks."
+        }
+      ]
+    },
+    "suggestions": [
+      {
+        "label": "Compare locations",
+        "prompt": "Show me a revenue comparison across all franchise locations for the past 30 days."
+      },
+      {
+        "label": "Identify top performer",
+        "prompt": "Which location is performing best this quarter, and what can others learn from it?"
+      },
+      {
+        "label": "Flag underperformers",
+        "prompt": "Flag any locations tracking below the network average on fill rate or revenue per seat."
+      },
+      {
+        "label": "Standardise pricing",
+        "prompt": "Help me review and standardise pricing across all locations for consistency."
+      },
+      {
+        "label": "Generate a franchise report",
+        "prompt": "Generate a monthly franchise network report with revenue, bookings, and key KPIs."
+      },
+      {
+        "label": "Plan a new location",
+        "prompt": "Help me model the revenue potential for a new franchise location based on network performance."
+      }
+    ]
+  },
+  "academy": {
+    "skillPath": "franchise-management",
+    "level": "advanced",
+    "learningObjectives": [
+      "Configure and manage a multi-location franchise network with per-location settings and shared brand standards",
+      "Generate and interpret comparative performance reports across franchise locations",
+      "Identify outlier locations — both overperformers and underperformers — and design interventions",
+      "Apply standardised pricing, inventory templates, and operational checklists across the network",
+      "Model network expansion economics using comp store data and location scorecards"
+    ],
+    "assessmentTypes": [
+      "portfolio",
+      "peer-review"
+    ],
+    "certificationSlug": "franchise-operator"
+  },
+  "workshop": {
+    "aiPersona": {
+      "role": "You are a franchise operations consultant helping multi-location business owners understand network performance, standardise operations, and identify growth opportunities. You think in benchmarks, scorecards, and comp store comparisons.",
+      "expertise": [
+        "multi-location franchise operations and management",
+        "comparative performance analytics and benchmarking",
+        "franchise standardisation and compliance",
+        "location scorecard design and KPI selection",
+        "network expansion modelling",
+        "royalty structure and franchise agreement economics"
+      ],
+      "tone": "collaborator",
+      "avoidances": [
+        "Don't compare locations in isolation — always benchmark against the network average and top quartile",
+        "Don't recommend operational changes to a location without looking at its scorecard history first",
+        "Don't conflate individual location ownership with network strategy — they require different conversations"
+      ]
+    },
+    "graphGuidance": {
+      "conceptCreation": {
+        "triggers": [
+          "new franchise location opened or onboarded",
+          "franchise report generated or requested",
+          "location scorecard reviewed or benchmarked",
+          "network-wide KPI or benchmark discussed",
+          "franchisee performance issue raised"
+        ],
+        "typeMapping": {
+          "franchise location": "location",
+          "location": "location",
+          "franchise report": "measurement",
+          "scorecard": "measurement",
+          "benchmark": "concept",
+          "KPI": "concept"
+        }
+      },
+      "relationshipPatterns": [
+        {
+          "from": "franchise_location",
+          "to": "booking",
+          "verb": "Contains",
+          "description": "Location owns its bookings and revenue"
+        },
+        {
+          "from": "franchise_report",
+          "to": "transaction",
+          "verb": "Aggregates",
+          "description": "Report aggregates transaction data"
+        },
+        {
+          "from": "location_scorecard",
+          "to": "franchise_location",
+          "verb": "References",
+          "description": "Scorecard is for a specific location"
+        }
+      ],
+      "rules": [
+        "Every franchise location must have a unique identifier used consistently across all reports",
+        "Franchise reports should always specify the date range they cover",
+        "Network benchmarks are updated after each reporting cycle — never use stale benchmarks",
+        "Location scorecards must link to the benchmarks they compare against"
+      ]
+    },
+    "qualityGates": {
+      "projectChecks": [
+        "At least two franchise locations are configured with distinct addresses",
+        "A franchise report is generated covering all locations for a defined date range",
+        "Location scorecards show per-location KPIs benchmarked against the network average",
+        "Revenue comparison across locations is functional",
+        "Standardised pricing or inventory template is applied across locations"
+      ]
+    },
+    "publishConfig": {
+      "contentType": "document",
+      "publishable": true
+    },
+    "remoteWorkspace": {
+      "connectedWorkbenches": [
+        {
+          "name": "Location Comparison",
+          "view": "stats",
+          "entityTypes": [
+            "franchise_location",
+            "location_scorecard"
+          ],
+          "description": "Side-by-side KPI comparison across all franchise locations"
+        },
+        {
+          "name": "Cross-Location Revenue",
+          "view": "timeline",
+          "entityTypes": [
+            "franchise_report"
+          ],
+          "description": "Revenue trends by location over time with network average overlay"
+        },
+        {
+          "name": "Franchise Health Dashboard",
+          "view": "board",
+          "entityTypes": [
+            "franchise_location",
+            "network_benchmark"
+          ],
+          "description": "At-a-glance health status for each location — green, amber, or red"
+        },
+        {
+          "name": "Network Graph",
+          "view": "graph",
+          "entityTypes": [
+            "franchise_location"
+          ],
+          "description": "Geographic and relational map of all locations in the network"
+        }
+      ]
+    }
+  },
+  "venue": {
+    "features": {
+      "franchise": true
+    },
+    "stations": [
+      {
+        "id": "franchise",
+        "label": "Franchise Dashboard",
+        "route": "/api/manage/franchise",
+        "icon": "🏢",
+        "roles": [
+          "owner"
+        ],
+        "scope": "kit",
+        "context": "both"
+      },
+      {
+        "id": "multi-location",
+        "label": "All Locations",
+        "route": "/api/manage/locations",
+        "icon": "📍",
+        "roles": [
+          "owner"
+        ],
+        "scope": "kit",
+        "context": "both"
+      }
+    ]
+  }
+}