@soulcraft/kits 1.0.0

package/kits/web-application/skills/kit-expertise/SKILL.md

@@ -0,0 +1,211 @@
+---
+id: kit-expertise
+name: web-application-expertise
+description: Expert knowledge for building SvelteKit + Brainy web applications
+version: "1.0.0"
+type: background
+requiresVision: false
+requiresData: false
+---
+
+# Web Application Kit Expertise
+
+You are helping the user build a SvelteKit + Brainy web application. This is the reference implementation for all Workshop app templates.
+
+## Project Structure
+
+```
+src/
+├── lib/
+│   ├── brainy.ts      # Brainy client (auto-detects environment)
+│   └── types.ts       # TypeScript types and helpers
+└── routes/
+    ├── +layout.svelte # Root layout with navigation
+    └── +page.svelte   # Home page / dashboard
+```
+
+## Key Files
+
+### `$lib/brainy.ts` - Brainy Client
+The unified client that works in both Workshop (WebContainer) and standalone deployment. It mirrors the native @soulcraft/brainy API.
+
+### `$lib/types.ts` - Type Definitions
+Contains Entity types, helper functions like `getEntityName()`, and app-specific type customizations.
+
+### `.workshop.json` - Workshop Integration Config
+Tells Workshop how to build, run, and debug this app.
+
+## Brainy API Patterns
+
+### Creating Entities
+```typescript
+import { brainy } from '$lib/brainy'
+
+// Simple entity (data as string)
+await brainy.add({
+  type: 'person',
+  data: 'Alice Johnson',
+  metadata: { email: 'alice@example.com' }
+})
+
+// Structured entity (data as object)
+await brainy.add({
+  type: 'task',
+  data: { title: 'Review PR', priority: 'high' },
+  metadata: { assignee: 'alice', sprint: 12 }
+})
+```
+
+### Querying Entities
+```typescript
+// By type
+const people = await brainy.find({ type: 'person' })
+
+// With search
+const results = await brainy.find({
+  query: 'machine learning',
+  type: 'project',
+  limit: 10
+})
+
+// All entities (limited)
+const all = await brainy.find({ limit: 100 })
+```
+
+### Creating Relationships
+```typescript
+await brainy.relate({
+  from: personId,
+  to: projectId,
+  type: 'worksOn',
+  weight: 1.0
+})
+
+// Get relationships
+const rels = await brainy.getRelations({ from: personId })
+```
+
+### File Operations (VFS)
+```typescript
+// Read
+const content = await brainy.vfs.readFile('/docs/readme.md')
+
+// Write
+await brainy.vfs.writeFile('/docs/notes.md', '# Notes')
+
+// Directory
+const files = await brainy.vfs.readdir('/docs')
+```
+
+## Svelte 5 Patterns
+
+### State Management
+```svelte
+<script lang="ts">
+  // Reactive state
+  let items = $state<Item[]>([])
+  let loading = $state(true)
+
+  // Derived state
+  let total = $derived(items.length)
+
+  // Effects
+  $effect(() => {
+    console.log(`Items changed: ${items.length}`)
+  })
+</script>
+```
+
+### Data Loading
+```svelte
+<script lang="ts">
+  import { onMount } from 'svelte'
+  import { brainy } from '$lib/brainy'
+
+  let data = $state([])
+  let loading = $state(true)
+
+  onMount(async () => {
+    try {
+      data = await brainy.find({ type: 'task' })
+    } finally {
+      loading = false
+    }
+  })
+</script>
+```
+
+### Render Children (Layouts)
+```svelte
+<script lang="ts">
+  let { children } = $props()
+</script>
+
+<div class="layout">
+  {@render children()}
+</div>
+```
+
+## Adding Routes
+
+Create new routes by adding files to `src/routes/`:
+
+```
+src/routes/
+├── +page.svelte           # /
+├── about/
+│   └── +page.svelte       # /about
+├── items/
+│   ├── +page.svelte       # /items
+│   └── [id]/
+│       └── +page.svelte   # /items/:id
+```
+
+## Styling Guidelines
+
+Use the Workshop theme CSS variables:
+- `--primary`, `--primary-light`, `--primary-dark` - Brand colors
+- `--bg-dark`, `--bg-medium`, `--bg-light` - Background colors
+- `--text-primary`, `--text-secondary` - Text colors
+- `--glass`, `--glass-border` - Glass morphism effects
+- `--success`, `--warning`, `--error` - Status colors
+
+Use component-scoped styles:
+```svelte
+<style>
+  .my-component {
+    background: var(--glass);
+    border: 1px solid var(--glass-border);
+  }
+</style>
+```
+
+## Common Tasks
+
+### Adding a New Page
+1. Create `src/routes/your-page/+page.svelte`
+2. Import brainy and types
+3. Add onMount for data loading
+4. Add navigation link in layout
+
+### Adding a Form
+1. Use Svelte 5 `$state` for form fields
+2. Create submit handler that calls `brainy.add()` or `brainy.update()`
+3. Add loading state and error handling
+4. Refresh data after successful save
+
+### Adding a List View
+1. Create page with state for items and loading
+2. Load data in onMount using `brainy.find()`
+3. Render items using `{#each}`
+4. Add empty state for no items
+
+### Environment Detection
+```typescript
+// Check where app is running
+if (brainy.isWebContainer()) {
+  // Running in Workshop
+} else {
+  // Running standalone
+}
+```