@zaflun/lumio-agent-skill 0.1.0

package/dist/chunk-I2USQPPS.js

@@ -0,0 +1,1729 @@
+// src/install.ts
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+
+// src/content/skill.ts
+var skillContent = `# Lumio Extension SDK
+
+AI agent skill file for building Lumio Extensions.
+
+## Architecture
+
+Lumio Extensions are sandboxed React apps that run inside a 3-layer iframe sandbox. The custom React reconciler serializes component trees to \`LumioComponentNode[]\` \u2014 there is no DOM access from extension code.
+
+\`\`\`
+3-Layer Sandbox:
+  Host (lumio.vision / OBS browser source)
+    \u2514\u2500\u2500 Supervisor iframe (supervisor.extension.lumio.vision)
+          \u2514\u2500\u2500 Extension Runtime iframe (ext.lumio.vision)
+                \u2514\u2500\u2500 Web Worker (server function execution)
+\`\`\`
+
+\`\`\`
+Extension Project:
+  lumio.config.json          <- Extension manifest (ID, name, category, permissions, targets, config_schema)
+  src/editor.tsx             <- Dashboard editor panel (sidebar in overlay editor)
+  src/layer.tsx              <- OBS overlay surface (transparent, read-only inputs)
+  src/interactive.tsx        <- Audience interaction page (optional)
+  server/schema.ts           <- DB schema (defineTable + validators)
+  server/functions.ts        <- Server functions (queries, mutations, actions)
+\`\`\`
+
+**Runtime flow:**
+1. Extension Runtime iframe loads from \`ext.lumio.vision/ext/{slug}/layer?token=lm_ext_xxx&install_id=uuid\`
+2. \`Lumio.render(<Component />, { target: "layer" })\` must be called within 10 seconds
+3. The custom React reconciler serializes the tree to \`LumioComponentNode[]\` via postMessage to the Supervisor
+4. The Supervisor validates and forwards the node tree to the Host for rendering
+5. Server functions execute inside a Web Worker in a V8 isolate sandbox (256 MB memory, 10s CPU timeout)
+6. Cross-frame messaging uses \`WorkerBridge\` (exported from \`@zaflun/lumio-sdk\`; replaces the legacy \`PostMessageBridge\`)
+
+**Key constraints:**
+- No direct DOM access \u2014 the reconciler serializes to \`LumioComponentNode[]\`, never touches the DOM
+- localStorage and sessionStorage are blocked in the Extension Runtime (separate origin isolation)
+- No access to Lumio core data (users, accounts, overlays) except via SDK hooks
+- Network access only via \`ctx.fetch()\` with declared \`egress.allowHosts\` (enforced by the Supervisor)
+- Extension tokens (\`lm_ext_*\`) are scoped and short-lived (15 min, auto-refreshed via postMessage)
+- Widget tokens (\`lm_widget_*\`) are permanent and scoped to a widget_id (Widget Gallery)
+
+## Core Concepts
+
+### Three Surfaces
+
+| Target | Where | Purpose |
+|--------|-------|---------|
+| \`editor\` | Dashboard overlay editor sidebar | Config UI, settings, content management |
+| \`layer\` | OBS Browser Source (transparent) | Visual overlay in stream |
+| \`interactive\` | Standalone page (\`/ext/{slug}\`) | Viewer interaction (votes, games) |
+
+All three surfaces share storage via \`useExtensionStorage()\` \u2014 changes in editor propagate to layer in real-time.
+
+### lumio.config.json
+
+\`\`\`json
+{
+  "$schema": "https://docs.lumio.vision/schemas/lumio.config.schema.json",
+  "extensionId": "uuid",
+  "slug": "k8f2x-my-extension",
+  "name": "My Extension",
+  "description": "Description",
+  "category": "widget",
+  "version": "1.0.0",
+  "targets": ["editor", "layer"],
+  "server": true,
+  "permissions": ["events:read", "chat:read"],
+  "egress": {
+    "allowHosts": ["api.example.com"],
+    "allowPorts": [443]
+  },
+  "visibility": "public",
+  "pricing": { "type": "free" },
+  "config_schema": {
+    "fields": [
+      { "key": "title", "type": "string", "label": "Widget Title", "default": "My Widget" },
+      { "key": "showBorder", "type": "boolean", "label": "Show Border", "default": true }
+    ]
+  }
+}
+\`\`\`
+
+**Slug format:** \`{short_id}-{kebab-name}\` (e.g. \`k8f2x-my-extension\`). Auto-generated on \`lumio init\`. The store URL is \`/store/{slug}\` (e.g. \`/store/k8f2x-my-extension\`).
+
+**Categories:** \`widget\`, \`extension\`, \`overlay\`, \`bot_module\`, \`integration\`, \`theme\`
+
+**Pricing:** \`{ "type": "free" }\` | \`{ "type": "one_time", "amount": 499, "currency": "eur" }\` | \`{ "type": "subscription", "amount": 199, "currency": "eur", "interval": "monthly" }\`
+
+**Access control:**
+- \`"visibility": "public"\` \u2014 listed in Widget Gallery
+- \`"visibility": "unlisted"\` \u2014 accessible by direct link only
+- Private invite: grant \`free_access\` to specific accounts via dashboard
+
+**Revenue split:** Configurable per developer (default 70/30 developer/Lumio).
+
+**Feature gates:** The following Lumio plan features must be enabled for extension functionality:
+- \`feature:extensions\` \u2014 allows using extensions at all
+- \`feature:extension_development\` \u2014 allows publishing and developing extensions
+- \`feature:widgets\` \u2014 allows Widget Gallery access
+
+### Developer Teams
+
+Extensions are owned by a solo developer or a team. Team members share publishing rights and revenue. Select team on \`lumio init\` or manage via dashboard.
+
+### Widget Gallery
+
+Widgets installed from the Widget Gallery use \`lm_widget_*\` tokens (permanent, scoped to widget_id). Unlike extension installs (which use \`lm_ext_*\`, 15 min TTL), widget tokens persist across sessions and are used for Widget Gallery standalone embeds.
+
+## Quick Start
+
+\`\`\`bash
+# Install CLI
+npm install -g @zaflun/lumio-cli
+
+# Authenticate
+lumio login
+
+# Log out (clears stored credentials)
+lumio logout
+
+# Create extension (registers ID on Lumio, scaffolds project; prompts for team if applicable)
+lumio init my-widget
+
+# Start dev server with hot reload + sandbox
+lumio dev
+
+# Build for deployment
+lumio build
+
+# Deploy (creates draft, submit via dashboard for review)
+lumio deploy
+\`\`\`
+
+## Components
+
+15 SDK components (all accept \`style: VisionStyle\`):
+
+**Layout:** \`Box\`, \`VStack\`, \`HStack\`, \`CompactView\`, \`List\`
+**Display:** \`Text\` (variant: heading/muted/default), \`Image\` (objectFit), \`Animated\`
+**Input:** \`Button\` (variant: default/destructive), \`Toggle\`, \`TextField\`, \`TextArea\`, \`NumberField\`, \`Dropdown\`, \`Slider\`
+
+**VisionStyle** is a typed CSS subset (allowed: flexbox, grid, \`position: relative\` / \`absolute\`, sizing, spacing, colors, border, typography, transitions; blocked: \`fixed\`, \`sticky\`, CSS expressions).
+
+On OBS layer: input components become read-only (buttons hidden, toggles show on/off text).
+
+See \`components.md\` for full props and examples.
+
+## Hooks
+
+11 SDK hooks:
+
+| Hook | Returns | Purpose |
+|------|---------|---------|
+| \`useExtensionStorage()\` | \`[storage, setStorage]\` | Persistent KV store, synced across targets |
+| \`useVisionState(key, default)\` | \`[value, setValue]\` | useState for single keys |
+| \`useExtensionContext()\` | \`{ extensionId, target, overlayId, interactiveUrl }\` | Extension metadata |
+| \`useLumioEvent(eventType)\` | \`event\` | Live events (chat, alerts, spotify) \u2014 type-safe: \`eventType\` is \`LumioEventType\` |
+| \`useLumioConfig()\` | \`[config, setConfig]\` | Extension config read/write (uses config_schema fields) |
+| \`useLumioTheme()\` | \`theme\` | Current theme (dark/light/custom) |
+| \`useLumioIdentity()\` | \`{ userId, accountId, role }\` | Current user context |
+| \`useLumioAction(action, params)\` | \`{ execute, data, isLoading, error }\` | Trigger Lumio actions \u2014 type-safe: \`action\` is \`LumioActionType\` |
+| \`useQuery(fn, params?)\` | \`{ data, isLoading, error, refetch }\` | Call server query |
+| \`useMutation(fn)\` | \`{ mutate, mutateAsync, data, isLoading, error }\` | Call server mutation/action |
+| \`useAnimation(preset, options?)\` | \`animationProps\` | SDK animation presets for \`Animated\` component |
+
+**Important:** \`setStorage\` must always spread: \`setStorage({ ...storage, key: value })\`
+
+## Server Functions
+
+Two types:
+
+**Declarative** (preferred, transpiled to SQL, no JS runtime):
+\`\`\`typescript
+import { queryRows, insertRow, patchRow, deleteRow } from "@zaflun/lumio-sdk/server";
+export const getItems = queryRows("items");
+export const addItem = insertRow("items", { text: arg("text") }, { editorOnly: true });
+export const updateItem = patchRow("items", arg("id"), { done: arg("done") });
+export const removeItem = deleteRow("items", arg("id"), { editorOnly: true });
+\`\`\`
+
+**Handler-based** (V8 isolate Web Worker, full control):
+\`\`\`typescript
+import { action, arg, v } from "@zaflun/lumio-sdk/server";
+export const fetchScores = action({
+  args: { league: v.string() },
+  handler: async (ctx, args) => {
+    // ctx.db, ctx.fetch, ctx.secrets, ctx.auth all available
+    const res = await ctx.fetch("https://api.example.com/scores?league=" + args.league);
+    return res.json();
+  },
+});
+\`\`\`
+
+**Extension Actions** via \`useLumioAction()\` (21 total, \`action\` is \`LumioActionType\`):
+\`\`\`tsx
+// Trigger platform actions (requires matching permission in lumio.config.json)
+const { execute: sendChat } = useLumioAction("chat:send", {});
+const { execute: banUser } = useLumioAction("chat:ban", {});
+const { execute: unbanUser } = useLumioAction("chat:unban", {});
+const { execute: timeoutUser } = useLumioAction("chat:timeout", {});
+const { execute: setScene } = useLumioAction("obs:set_scene", {});
+const { execute: startRecording } = useLumioAction("obs:start_recording", {});
+const { execute: stopRecording } = useLumioAction("obs:stop_recording", {});
+const { execute: emitEvent } = useLumioAction("events:emit", {});
+const { execute: updateLayer } = useLumioAction("overlay:update_layer", {});
+const { execute: spotifyPlay } = useLumioAction("spotify:play", {});
+const { execute: spotifyPause } = useLumioAction("spotify:pause", {});
+const { execute: spotifySkip } = useLumioAction("spotify:skip", {});
+const { execute: spotifySeek } = useLumioAction("spotify:seek", {});
+const { execute: spotifyVolume } = useLumioAction("spotify:volume", {});
+const { execute: spotifyShuffle } = useLumioAction("spotify:shuffle", {});
+const { execute: spotifyRepeat } = useLumioAction("spotify:repeat", {});
+const { execute: spotifyQueueAdd } = useLumioAction("spotify:queue_add", {});
+\`\`\`
+
+See \`server-functions.md\` for schema definition, storage scoping, and advanced patterns.
+
+## CLI Commands
+
+12 commands provided by \`@zaflun/lumio-cli\`:
+
+| Command | Description |
+|---------|-------------|
+| \`lumio login\` | PKCE OAuth via browser (\`lumio login --token <token>\` for CI) |
+| \`lumio logout\` | Clear stored credentials |
+| \`lumio whoami\` | Show current user + account |
+| \`lumio init <name>\` | Scaffold extension project, register extension ID (prompts for team) |
+| \`lumio dev\` | Local dev server with hot reload + mock events |
+| \`lumio build\` | Bundle as standalone HTML + source archive |
+| \`lumio deploy\` | Upload to Lumio (status: draft). Flags: \`-v\`, \`-d\`, \`--breaking\`, \`--draft\` |
+| \`lumio status\` | Check review status of latest version |
+| \`lumio logs\` | Stream server function logs |
+| \`lumio secrets\` | Manage server-side secrets |
+| \`lumio team\` | Manage developer team members |
+| \`lumio config\` | Show/set CLI configuration |
+
+See \`cli-workflows.md\` for detailed usage and examples.
+
+## Auth
+
+9 token types in the Lumio auth system. Extensions use two:
+
+- **\`lm_ext_*\`** \u2014 Extension tokens: 15 min TTL, scoped to install_id + extension_id + account_id, auto-refreshed via postMessage
+- **\`lm_widget_*\`** \u2014 Widget tokens: permanent, scoped to widget_id (Widget Gallery standalone embeds)
+
+Extension tokens have no RBAC permissions (\`has_permission()\` always returns false) and can only access \`ext_{extension_id}.*\` DB tables via server functions.
+
+**\`editorOnly: true\`** on server functions restricts mutations to editor surface only (layer/interactive cannot call them).
+
+See \`auth.md\` for all 9 token types and the full token lifecycle.
+
+## Extension Version Flow
+
+\`\`\`
+lumio deploy -> draft -> [Submit via dashboard] -> pending_review
+  -> [Admin approves] -> testing -> [Developer requests publish] -> pending_publish
+  -> [Admin approves] -> published
+  -> [Admin rejects] -> rejected (fix + resubmit)
+\`\`\`
+
+## Common Patterns
+
+### Editor + Layer sync
+\`\`\`tsx
+// editor.tsx
+const [storage, setStorage] = useExtensionStorage();
+<Toggle label="Show" checked={storage.visible ?? false}
+  onChange={(v) => setStorage({ ...storage, visible: v })} />
+
+// layer.tsx
+const [storage] = useExtensionStorage();
+if (!storage.visible) return null;
+return <Text content={storage.text} />;
+\`\`\`
+
+### Live events
+\`\`\`tsx
+// eventType is LumioEventType \u2014 autocomplete shows all 49 valid event strings
+const event = useLumioEvent("twitch:follower");
+// event updates automatically when a new follower event arrives
+\`\`\`
+
+**All 49 event types** (\`LumioEventType\`):
+
+Twitch (22): \`twitch:follower\`, \`twitch:subscriber\`, \`twitch:subscribe\`, \`twitch:gift_sub\`, \`twitch:resub\`, \`twitch:cheer\`, \`twitch:raid\`, \`twitch:redemption\`, \`twitch:ban\`, \`twitch:unban\`, \`twitch:hype_train\`, \`twitch:poll\`, \`twitch:prediction\`, \`twitch:goal\`, \`twitch:ad_break\`, \`twitch:stream_update\`, \`twitch:chat\`
+
+YouTube (7): \`youtube:subscriber\`, \`youtube:superchat\`, \`youtube:supersticker\`, \`youtube:gift_membership\`, \`youtube:gift_membership_received\`, \`youtube:poll\`, \`youtube:chat\`
+
+Kick (6): \`kick:follower\`, \`kick:subscribe\`, \`kick:gift\`, \`kick:stream_online\`, \`kick:stream_offline\`, \`kick:chat\`
+
+Trovo (3): \`trovo:subscribe\`, \`trovo:spell\`, \`trovo:chat\`
+
+Spotify (11): \`spotify:track\`, \`spotify:play\`, \`spotify:pause\`, \`spotify:skip\`, \`spotify:volume\`, \`spotify:queue_add\`, \`spotify:device\`, \`spotify:playlist_add\`, \`spotify:playlist_remove\`, \`spotify:playlist_create\`, \`spotify:playlist_delete\`
+
+### Server queries
+\`\`\`tsx
+const { data: items } = useQuery("getItems");
+const { mutate: addItem } = useMutation("addItem");
+addItem({ text: "New item" });
+\`\`\`
+
+### Lumio actions
+\`\`\`tsx
+const { execute } = useLumioAction("chat:send", {});
+execute({ message: "Hello from my extension!" });
+\`\`\`
+
+### Animations
+\`\`\`tsx
+import { Animated, useAnimation } from "@zaflun/lumio-sdk";
+const anim = useAnimation("slide-in", { duration: 300 });
+<Animated {...anim}><Text content="Animated!" /></Animated>
+\`\`\`
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| \`RENDER_TIMEOUT\` | \`Lumio.render()\` not called within 10s | Ensure render call is at module top level |
+| \`EXTENSION_NOT_FOUND\` | Invalid extensionId in config | Run \`lumio init\` or create via dashboard |
+| \`EGRESS_BLOCKED\` | Fetch to undeclared host | Add host to \`egress.allowHosts\` in config |
+| \`STORAGE_QUOTA\` | Exceeded storage limit | Reduce data or request limit increase |
+| \`EDITOR_ONLY\` | Mutation called from layer/interactive | Remove \`editorOnly\` or restrict to editor |
+| \`SUPERVISOR_BLOCKED\` | Supervisor rejected a postMessage | Check message origin matches ext.lumio.vision |
+| \`WORKER_CREATION_FAILED\` | Web Worker could not be created | Verify server functions bundle is valid JS |
+| \`STORAGE_DOM_EXCEPTION\` | localStorage/sessionStorage access | Use \`useExtensionStorage()\` instead (storage blocked) |
+
+See \`troubleshooting.md\` for the full error reference.
+`;
+
+// src/content/components.ts
+var componentsContent = `# Lumio SDK Components
+
+All 15 components available in \`@zaflun/lumio-sdk\`. Every component accepts an optional \`style: VisionStyle\` prop.
+
+> **Note:** There is no direct DOM access from extension code. The custom React reconciler serializes component trees to \`LumioComponentNode[]\` via postMessage \u2014 you must use SDK components exclusively.
+
+## Layout Components
+
+### Box
+
+Generic container with flexbox support.
+
+\`\`\`tsx
+import { Box } from "@zaflun/lumio-sdk";
+
+<Box style={{ display: "flex", gap: 8, padding: 16 }}>
+  {children}
+</Box>
+\`\`\`
+
+**Props:**
+- \`children: ReactNode\`
+- \`style?: VisionStyle\`
+
+### VStack
+
+Vertical stack layout (column direction).
+
+\`\`\`tsx
+import { VStack } from "@zaflun/lumio-sdk";
+
+<VStack style={{ gap: 12 }}>
+  <Text content="Line 1" />
+  <Text content="Line 2" />
+</VStack>
+\`\`\`
+
+**Props:**
+- \`children: ReactNode\`
+- \`gap?: number\` (default: 8)
+- \`style?: VisionStyle\`
+
+### HStack
+
+Horizontal stack layout (row direction).
+
+\`\`\`tsx
+import { HStack } from "@zaflun/lumio-sdk";
+
+<HStack style={{ gap: 8 }}>
+  <Text content="Live" />
+  <Text content="Score: 3-1" />
+</HStack>
+\`\`\`
+
+**Props:**
+- \`children: ReactNode\`
+- \`gap?: number\` (default: 8)
+- \`style?: VisionStyle\`
+
+### CompactView
+
+Panel container with title bar. Standard layout for editor surfaces.
+
+\`\`\`tsx
+import { CompactView } from "@zaflun/lumio-sdk";
+
+<CompactView title="Settings">
+  <TextField label="Name" value={name} onChange={setName} />
+  <Toggle label="Visible" checked={visible} onChange={setVisible} />
+</CompactView>
+\`\`\`
+
+**Props:**
+- \`title: string\`
+- \`children: ReactNode\`
+- \`collapsible?: boolean\` (default: false)
+- \`defaultCollapsed?: boolean\` (default: false)
+- \`style?: VisionStyle\`
+
+### List
+
+Scrollable list container with virtualization for large datasets.
+
+\`\`\`tsx
+import { List } from "@zaflun/lumio-sdk";
+
+<List
+  items={messages}
+  renderItem={(msg) => <Text content={msg.text} />}
+  maxHeight={400}
+/>
+\`\`\`
+
+**Props:**
+- \`items: T[]\`
+- \`renderItem: (item: T, index: number) => ReactNode\`
+- \`maxHeight?: number\`
+- \`emptyText?: string\`
+- \`style?: VisionStyle\`
+
+## Display Components
+
+### Text
+
+Text display with variants.
+
+\`\`\`tsx
+import { Text } from "@zaflun/lumio-sdk";
+
+<Text content="Hello World" variant="heading" />
+<Text content="Subtitle" variant="muted" />
+<Text content="Normal text" />
+\`\`\`
+
+**Props:**
+- \`content: string\`
+- \`variant?: "heading" | "muted" | "default"\` (default: "default")
+- \`style?: VisionStyle\`
+
+### Image
+
+Image display with fit options.
+
+\`\`\`tsx
+import { Image } from "@zaflun/lumio-sdk";
+
+<Image src="https://example.com/logo.png" alt="Logo" objectFit="contain" />
+\`\`\`
+
+**Props:**
+- \`src: string\`
+- \`alt: string\`
+- \`objectFit?: "cover" | "contain" | "fill" | "none"\` (default: "cover")
+- \`width?: number | string\`
+- \`height?: number | string\`
+- \`style?: VisionStyle\`
+
+## Input Components
+
+**Important:** On OBS layer surface, all input components become read-only. Buttons are hidden, toggles show "On"/"Off" text, dropdowns show the selected value.
+
+### Button
+
+Clickable button with variants.
+
+\`\`\`tsx
+import { Button } from "@zaflun/lumio-sdk";
+
+<Button label="Save" onClick={handleSave} />
+<Button label="Delete" variant="destructive" onClick={handleDelete} />
+\`\`\`
+
+**Props:**
+- \`label: string\`
+- \`onClick: () => void\`
+- \`variant?: "default" | "destructive"\` (default: "default")
+- \`disabled?: boolean\`
+- \`style?: VisionStyle\`
+
+### Toggle
+
+Boolean toggle switch.
+
+\`\`\`tsx
+import { Toggle } from "@zaflun/lumio-sdk";
+
+<Toggle label="Show overlay" checked={visible} onChange={setVisible} />
+\`\`\`
+
+**Props:**
+- \`label: string\`
+- \`checked: boolean\`
+- \`onChange: (checked: boolean) => void\`
+- \`disabled?: boolean\`
+- \`style?: VisionStyle\`
+
+### TextField
+
+Single-line text input.
+
+\`\`\`tsx
+import { TextField } from "@zaflun/lumio-sdk";
+
+<TextField label="Title" value={title} onChange={setTitle} placeholder="Enter title..." />
+\`\`\`
+
+**Props:**
+- \`label: string\`
+- \`value: string\`
+- \`onChange: (value: string) => void\`
+- \`placeholder?: string\`
+- \`disabled?: boolean\`
+- \`maxLength?: number\`
+- \`style?: VisionStyle\`
+
+### TextArea
+
+Multi-line text input.
+
+\`\`\`tsx
+import { TextArea } from "@zaflun/lumio-sdk";
+
+<TextArea label="Description" value={desc} onChange={setDesc} rows={4} />
+\`\`\`
+
+**Props:**
+- \`label: string\`
+- \`value: string\`
+- \`onChange: (value: string) => void\`
+- \`placeholder?: string\`
+- \`rows?: number\` (default: 3)
+- \`maxLength?: number\`
+- \`disabled?: boolean\`
+- \`style?: VisionStyle\`
+
+### NumberField
+
+Numeric input with optional min/max/step.
+
+\`\`\`tsx
+import { NumberField } from "@zaflun/lumio-sdk";
+
+<NumberField label="Score" value={score} onChange={setScore} min={0} max={100} step={1} />
+\`\`\`
+
+**Props:**
+- \`label: string\`
+- \`value: number\`
+- \`onChange: (value: number) => void\`
+- \`min?: number\`
+- \`max?: number\`
+- \`step?: number\`
+- \`disabled?: boolean\`
+- \`style?: VisionStyle\`
+
+### Dropdown
+
+Select dropdown with options.
+
+\`\`\`tsx
+import { Dropdown } from "@zaflun/lumio-sdk";
+
+<Dropdown
+  label="League"
+  value={league}
+  onChange={setLeague}
+  options={[
+    { label: "NFL", value: "nfl" },
+    { label: "NBA", value: "nba" },
+    { label: "NHL", value: "nhl" },
+  ]}
+/>
+\`\`\`
+
+**Props:**
+- \`label: string\`
+- \`value: string\`
+- \`onChange: (value: string) => void\`
+- \`options: { label: string; value: string }[]\`
+- \`placeholder?: string\`
+- \`disabled?: boolean\`
+- \`style?: VisionStyle\`
+
+### Slider
+
+Range slider input.
+
+\`\`\`tsx
+import { Slider } from "@zaflun/lumio-sdk";
+
+<Slider label="Volume" value={volume} onChange={setVolume} min={0} max={100} step={1} />
+\`\`\`
+
+**Props:**
+- \`label: string\`
+- \`value: number\`
+- \`onChange: (value: number) => void\`
+- \`min: number\`
+- \`max: number\`
+- \`step?: number\` (default: 1)
+- \`showValue?: boolean\` (default: true)
+- \`disabled?: boolean\`
+- \`style?: VisionStyle\`
+
+### Animated
+
+Wrapper component for SDK-managed entrance/exit animations. Use with \`useAnimation()\` hook \u2014 do not use raw CSS keyframes for entrance/exit effects.
+
+\`\`\`tsx
+import { Animated, useAnimation } from "@zaflun/lumio-sdk";
+
+// Use a preset
+const anim = useAnimation("slide-in", { duration: 400, delay: 0 });
+<Animated {...anim}>
+  <Text content="I animate in!" />
+</Animated>
+
+// Fade out on condition
+const exitAnim = useAnimation("fade-out", { duration: 200 });
+<Animated {...exitAnim} trigger={isHiding}>
+  <Box>{children}</Box>
+</Animated>
+\`\`\`
+
+**Available presets:** \`fade-in\`, \`fade-out\`, \`slide-in\`, \`slide-out\`, \`scale-in\`, \`scale-out\`, \`bounce-in\`
+
+**Props:**
+- \`children: ReactNode\`
+- \`trigger?: boolean\` (play animation when true; default: plays on mount)
+- \`style?: VisionStyle\`
+- _(spread \`useAnimation()\` return value for preset props)_
+
+**\`useAnimation(preset, options?)\`**
+- \`preset: string\` \u2014 animation preset name
+- \`options?: { duration?: number; delay?: number; easing?: string }\`
+- Returns: props object to spread onto \`<Animated>\`
+
+**Best practices:**
+- Always use SDK presets instead of raw CSS animations for entrance/exit effects \u2014 the reconciler maps them to allowed VisionStyle \`animation\` properties
+- Keep animation durations short on the OBS layer surface (< 500ms) to avoid frame drops
+- Avoid animating layout-affecting properties (\`width\`, \`height\`) on the layer; prefer \`opacity\` and \`transform\`
+
+## VisionStyle
+
+Typed CSS subset accepted by all components. Sanitized by the host \u2014 only safe properties are allowed.
+
+**Allowed:**
+- Flexbox: \`display\`, \`flexDirection\`, \`justifyContent\`, \`alignItems\`, \`gap\`, \`flex\`, \`flexWrap\`
+- Grid: \`gridTemplateColumns\`, \`gridTemplateRows\`, \`gridGap\`
+- Positioning: \`position: "relative" | "absolute"\`, \`top\`, \`right\`, \`bottom\`, \`left\`, \`zIndex\`
+- Sizing: \`width\`, \`height\`, \`minWidth\`, \`minHeight\`, \`maxWidth\`, \`maxHeight\`
+- Spacing: \`margin\`, \`padding\` (and directional variants)
+- Colors: \`color\`, \`backgroundColor\`, \`borderColor\`, \`opacity\`
+- Border: \`border\`, \`borderWidth\`, \`borderRadius\`, \`borderStyle\`
+- Typography: \`fontSize\`, \`fontWeight\`, \`fontFamily\`, \`lineHeight\`, \`textAlign\`, \`textTransform\`
+- Transform: \`transform\`, \`transformOrigin\`
+- Animations: \`transition\`, \`animation\`, \`animationDuration\`
+- Other: \`objectFit\`, \`pointerEvents\`, \`cursor\`, \`overflow\`, \`overflowX\`, \`overflowY\`
+
+**Blocked:**
+- \`position: "fixed" | "sticky"\` \u2014 iframe escape prevention
+- CSS expressions
+- \`javascript:\` URLs
+`;
+
+// src/content/server-functions.ts
+var serverFunctionsContent = `# Server Functions
+
+Server functions run on the Lumio API, not in the browser. They access the extension's isolated DB schema (\`ext_{extension_id}\`).
+
+## Schema Definition
+
+Define your data model in \`server/schema.ts\`:
+
+\`\`\`typescript
+import { defineSchema, defineTable, v } from "@zaflun/lumio-sdk/server";
+
+export default defineSchema({
+  items: defineTable({
+    text: v.string(),
+    done: v.boolean(),
+    priority: v.number().optional(),
+    tags: v.array(v.string()).optional(),
+  }).storage("instance"),
+
+  settings: defineTable({
+    key: v.string(),
+    value: v.string(),
+  }).storage("account"),
+});
+\`\`\`
+
+### Validators
+
+| Validator | Description |
+|-----------|-------------|
+| \`v.string()\` | String field |
+| \`v.number()\` | Numeric field |
+| \`v.boolean()\` | Boolean field |
+| \`v.array(v.string())\` | Array of strings |
+| \`v.object({ key: v.string() })\` | Nested object |
+| \`.optional()\` | Mark field as nullable |
+
+### Storage Scoping
+
+\`\`\`typescript
+defineTable({...}).storage("instance")   // Per overlay instance (most isolated)
+defineTable({...}).storage("overlay")    // Per overlay (shared across instances)
+defineTable({...}).storage("account")    // Per account (shared across overlays)
+defineTable({...}).storage("global")     // Global (shared across all accounts \u2014 admin only)
+\`\`\`
+
+See \`runtime-scopes.md\` for when to use each scope.
+
+## Declarative Functions (preferred)
+
+Transpiled directly to parameterized SQL \u2014 no JS runtime, fast, secure.
+
+\`\`\`typescript
+import { queryRows, insertRow, patchRow, deleteRow, arg, filter } from "@zaflun/lumio-sdk/server";
+
+// Read all rows
+export const getItems = queryRows("items");
+
+// Read with filter
+export const getDoneItems = queryRows("items", {
+  filter: filter("done", "=", true),
+});
+
+// Insert a row (editorOnly: only callable from editor surface)
+export const addItem = insertRow("items", {
+  text: arg("text"),
+  done: false,
+  priority: arg("priority"),
+}, { editorOnly: true });
+
+// Update specific fields
+export const toggleItem = patchRow("items", arg("id"), {
+  done: arg("done"),
+});
+
+// Delete a row
+export const removeItem = deleteRow("items", arg("id"), { editorOnly: true });
+\`\`\`
+
+### \`arg(name)\` and expressions
+
+- \`arg("name")\` \u2014 reads from the client-provided arguments
+- \`identity()\` \u2014 returns \`{ userId, accountId }\` of the caller
+- \`secret("KEY")\` \u2014 reads a server-side secret (never exposed to client)
+- \`filter(field, op, value)\` \u2014 query filter (=, !=, >, <, >=, <=, LIKE, IN)
+
+## Handler-Based Functions
+
+For complex logic that cannot be expressed declaratively. Runs in V8 isolate sandbox.
+
+\`\`\`typescript
+import { query, mutation, action, v } from "@zaflun/lumio-sdk/server";
+
+// Read-only query
+export const getLeaderboard = query({
+  args: { limit: v.number().optional() },
+  handler: async (ctx, args) => {
+    const rows = await ctx.db.get("scores", {
+      order: { score: "desc" },
+      limit: args.limit ?? 10,
+    });
+    return rows;
+  },
+});
+
+// Write operation
+export const submitScore = mutation({
+  args: { playerName: v.string(), score: v.number() },
+  handler: async (ctx, args) => {
+    return ctx.db.insert("scores", {
+      player_name: args.playerName,
+      score: args.score,
+    });
+  },
+  editorOnly: false,
+});
+
+// External API call (requires egress.allowHosts in config)
+// Egress allowlist is enforced by the Supervisor \u2014 requests to undeclared hosts are rejected before reaching the network
+export const fetchScores = action({
+  args: { sport: v.string(), league: v.string() },
+  handler: async (ctx, args) => {
+    const apiKey = ctx.secrets.get("ESPN_API_KEY");
+    const res = await ctx.fetch(
+      \`https://site.api.espn.com/apis/v2/sports/\${args.sport}/\${args.league}/scoreboard\`,
+      { headers: { "Authorization": \`Bearer \${apiKey}\` } }
+    );
+    return res.json();
+  },
+});
+\`\`\`
+
+### Handler Context (\`ctx\`)
+
+Handler-based functions run inside a V8 isolate Web Worker. The \`ctx\` object provides the full sandbox API:
+
+| Property | Description |
+|----------|-------------|
+| \`ctx.db.get(table, options?)\` | Read rows from extension DB schema |
+| \`ctx.db.insert(table, data)\` | Insert row |
+| \`ctx.db.patch(table, id, data)\` | Update row |
+| \`ctx.db.delete(table, id)\` | Delete row |
+| \`ctx.fetch(url, options?)\` | HTTP request (egress allowlist enforced by Supervisor) |
+| \`ctx.secrets.get(key)\` | Read server-side secret (set via dashboard or \`lumio secrets\`) |
+| \`ctx.auth\` | \`{ userId, accountId, target }\` \u2014 caller identity from extension token |
+
+### Sandbox Limits
+
+| Limit | Value |
+|-------|-------|
+| Memory | 256 MB per invocation |
+| CPU timeout | 10 seconds |
+| Filesystem | No access |
+| Network | Only \`ctx.fetch()\` via egress allowlist (Supervisor-enforced) |
+| Dynamic code | Blocked (\`eval\`, \`Function\`, \`import()\`) |
+| Storage APIs | localStorage/sessionStorage blocked (separate origin) |
+
+### Rate Limits
+
+| Function type | Limit |
+|--------------|-------|
+| Queries | 100/min per installation |
+| Mutations | 50/min per installation |
+| Actions (with fetch) | 20/min per installation |
+| Storage writes | 200/min per installation |
+
+## Extension Actions
+
+Extension Actions let extensions trigger Lumio platform capabilities on behalf of the account. They are called via \`useLumioAction()\` in the frontend and require the matching permission in \`lumio.config.json\`.
+
+\`\`\`tsx
+import { useLumioAction } from "@zaflun/lumio-sdk";
+
+// Send a chat message on the connected platform
+const { execute: sendChat, isLoading, error } = useLumioAction("chat:send", {});
+sendChat({ message: "Hello from the extension!" });
+
+// Switch OBS scene (requires OBS WebSocket integration)
+const { execute: setScene } = useLumioAction("obs:set_scene", {});
+setScene({ sceneName: "Main Scene" });
+
+// Emit a custom event into the Lumio event bus
+const { execute: emitEvent } = useLumioAction("events:emit", {});
+emitEvent({ type: "extension:custom", payload: { score: 42 } });
+
+// Update a specific layer in the overlay
+const { execute: updateLayer } = useLumioAction("overlay:update_layer", {});
+updateLayer({ layerId: "uuid", visible: true });
+\`\`\`
+
+**Available actions (21 total, \`action\` is \`LumioActionType\`):**
+
+| Action | Permission required | Description |
+|--------|--------------------|----|
+| \`chat:send\` | \`chat:send\` | Send chat message on connected platform |
+| \`chat:ban\` | \`chat:ban\` | Ban a user from chat |
+| \`chat:unban\` | \`chat:ban\` | Unban a user from chat |
+| \`chat:timeout\` | \`chat:ban\` | Timeout a user from chat |
+| \`obs:set_scene\` | \`obs:control\` | Switch OBS scene |
+| \`obs:start_recording\` | \`obs:control\` | Start OBS recording |
+| \`obs:stop_recording\` | \`obs:control\` | Stop OBS recording |
+| \`events:emit\` | \`events:write\` | Emit event into Lumio event bus |
+| \`overlay:update_layer\` | \`overlays:edit\` | Update overlay layer properties |
+| \`spotify:play\` | \`spotify:control\` | Resume Spotify playback |
+| \`spotify:pause\` | \`spotify:control\` | Pause Spotify playback |
+| \`spotify:skip\` | \`spotify:control\` | Skip to next track |
+| \`spotify:seek\` | \`spotify:control\` | Seek to position in current track |
+| \`spotify:volume\` | \`spotify:control\` | Set Spotify volume |
+| \`spotify:shuffle\` | \`spotify:control\` | Toggle shuffle mode |
+| \`spotify:repeat\` | \`spotify:control\` | Set repeat mode |
+| \`spotify:queue_add\` | \`spotify:control\` | Add track to Spotify queue |
+
+Actions are proxied through the Lumio API \u2014 the extension never accesses OAuth tokens or platform credentials directly.
+`;
+
+// src/content/cli-workflows.ts
+var cliWorkflowsContent = `# CLI Workflows
+
+All 12 commands provided by \`@zaflun/lumio-cli\` (\`npm install -g @zaflun/lumio-cli\`).
+
+## lumio login
+
+Authenticate with Lumio via PKCE OAuth flow.
+
+\`\`\`bash
+# Browser-based login (opens browser for OAuth)
+lumio login
+
+# Token-based login (CI/CD)
+lumio login --token lm_usr_xxxxxxxxxxxx
+
+# Or via environment variable
+export LUMIO_TOKEN=lm_usr_xxxxxxxxxxxx
+\`\`\`
+
+Credentials stored in \`~/.lumio/credentials\`.
+
+## lumio logout
+
+Clear stored credentials from \`~/.lumio/credentials\`.
+
+\`\`\`bash
+lumio logout
+# Output:
+# Logged out. Credentials removed from ~/.lumio/credentials.
+\`\`\`
+
+## lumio whoami
+
+Show current authenticated user and account.
+
+\`\`\`bash
+lumio whoami
+# Output:
+# User: raphael (raphael@example.com)
+# Account: My Stream (plan: pro)
+# API: https://api.lumio.vision
+\`\`\`
+
+## lumio init
+
+Scaffold a new extension project. Registers the extension ID on Lumio (requires auth). If you belong to developer teams, you will be prompted to select which team (or personal account) owns the extension.
+
+\`\`\`bash
+lumio init my-widget
+
+# Interactive prompts:
+# ? Extension name: My Widget
+# ? Description: A cool widget
+# ? Category: widget
+# ? Targets: editor, layer
+# ? Server functions: yes
+# ? Template: Widget (editor + layer + storage)
+# ? Owner: My Stream (personal) / Awesome Team  <- team selection if applicable
+#
+# Creating extension on Lumio...
+# Extension-ID: 88b2478a-39c7-468e-bebd-14e52fd97ac0
+# Slug: k8f2x-my-widget
+#
+# Writing lumio.config.json...
+# Writing src/editor.tsx...
+# Writing src/layer.tsx...
+# Writing server/schema.ts...
+# Writing server/functions.ts...
+#
+# Done! Run \`lumio dev\` to start developing.
+\`\`\`
+
+### Templates
+
+| Template | Targets | Server | Description |
+|----------|---------|--------|-------------|
+| Blank | editor + layer | No | Minimal starting point |
+| Widget | editor + layer | Yes | Widget with storage |
+| Full-Stack | editor + layer | Yes | Complete extension with server functions |
+| Interactive Game | editor + layer + interactive | Yes | Viewer interaction game |
+| Bot Module | server-only | Yes | Chat command module |
+| Integration | server | Yes | External API integration |
+| Theme | editor | No | Style variables only |
+
+## lumio dev
+
+Start local development server with hot reload and Lumio sandbox.
+
+\`\`\`bash
+lumio dev
+
+# Output:
+# Lumio Dev Server running at http://localhost:5173
+# Editor:      http://localhost:5173/editor
+# Layer:       http://localhost:5173/layer
+# Interactive: http://localhost:5173/interactive
+#
+# Mock events available. Press 'e' to emit a test event.
+# Press 'q' to quit.
+\`\`\`
+
+Features:
+- Hot reload on file changes
+- Mock event system (simulated chat, follows, subs)
+- Sandbox environment matching production constraints
+- Server function execution with local DB
+
+## lumio build
+
+Bundle the extension as standalone HTML and create source archive.
+
+\`\`\`bash
+lumio build
+
+# Output:
+# Building extension...
+# Bundling editor.tsx -> dist/editor.html (42 KB)
+# Bundling layer.tsx -> dist/layer.html (38 KB)
+# Creating source archive -> dist/source.tar.gz
+# Build complete!
+\`\`\`
+
+Warns if \`CHANGELOG.md\` is missing.
+
+## lumio deploy
+
+Upload the built extension to Lumio. Creates a draft version.
+
+\`\`\`bash
+# Basic deploy
+lumio deploy
+
+# With version override
+lumio deploy -v 1.2.0
+
+# With release notes
+lumio deploy -d "Added NHL support"
+
+# Mark as breaking change
+lumio deploy --breaking -v 2.0.0
+
+# Explicit draft (default behavior)
+lumio deploy --draft
+\`\`\`
+
+After deploy:
+1. Version status = \`draft\`
+2. Submit for review via dashboard (\`/dashboard/extensions/{slug}/submit\`)
+3. Admin reviews code
+4. Testing phase (invite testers)
+5. Request publish
+6. Admin final approval
+7. Published to store
+
+### CI/CD Example
+
+\`\`\`yaml
+# .github/workflows/deploy.yml
+name: Deploy Extension
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm install -g @zaflun/lumio-cli
+      - run: lumio login --token \${{ secrets.LUMIO_TOKEN }}
+      - run: pnpm install
+      - run: lumio build
+      - run: lumio deploy -v \${{ github.ref_name }} -d "Automated release"
+\`\`\`
+
+## lumio status
+
+Check the review status of the latest deployed version.
+
+\`\`\`bash
+lumio status
+
+# Output:
+# Extension: Sports Scoreboard (sports-scoreboard)
+# Latest version: 1.2.0
+# Status: testing
+# Submitted: May 17, 2026
+# Approved: May 18, 2026
+# Testers: 3 invited, 2 active
+\`\`\`
+
+## lumio logs
+
+Stream server function execution logs in real-time.
+
+\`\`\`bash
+lumio logs
+
+# Output:
+# [2026-05-17 14:32:01] QUERY getItems -> 12 rows (3ms)
+# [2026-05-17 14:32:05] MUTATION addItem -> { id: "abc123" } (5ms)
+# [2026-05-17 14:32:10] ACTION fetchScores -> 200 OK (142ms)
+# [2026-05-17 14:32:15] ERROR fetchScores -> EGRESS_BLOCKED: host not in allowlist
+
+# Filter by function name
+lumio logs --filter fetchScores
+
+# Filter by level
+lumio logs --level error
+\`\`\`
+
+## lumio secrets
+
+Manage server-side secrets used by handler-based server functions via \`ctx.secrets.get("KEY")\`.
+
+\`\`\`bash
+# Set a secret
+lumio secrets set ESPN_API_KEY abc123xyz
+
+# List secret keys (values are never shown)
+lumio secrets list
+# Output:
+# ESPN_API_KEY   (set 2026-05-19)
+# WEATHER_TOKEN  (set 2026-04-01)
+
+# Delete a secret
+lumio secrets delete ESPN_API_KEY
+\`\`\`
+
+Secrets are stored encrypted on the Lumio platform and injected into the V8 isolate at runtime. They are never exposed to the frontend or to other extensions.
+
+## lumio team
+
+Manage developer team members. Teams share publishing rights and revenue.
+
+\`\`\`bash
+# List team members
+lumio team list
+
+# Invite a team member
+lumio team invite alice@example.com --role editor
+
+# Remove a team member
+lumio team remove alice@example.com
+
+# Show current team
+lumio team whoami
+\`\`\`
+
+## lumio config
+
+Show or set CLI configuration.
+
+\`\`\`bash
+# Show current config
+lumio config
+
+# Set API endpoint (useful for self-hosted or staging)
+lumio config set api https://api.lumio.vision
+
+# Set default account when you have multiple
+lumio config set account my-account-slug
+\`\`\`
+`;
+
+// src/content/auth.ts
+var authContent = `# Auth Model
+
+## All 9 Token Types
+
+The Lumio auth system has 9 token types:
+
+| # | Prefix | Name | TTL | Purpose |
+|---|--------|------|-----|---------|
+| 1 | \`lm_sys_\` | System Key | Permanent | Internal service-to-service auth |
+| 2 | \`lm_usr_\` | User API Key | Permanent | External API access for users |
+| 3 | _(JWT)_ | JWT | Session | OAuth login session |
+| 4 | \`lm_pop_\` | Popout Token | Non-expiring | Overlay access for non-session viewers |
+| 5 | \`lm_overlay_\` | Overlay Token | Permanent | Per-overlay OBS browser source access |
+| 6 | \`lm_share_\` | Shared Overlay Token | Time-limited | Temporary shared overlay links |
+| 7 | \`lm_ext_\` | Extension Token | 15 min | Scoped to one extension installation |
+| 8 | \`lm_widget_\` | Widget Token | Permanent | Widget Gallery standalone embeds |
+| 9 | _(none)_ | Anonymous | N/A | Public/unauthenticated access |
+
+## Extension Tokens (\`lm_ext_*\`)
+
+Extensions authenticate via short-lived \`lm_ext_*\` tokens.
+
+| Property | Value |
+|----------|-------|
+| Prefix | \`lm_ext_\` |
+| TTL | 15 min (auto-refreshed via postMessage) |
+| Scope | Single extension installation (install_id + extension_id) |
+| RBAC | None (\`has_permission()\` returns false) |
+| DB access | Only \`ext_{extension_id}.*\` tables |
+| Rate limit | Popout tier (600 req/min) |
+
+### Token Fields
+
+\`\`\`
+AuthContext::ExtensionToken {
+    token_id: Uuid,
+    extension_id: Uuid,
+    install_id: Uuid,
+    account_id: Uuid,
+    target: "editor" | "layer" | "interactive",
+}
+\`\`\`
+
+### Token Lifecycle
+
+1. User opens extension in dashboard/overlay \u2014 Lumio server generates \`lm_ext_*\` token
+2. Token passed to Extension Runtime iframe: \`ext.lumio.vision/ext/{slug}/layer?token=lm_ext_xxx&install_id=uuid\` where \`slug\` includes the \`short_id\` prefix (e.g. \`k8f2x-my-extension\`); the store URL is \`/store/k8f2x-my-extension\`
+3. SDK uses token for all API calls (server functions, storage, events)
+4. Token auto-refreshes via postMessage every 12 minutes (before 15-min expiry) \u2014 the Supervisor mediates the refresh
+5. On page reload, a new token is generated
+
+### What Extensions Cannot Access
+
+- No Lumio core tables (users, accounts, overlays, channel_connections)
+- No OAuth tokens, API keys, client secrets
+- No other extensions' data
+- No other accounts' data
+- No direct Redis access
+- No platform API calls (only via \`useLumioAction()\`)
+- No localStorage or sessionStorage (blocked at Extension Runtime origin)
+
+## Widget Tokens (\`lm_widget_*\`)
+
+Widget Gallery standalone embeds use \`lm_widget_*\` tokens.
+
+| Property | Value |
+|----------|-------|
+| Prefix | \`lm_widget_\` |
+| TTL | Permanent (no expiry) |
+| Scope | Single widget_id |
+| RBAC | None |
+| Use | Widget Gallery embeds, standalone widget pages |
+
+Widget tokens are suitable for persistent, public-facing embeds where session refresh is not practical.
+
+## \`editorOnly\` Flag
+
+Server functions marked with \`editorOnly: true\` can only be called from the \`editor\` surface.
+
+\`\`\`typescript
+// Only callable from editor.tsx \u2014 layer.tsx and interactive.tsx get 403
+export const addItem = insertRow("items", { text: arg("text") }, { editorOnly: true });
+
+// Callable from any surface
+export const getItems = queryRows("items");
+\`\`\`
+
+Use \`editorOnly\` for:
+- Write operations that should only happen in the dashboard
+- Admin/config mutations
+- Destructive operations (delete, reset)
+
+## Lumio Actions Auth
+
+\`useLumioAction()\` calls are authorized by checking:
+1. Extension has the permission declared in \`lumio.config.json -> permissions\`
+2. Account has the required connection/integration configured
+3. Extension token is valid and matches the installation
+
+\`\`\`json
+{
+  "permissions": ["chat:send", "obs:set_scene", "events:emit", "overlay:update_layer"]
+}
+\`\`\`
+
+The extension never sees OAuth tokens or credentials \u2014 Lumio executes the action on behalf of the account.
+
+## Extension Access Patterns
+
+- **Public** (\`"visibility": "public"\`): Listed in Widget Gallery, anyone can install.
+- **Unlisted** (\`"visibility": "unlisted"\`): Not in Widget Gallery, accessible by direct link.
+- **Private invite**: Developer grants \`free_access\` to specific accounts via the dashboard. The account can install the extension even if it is paid or restricted.
+`;
+
+// src/content/runtime-scopes.ts
+var runtimeScopesContent = `# Runtime Scopes
+
+## Sandbox Architecture
+
+Extensions run inside a 3-layer iframe sandbox. Understanding the layers is important for debugging messaging and storage issues:
+
+\`\`\`
+Host (lumio.vision / OBS browser source)
+  \u2514\u2500\u2500 Supervisor iframe (supervisor.extension.lumio.vision)
+        Purpose: validates postMessage traffic, enforces egress allowlist,
+                 mediates token refresh, proxies LumioComponentNode[] to host
+        \u2514\u2500\u2500 Extension Runtime iframe (ext.lumio.vision)
+              Purpose: runs extension code on a separate origin
+              Storage: localStorage/sessionStorage BLOCKED (cross-origin isolation)
+              \u2514\u2500\u2500 Web Worker
+                    Purpose: V8 isolate for server function execution
+                    Memory: 256 MB   CPU: 10s timeout
+\`\`\`
+
+**Supervisor layer responsibilities:**
+- Validates all postMessage messages between Extension Runtime and Host
+- Enforces \`egress.allowHosts\` \u2014 rejects fetch requests to undeclared hosts before they reach the network
+- Mediates \`lm_ext_*\` token refresh (12 min interval, before 15 min expiry)
+- Forwards serialized \`LumioComponentNode[]\` to the Host renderer
+
+**Extension Runtime (ext.lumio.vision) origin isolation:**
+- Runs on a separate origin from the Host \u2014 this prevents direct DOM access and localStorage sharing
+- \`localStorage\` and \`sessionStorage\` throw \`DOMException: Access is denied\` \u2014 use \`useExtensionStorage()\` instead
+- \`document.cookie\` is unavailable
+- Cross-origin postMessage to the Host goes through the Supervisor
+
+## Storage Scoping
+
+Every \`defineTable()\` call specifies a storage scope that controls data isolation.
+
+## Scopes
+
+### \`instance\` (most isolated)
+
+Data is scoped to a specific extension installation within a specific overlay.
+
+\`\`\`typescript
+defineTable({...}).storage("instance")
+\`\`\`
+
+- Filtered by: \`_account_id\` + \`_overlay_id\`
+- Use for: per-widget data (scoreboard scores, timer state, per-overlay config)
+- Example: A "Sports Scoreboard" widget has different scores in each overlay it appears in
+
+### \`overlay\`
+
+Data is scoped to a specific overlay (shared across all instances of this extension in that overlay).
+
+\`\`\`typescript
+defineTable({...}).storage("overlay")
+\`\`\`
+
+- Filtered by: \`_account_id\` + \`_overlay_id\`
+- Use for: overlay-level shared state (theme overrides, layout preferences)
+- Example: All widgets in one overlay share the same color scheme
+
+### \`account\`
+
+Data is scoped to the account (shared across all overlays).
+
+\`\`\`typescript
+defineTable({...}).storage("account")
+\`\`\`
+
+- Filtered by: \`_account_id\`
+- Use for: account-wide settings, user preferences, persistent state
+- Example: A streamer's global extension settings, saved templates
+
+### \`global\`
+
+Data is shared across all accounts. Use sparingly \u2014 typically only for extension-level configuration.
+
+\`\`\`typescript
+defineTable({...}).storage("global")
+\`\`\`
+
+- Filtered by: nothing (all accounts see the same data)
+- Use for: extension-wide leaderboards, shared content
+- Example: A global high-score leaderboard across all streamers
+- **Warning:** Write access to global tables requires careful rate limiting
+
+## Choosing a Scope
+
+| Scope | Data shared across | Best for |
+|-------|-------------------|----------|
+| \`instance\` | Nothing (fully isolated) | Per-widget state, game sessions |
+| \`overlay\` | Instances in same overlay | Overlay-level config |
+| \`account\` | All overlays in account | User preferences, persistent data |
+| \`global\` | All accounts | Leaderboards, shared content |
+
+**Default recommendation:** Start with \`instance\` and widen only when needed.
+
+## DB Schema Mapping
+
+Each scope maps to automatic WHERE clauses:
+
+\`\`\`sql
+-- instance scope:
+SELECT * FROM ext_{id}.items WHERE _account_id = $1 AND _overlay_id = $2
+
+-- overlay scope:
+SELECT * FROM ext_{id}.items WHERE _account_id = $1 AND _overlay_id = $2
+
+-- account scope:
+SELECT * FROM ext_{id}.items WHERE _account_id = $1
+
+-- global scope:
+SELECT * FROM ext_{id}.items
+\`\`\`
+
+The scoping is enforced server-side \u2014 extensions cannot bypass it.
+`;
+
+// src/content/best-practices.ts
+var bestPracticesContent = `# Best Practices
+
+## Performance
+
+### Minimize renders
+- Use \`useVisionState()\` for individual values instead of \`useExtensionStorage()\` for everything
+- Avoid spreading entire storage on every keystroke \u2014 debounce text inputs
+- Use \`useMemo\` and \`useCallback\` to avoid unnecessary re-renders
+
+### Optimize server function calls
+- Prefer declarative functions (\`queryRows\`, \`insertRow\`) over handler-based \u2014 they skip the V8 isolate
+- Batch related data into single queries instead of multiple round-trips
+- Use \`useQuery\` with appropriate refetch intervals, not continuous polling
+
+### Keep bundles small
+- Import only what you need from \`@zaflun/lumio-sdk\` (tree-shakeable)
+- Avoid large libraries \u2014 the bundle runs in an iframe, every KB counts
+- Images should be loaded via URLs, not bundled as base64
+
+### Layer surface
+- Use CSS animations via \`VisionStyle\` instead of JS-driven animations
+- Keep the layer surface minimal \u2014 it runs in OBS at 30/60 fps
+- Return \`null\` from components when they should be invisible (do not use \`display: none\`)
+
+## UX Patterns
+
+### Editor-Layer sync
+Always use \`useExtensionStorage()\` for state that should be visible on both editor and layer. Changes propagate in real-time via WebSocket.
+
+\`\`\`tsx
+// editor.tsx \u2014 user configures
+const [storage, setStorage] = useExtensionStorage();
+<TextField label="Title" value={storage.title ?? ""}
+  onChange={(v) => setStorage({ ...storage, title: v })} />
+
+// layer.tsx \u2014 displays result
+const [storage] = useExtensionStorage();
+<Text content={storage.title ?? "Default Title"} variant="heading" />
+\`\`\`
+
+### Graceful defaults
+Always provide sensible defaults using \`??\` (nullish coalescing). Storage might be empty on first load.
+
+\`\`\`tsx
+const visible = storage.visible ?? true;
+const maxItems = storage.maxItems ?? 10;
+const theme = storage.theme ?? "dark";
+\`\`\`
+
+### Loading states
+Use the \`isLoading\` flag from \`useQuery\` and \`useMutation\`:
+
+\`\`\`tsx
+const { data, isLoading, error } = useQuery("getItems");
+
+if (isLoading) return <Text content="Loading..." variant="muted" />;
+if (error) return <Text content="Error loading data" variant="muted" />;
+return <List items={data} renderItem={(item) => <Text content={item.text} />} />;
+\`\`\`
+
+### CompactView for editor panels
+Wrap editor settings in \`CompactView\` for consistent styling with the Lumio dashboard:
+
+\`\`\`tsx
+<CompactView title="Display Settings" collapsible>
+  <Toggle label="Show title" checked={showTitle} onChange={setShowTitle} />
+  <Dropdown label="Theme" value={theme} onChange={setTheme}
+    options={[{ label: "Dark", value: "dark" }, { label: "Light", value: "light" }]} />
+</CompactView>
+\`\`\`
+
+### Transparent backgrounds on layer
+The layer surface should have a transparent background so it composites correctly over the stream in OBS:
+
+\`\`\`tsx
+// layer.tsx \u2014 no background, content floats over stream
+Lumio.render(<Overlay />, { target: "layer" });
+// The host iframe already has background: transparent
+\`\`\`
+
+## Config Schema
+
+Use \`config_schema\` in \`lumio.config.json\` for user-customizable settings. The Lumio dashboard renders these as a form in the Widget Gallery install flow \u2014 the user fills them in without needing to open the editor surface.
+
+\`\`\`json
+{
+  "config_schema": {
+    "fields": [
+      { "key": "title", "type": "string", "label": "Widget Title", "default": "My Widget" },
+      { "key": "maxItems", "type": "number", "label": "Max Items", "default": 10 },
+      { "key": "showBorder", "type": "boolean", "label": "Show Border", "default": true },
+      {
+        "key": "theme",
+        "type": "select",
+        "label": "Color Theme",
+        "options": [
+          { "label": "Dark", "value": "dark" },
+          { "label": "Light", "value": "light" }
+        ],
+        "default": "dark"
+      }
+    ]
+  }
+}
+\`\`\`
+
+Read config values via \`useLumioConfig()\`:
+
+\`\`\`tsx
+const [config] = useLumioConfig();
+const title = config.title ?? "My Widget";
+const maxItems = config.maxItems ?? 10;
+\`\`\`
+
+**When to use config_schema vs storage:**
+- \`config_schema\` \u2014 install-time settings (set once, rarely changed)
+- \`useExtensionStorage()\` \u2014 runtime state (changes during stream)
+
+## Animation Best Practices
+
+- Always use SDK presets via \`useAnimation()\` + \`<Animated>\` for entrance/exit effects \u2014 never write raw CSS keyframe \`@keyframes\` rules
+- The reconciler maps animation preset names to allowed \`VisionStyle\` \`animation\` properties; raw keyframe strings are stripped by the Supervisor
+- Keep durations short on OBS layer (< 400ms). Longer animations cause visible frame drops in OBS at 30/60 fps
+- Prefer animating \`opacity\` and \`transform\` (GPU-composited) over \`width\`, \`height\`, \`margin\`, \`padding\` (layout-triggering)
+
+\`\`\`tsx
+// Good: SDK preset, short duration, transform-based
+const anim = useAnimation("slide-in", { duration: 300 });
+<Animated {...anim}><Text content="New follower!" /></Animated>
+
+// Bad: raw CSS animation string \u2014 stripped by Supervisor
+<Box style={{ animation: "mySlide 1s ease-in-out" }}>...</Box>
+\`\`\`
+
+## Extension Access Patterns
+
+Choose the right visibility setting for your extension:
+
+| Pattern | Config | Use when |
+|---------|--------|----------|
+| **Public** | \`"visibility": "public"\` | Extension is listed in Widget Gallery, anyone can install |
+| **Unlisted** | \`"visibility": "unlisted"\` | Share via direct link only, not discoverable in store |
+| **Private invite** | Any visibility + grant \`free_access\` via dashboard | Give specific accounts access to a paid or restricted extension |
+
+For beta testing before public launch:
+1. Deploy with \`"visibility": "unlisted"\`
+2. Grant \`free_access\` to invited testers via dashboard
+3. Switch to \`"visibility": "public"\` when ready for public release
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Direct DOM manipulation | Use SDK components only \u2014 reconciler serializes to \`LumioComponentNode[]\` |
+| \`setStorage(newObj)\` without spread | \`setStorage({ ...storage, key: value })\` |
+| Polling with setInterval | Use \`useLumioEvent()\` for live data |
+| Large inline images | Use URL-based images via \`Image\` component |
+| Missing \`Lumio.render()\` | Must be called within 10s of page load |
+| Hardcoded strings | Use \`config_schema\` fields for user-customizable text |
+| Using localStorage directly | Use \`useExtensionStorage()\` (localStorage blocked at ext.lumio.vision) |
+| Raw CSS \`@keyframes\` animations | Use \`useAnimation()\` + \`<Animated>\` SDK presets |
+`;
+
+// src/content/troubleshooting.ts
+var troubleshootingContent = `# Troubleshooting
+
+## Error Reference
+
+| Error Code | Message | Cause | Fix |
+|------------|---------|-------|-----|
+| \`RENDER_TIMEOUT\` | Extension did not render within 10 seconds | \`Lumio.render()\` not called or called too late | Move \`Lumio.render()\` to module top level, outside async code |
+| \`EXTENSION_NOT_FOUND\` | Extension ID not found | Invalid \`extensionId\` in \`lumio.config.json\` | Run \`lumio init\` to register, or create via dashboard |
+| \`INSTALL_NOT_FOUND\` | Installation not found | Extension not installed on this account | Install via store or check \`install_id\` parameter |
+| \`EGRESS_BLOCKED\` | Host not in allowlist | \`ctx.fetch()\` called with undeclared host | Add host to \`egress.allowHosts\` in \`lumio.config.json\` |
+| \`EGRESS_PRIVATE_IP\` | Private IP range blocked | Fetch targeting localhost or private network | Use public HTTPS endpoints only |
+| \`STORAGE_QUOTA\` | Storage quota exceeded | Extension data exceeds allocated storage | Reduce stored data or request limit increase |
+| \`EDITOR_ONLY\` | Function restricted to editor | Mutation with \`editorOnly: true\` called from layer/interactive | Remove \`editorOnly\` flag or call only from editor |
+| \`MEMORY_LIMIT\` | V8 isolate memory exceeded (128 MB) | Handler-based function using too much memory | Reduce data processing, stream large datasets |
+| \`CPU_TIMEOUT\` | V8 isolate CPU timeout (5s) | Handler-based function running too long | Optimize logic, break into smaller operations |
+| \`RATE_LIMITED\` | Too many requests (429) | Exceeded per-installation rate limit | Reduce call frequency, batch operations |
+| \`TOKEN_EXPIRED\` | Extension token expired | \`lm_ext_*\` token past 15-min TTL | SDK auto-refreshes; if manual, request new token |
+| \`SCHEMA_VALIDATION\` | Invalid function arguments | Args do not match \`v.string()\`/\`v.number()\` validators | Check argument types match schema definition |
+| \`TABLE_NOT_FOUND\` | Table does not exist | Referenced table not defined in \`server/schema.ts\` | Add table to \`defineSchema()\` and redeploy |
+| \`PERMISSION_DENIED\` | Missing declared permission | Action requires undeclared permission | Add permission to \`lumio.config.json -> permissions\` |
+| \`SECRET_NOT_FOUND\` | Secret key not set | \`ctx.secrets.get("KEY")\` with unset secret | Set secret via dashboard (\`/dashboard/extensions/{slug}/secrets\`) |
+| \`CHANGELOG_MISSING\` | No changelog entry for version | \`lumio deploy\` without matching CHANGELOG.md entry | Add entry for the version in CHANGELOG.md, or use \`-d\` flag |
+| \`BUNDLE_TOO_LARGE\` | Bundle exceeds size limit | Built bundle exceeds \`max_bundle_size_mb\` | Reduce bundle size or request limit increase |
+| \`SUPERVISOR_BLOCKED\` | Supervisor rejected postMessage | Message origin or schema invalid | Ensure you are in the correct iframe layer; do not post to Host directly |
+| \`WORKER_CREATION_FAILED\` | Web Worker could not start | Server functions bundle is invalid or too large | Check for syntax errors in server functions; run \`lumio build\` locally |
+| \`STORAGE_DOM_EXCEPTION\` | localStorage/sessionStorage access attempt | Extension Runtime (ext.lumio.vision) blocks storage APIs | Replace \`localStorage.setItem\` with \`useExtensionStorage()\` |
+| \`SLUG_FORMAT_INVALID\` | Slug does not match short-ID format | Manually edited slug in \`lumio.config.json\` | Use auto-generated slug (\`k8f2x-my-extension\` format) or run \`lumio init\` |
+
+## Common Issues
+
+### Extension not showing in overlay
+1. Check the extension is installed (\`/dashboard/store/installed\`)
+2. Verify the overlay has an extension layer with this extension
+3. Check browser console for \`RENDER_TIMEOUT\` errors
+4. Verify \`Lumio.render()\` is called with \`target: "layer"\`
+
+### Server functions returning empty data
+1. Check storage scope \u2014 \`instance\` scope needs matching overlay context
+2. Verify the table is defined in \`server/schema.ts\`
+3. Check \`lumio logs\` for query errors
+4. Ensure data was inserted with the correct scope
+
+### Hot reload not working in dev mode
+1. Verify \`lumio dev\` is running
+2. Check for TypeScript compilation errors in terminal
+3. Ensure file is saved (autosave may be off)
+4. Try stopping and restarting \`lumio dev\`
+
+### CORS errors in browser console
+Extensions run in sandboxed iframes \u2014 they should never make direct HTTP requests. Use:
+- \`useQuery()\` / \`useMutation()\` for server functions
+- \`useLumioAction()\` for platform actions
+- \`ctx.fetch()\` in handler-based server functions for external APIs
+
+### Token refresh failures
+The SDK auto-refreshes \`lm_ext_*\` tokens via postMessage. The Supervisor mediates refresh requests. If refreshes fail:
+1. Check the parent window is the Lumio dashboard/overlay (not standalone)
+2. Verify the extension is still installed
+3. Check network connectivity to the Lumio API
+
+### Supervisor blocked messages (\`SUPERVISOR_BLOCKED\`)
+The Supervisor validates all postMessage traffic between Extension Runtime and Host. If you see this error:
+1. Do not post messages directly from extension code to \`window.parent.parent\` (Host) \u2014 always use SDK hooks
+2. Verify the extension iframe is loaded inside \`supervisor.extension.lumio.vision\`, not directly in the Host
+3. Check that the message schema matches the \`@zaflun/lumio-protocol\` wire format (SDK handles this automatically)
+
+### Worker creation failures (\`WORKER_CREATION_FAILED\`)
+The V8 isolate Web Worker for server functions failed to start:
+1. Run \`lumio build\` locally and check for TypeScript/syntax errors in \`server/functions.ts\`
+2. Verify the server functions bundle is under the size limit
+3. Check \`lumio logs\` for the underlying JS error from the Worker initializer
+
+### Storage DOMException errors (\`STORAGE_DOM_EXCEPTION\`)
+\`localStorage\` and \`sessionStorage\` are blocked on the Extension Runtime origin (\`ext.lumio.vision\`):
+1. Replace all \`localStorage.setItem\` / \`localStorage.getItem\` calls with \`useExtensionStorage()\`
+2. Replace all \`sessionStorage\` usage with \`useVisionState()\` for transient values
+3. For server-side persistence, use \`ctx.db\` in server functions
+
+### Short-ID slug format issues (\`SLUG_FORMAT_INVALID\`)
+Extension slugs use a short-ID prefix format (\`k8f2x-my-extension\`):
+1. Do not manually edit the \`slug\` field in \`lumio.config.json\`
+2. The slug is auto-generated by \`lumio init\` and must not be changed
+3. If the slug is wrong, create a new extension via \`lumio init\` (slug is immutable after registration)
+
+## Debug Tools
+
+### \`lumio dev\` console
+Press \`e\` to emit test events (chat message, follow, sub, etc.)
+
+### \`lumio logs\`
+Stream server function execution logs in real-time:
+\`\`\`bash
+lumio logs                    # All logs
+lumio logs --filter addItem   # Filter by function name
+lumio logs --level error      # Errors only
+\`\`\`
+
+### Browser DevTools
+Open the extension iframe's DevTools (right-click -> Inspect Frame) to see:
+- Console logs from extension code
+- Network requests (should be empty \u2014 all communication via postMessage)
+- \`postMessage\` events in the Console
+`;
+
+// src/install.ts
+var SKILL_FILES = [
+  { filename: "SKILL.md", content: skillContent },
+  { filename: "components.md", content: componentsContent },
+  { filename: "server-functions.md", content: serverFunctionsContent },
+  { filename: "cli-workflows.md", content: cliWorkflowsContent },
+  { filename: "auth.md", content: authContent },
+  { filename: "runtime-scopes.md", content: runtimeScopesContent },
+  { filename: "best-practices.md", content: bestPracticesContent },
+  { filename: "troubleshooting.md", content: troubleshootingContent }
+];
+var geminiContent = `## Lumio Extension SDK
+
+This project is a Lumio extension. Read \`.lumio/skills/SKILL.md\` for the full SDK reference.
+
+Key files:
+- \`.lumio/skills/components.md\` \u2014 UI components
+- \`.lumio/skills/server-functions.md\` \u2014 Server functions
+- \`.lumio/skills/cli-workflows.md\` \u2014 CLI commands
+- \`.lumio/skills/auth.md\` \u2014 Authentication
+`;
+var agentsContent = `## Lumio Extension SDK
+
+This project is a Lumio extension built with \`@zaflun/lumio-sdk\`.
+Read \`.lumio/skills/SKILL.md\` for the complete SDK reference including components, hooks, server functions, and CLI commands.
+`;
+var windsurfContent = `Read .lumio/skills/SKILL.md for Lumio Extension SDK conventions.
+This project uses @zaflun/lumio-sdk for components and hooks, and @zaflun/lumio-cli for development.
+`;
+var copilotContent = `See .lumio/skills/SKILL.md for Lumio Extension SDK conventions.
+`;
+var ROOT_FILES = [
+  { filename: "GEMINI.md", content: geminiContent },
+  { filename: "AGENTS.md", content: agentsContent },
+  { filename: ".windsurfrules", content: windsurfContent },
+  { filename: ".github/copilot-instructions.md", content: copilotContent }
+];
+function installSkillFiles(targetDir) {
+  const skillsDir = join(targetDir, ".lumio", "skills");
+  if (!existsSync(skillsDir)) {
+    mkdirSync(skillsDir, { recursive: true });
+  }
+  for (const file of SKILL_FILES) {
+    writeFileSync(join(skillsDir, file.filename), file.content, "utf-8");
+  }
+  for (const file of ROOT_FILES) {
+    const filePath = join(targetDir, file.filename);
+    const fileDir = join(filePath, "..");
+    if (!existsSync(fileDir)) {
+      mkdirSync(fileDir, { recursive: true });
+    }
+    writeFileSync(filePath, file.content, "utf-8");
+  }
+}
+
+export {
+  SKILL_FILES,
+  ROOT_FILES,
+  installSkillFiles
+};