@zaflun/lumio-agent-skill 0.1.0 → 0.4.0

package/dist/bin/lumio-skills.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   installSkillFiles
-} from "../chunk-I2USQPPS.js";
+} from "../chunk-SSYJXSJX.js";
 
 // src/bin/lumio-skills.ts
 import { resolve } from "path";

package/dist/{chunk-I2USQPPS.js → chunk-SSYJXSJX.js}

@@ -13,7 +13,7 @@ Lumio Extensions are sandboxed React apps that run inside a 3-layer iframe sandb
 
 \`\`\`
 3-Layer Sandbox:
-  Host (lumio.vision / OBS browser source)
+  Host (lumio.vision / 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)
@@ -23,7 +23,7 @@ Lumio Extensions are sandboxed React apps that run inside a 3-layer iframe sandb
 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/layer.tsx              <- Stream 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)
@@ -52,7 +52,7 @@ Extension Project:
 | Target | Where | Purpose |
 |--------|-------|---------|
 | \`editor\` | Dashboard overlay editor sidebar | Config UI, settings, content management |
-| \`layer\` | OBS Browser Source (transparent) | Visual overlay in stream |
+| \`layer\` | 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.
@@ -61,9 +61,8 @@ All three surfaces share storage via \`useExtensionStorage()\` \u2014 changes in
 
 \`\`\`json
 {
-  "$schema": "https://docs.lumio.vision/schemas/lumio.config.schema.json",
+  "$schema": "https://lumio.vision/schemas/lumio.config.schema.json",
   "extensionId": "uuid",
-  "slug": "k8f2x-my-extension",
   "name": "My Extension",
   "description": "Description",
   "category": "widget",
@@ -77,12 +76,10 @@ All three surfaces share storage via \`useExtensionStorage()\` \u2014 changes in
   },
   "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 }
-    ]
-  }
+  "config_schema": [
+    { "key": "title", "type": "string", "label": "Widget Title", "default_value": "My Widget", "required": true },
+    { "key": "showBorder", "type": "boolean", "label": "Show Border", "default_value": true, "required": false }
+  ]
 }
 \`\`\`
 
@@ -147,7 +144,7 @@ lumio deploy
 
 **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).
+On the layer surface: input components become read-only (buttons hidden, toggles show on/off text).
 
 See \`components.md\` for full props and examples.
 
@@ -164,7 +161,7 @@ See \`components.md\` for full props and examples.
 | \`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\` |
+| \`useLumioAction(action)\` | \`{ 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 |
@@ -200,27 +197,122 @@ export const fetchScores = action({
 **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", {});
+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.
 
+## Bot Modules
+
+Extensions with category \`bot_module\` register handler-based server functions that respond to chat messages and platform events. Bot module handlers use six trigger types.
+
+### Handler Types
+
+| Handler | Trigger | Description |
+|---------|---------|-------------|
+| \`command(prefix, handler)\` | Chat command (e.g. \`!rank\`) | Fires when a message starts with the prefix |
+| \`keyword(words, handler)\` | Keyword match | Fires when a message contains any listed keyword |
+| \`pattern(regex, handler)\` | Regex match | Fires when a message matches the regex |
+| \`event(type, handler)\` | Platform event | Fires on a specific event (e.g. \`twitch:follower\`) |
+| \`timer(name, intervalSecs, handler)\` | Recurring timer | Fires every N seconds. Name must be unique per extension. |
+| \`moderate(handler)\` | Every message | Runs on every chat message for moderation decisions |
+
+### Handler Context
+
+Bot module handlers receive an extended \`ctx\` with chat-specific properties:
+
+\`\`\`typescript
+import { command } from "@zaflun/lumio-sdk/server";
+
+export const rankCmd = command("!rank", {
+  handler: async (ctx, message) => {
+    // ctx.user \u2014 chat user who sent the message
+    //   { platform, platform_user_id, display_name, roles }
+    //   roles: { moderator, vip, subscriber, broadcaster }
+
+    // ctx.auth \u2014 extension identity
+    //   { userId, accountId, extensionId, installId }
+
+    // ctx.cache \u2014 in-memory KV cache scoped to install (TTL-based)
+    await ctx.cache.set("last_rank_user", ctx.user.display_name, { ttl: 300 });
+    const cached = await ctx.cache.get("last_rank_user");
+
+    // ctx.defer() \u2014 schedule a follow-up after handler returns
+    ctx.defer(async () => {
+      await ctx.db.insert("rank_log", { user: ctx.user.display_name });
+    });
+
+    return { action: "send_message", message: \`@\${ctx.user.display_name} your rank is Gold!\` };
+  },
+});
+\`\`\`
+
+### \`ctx.user\` vs \`ctx.auth\`
+
+- \`ctx.user\` is the **chat user** who triggered the handler (their platform identity, display name, and role flags). Only available in bot module handlers.
+- \`ctx.auth\` is the **extension identity** (which extension, which install, which account). Available in all server functions.
+
+### Timer Naming
+
+Timer names must be unique within the extension. The name is used as the timer's identity for scheduling and deduplication. Use descriptive names:
+
+\`\`\`typescript
+timer("ad_reminder", 900, { handler: async (ctx) => { ... } });    // Good
+timer("t1", 900, { handler: async (ctx) => { ... } });             // Bad \u2014 unclear
+\`\`\`
+
+### \`ctx.cache\`
+
+The cache is an in-memory key-value store scoped to the extension install. Use it for rate limiting, cooldowns, and short-lived state that does not need to survive Worker restarts.
+
+\`\`\`typescript
+// Set with TTL (seconds)
+await ctx.cache.set("cooldown:ban:" + userId, "1", { ttl: 60 });
+
+// Get (returns null if expired or missing)
+const val = await ctx.cache.get("cooldown:ban:" + userId);
+
+// Delete
+await ctx.cache.delete("cooldown:ban:" + userId);
+\`\`\`
+
+### \`ctx.defer()\`
+
+Schedule work to run after the handler returns its response. Useful for logging, analytics, or secondary actions that should not delay the primary response.
+
+\`\`\`typescript
+export const modCheck = moderate({
+  handler: async (ctx, message) => {
+    if (isToxic(message.text)) {
+      ctx.defer(async () => {
+        await ctx.db.insert("mod_log", {
+          user: ctx.user.platform_user_id,
+          action: "timeout",
+          reason: "toxic message",
+        });
+      });
+      return { action: "timeout", duration: 300, message: "Please be respectful." };
+    }
+    return { action: "none" };
+  },
+});\`\`\`
+
 ## CLI Commands
 
 12 commands provided by \`@zaflun/lumio-cli\`:
@@ -307,7 +399,7 @@ addItem({ text: "New item" });
 
 ### Lumio actions
 \`\`\`tsx
-const { execute } = useLumioAction("chat:send", {});
+const { execute } = useLumioAction("chat:send");
 execute({ message: "Hello from my extension!" });
 \`\`\`
 
@@ -475,7 +567,7 @@ import { Image } from "@zaflun/lumio-sdk";
 
 ## 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.
+**Important:** On the layer surface, all input components become read-only. Buttons are hidden, toggles show "On"/"Off" text, dropdowns show the selected value.
 
 ### Button
 
@@ -655,7 +747,7 @@ const exitAnim = useAnimation("fade-out", { duration: 200 });
 
 **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
+- Keep animation durations short on the layer surface (< 500ms) to avoid frame drops
 - Avoid animating layout-affecting properties (\`width\`, \`height\`) on the layer; prefer \`opacity\` and \`transform\`
 
 ## VisionStyle
@@ -775,15 +867,12 @@ For complex logic that cannot be expressed declaratively. Runs in V8 isolate san
 \`\`\`typescript
 import { query, mutation, action, v } from "@zaflun/lumio-sdk/server";
 
-// Read-only query
-export const getLeaderboard = query({
-  args: { limit: v.number().optional() },
+// Read-only query \u2014 look up a single row by ID
+export const getScore = query({
+  args: { id: v.string() },
   handler: async (ctx, args) => {
-    const rows = await ctx.db.get("scores", {
-      order: { score: "desc" },
-      limit: args.limit ?? 10,
-    });
-    return rows;
+    const row = await ctx.db.get("scores", args.id);
+    return row;
   },
 });
 
@@ -820,7 +909,7 @@ Handler-based functions run inside a V8 isolate Web Worker. The \`ctx\` object p
 
 | Property | Description |
 |----------|-------------|
-| \`ctx.db.get(table, options?)\` | Read rows from extension DB schema |
+| \`ctx.db.get(table, id)\` | Read a single row by ID 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 |
@@ -856,19 +945,19 @@ Extension Actions let extensions trigger Lumio platform capabilities on behalf o
 import { useLumioAction } from "@zaflun/lumio-sdk";
 
 // Send a chat message on the connected platform
-const { execute: sendChat, isLoading, error } = useLumioAction("chat:send", {});
+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", {});
+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", {});
+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", {});
+const { execute: updateLayer } = useLumioAction("overlay:update_layer");
 updateLayer({ layerId: "uuid", visible: true });
 \`\`\`
 
@@ -877,10 +966,14 @@ updateLayer({ layerId: "uuid", visible: true });
 | Action | Permission required | Description |
 |--------|--------------------|----|
 | \`chat:send\` | \`chat:send\` | Send chat message on connected platform |
+| \`chat:delete\` | \`chat:delete\` | Delete a chat message |
 | \`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:set_source_visible\` | \`obs:control\` | Show or hide an OBS source |
+| \`obs:start_stream\` | \`obs:control\` | Start OBS streaming |
+| \`obs:stop_stream\` | \`obs:control\` | Stop OBS streaming |
 | \`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 |
@@ -895,6 +988,129 @@ updateLayer({ layerId: "uuid", visible: true });
 | \`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.
+
+## Bot Module Handlers
+
+Extensions with category \`bot_module\` export handler wrappers that register triggers. Each wrapper defines when the handler fires and what context it receives.
+
+### \`command(prefix, options)\`
+
+Fires when a chat message starts with the given prefix.
+
+\`\`\`typescript
+import { command } from "@zaflun/lumio-sdk/server";
+
+export const hello = command("!hello", {
+  handler: async (ctx, message) => {
+    return { action: "send_message", message: \`Hello @\${ctx.user.display_name}!\` };
+  },
+});
+\`\`\`
+
+### \`keyword(words, options)\`
+
+Fires when a chat message contains any of the listed keywords (case-insensitive).
+
+\`\`\`typescript
+import { keyword } from "@zaflun/lumio-sdk/server";
+
+export const giveaway = keyword(["giveaway", "enter", "join"], {
+  handler: async (ctx, message) => {
+    await ctx.db.insert("entries", { user_id: ctx.user.platform_user_id });
+    return { action: "send_message", message: \`@\${ctx.user.display_name} you are entered!\` };
+  },
+});
+\`\`\`
+
+### \`pattern(regex, options)\`
+
+Fires when a chat message matches the given regex.
+
+\`\`\`typescript
+import { pattern } from "@zaflun/lumio-sdk/server";
+
+export const scoreParser = pattern(/^!score\\s+(\\w+)\\s+(\\d+)$/, {
+  handler: async (ctx, message, matches) => {
+    const [, game, score] = matches;
+    await ctx.db.insert("scores", { game, score: parseInt(score, 10), user: ctx.user.display_name });
+    return { action: "send_message", message: \`Score recorded: \${game} = \${score}\` };
+  },
+});
+\`\`\`
+
+### \`event(eventType, options)\`
+
+Fires on a platform event. The \`eventType\` is a \`LumioEventType\` string.
+
+\`\`\`typescript
+import { event } from "@zaflun/lumio-sdk/server";
+
+export const welcomeFollower = event("twitch:follower", {
+  handler: async (ctx, eventData) => {
+    return { action: "send_message", message: \`Welcome @\${eventData.user_name}! Thanks for the follow!\` };
+  },
+});
+\`\`\`
+
+### \`timer(name, intervalSecs, options)\`
+
+Fires on a recurring interval. The name must be unique within the extension.
+
+\`\`\`typescript
+import { timer } from "@zaflun/lumio-sdk/server";
+
+export const reminder = timer("social_reminder", 900, {
+  handler: async (ctx) => {
+    return { action: "send_message", message: "Follow us on Twitter! twitter.com/example" };
+  },
+});
+\`\`\`
+
+### \`moderate(options)\`
+
+Runs on every incoming chat message. Used for moderation decisions.
+
+\`\`\`typescript
+import { moderate } from "@zaflun/lumio-sdk/server";
+
+export const toxicFilter = moderate({
+  handler: async (ctx, message) => {
+    const toxicScore = await analyzeToxicity(message.text);
+    if (toxicScore > 0.9) {
+      return { action: "timeout", duration: 600, message: "Please keep chat respectful." };
+    }
+    if (toxicScore > 0.7) {
+      return { action: "delete", message: "Message removed by auto-mod." };
+    }
+    return { action: "none" };
+  },
+});
+\`\`\`
+
+### Handler Return Actions
+
+All bot module handlers return an action object:
+
+| Action | Fields | Description | Permission required |
+|--------|--------|-------------|---------------------|
+| \`send_message\` | \`message\` | Send a chat message | \`chat:send\` |
+| \`delete\` | \`message?\` | Delete the triggering message | \`chat:delete\` |
+| \`timeout\` | \`duration\`, \`message?\` | Timeout the user (seconds) | \`chat:ban\` |
+| \`ban\` | \`message?\` | Ban the user | \`chat:ban\` |
+| \`none\` | \u2014 | Take no action | \u2014 |
+
+The extension must declare the matching permission in \`lumio.config.json\`. For example, a moderation module that bans users needs \`"permissions": ["chat:ban"]\`.
+
+### Bot Module Permission Table
+
+| Permission | Grants | Review level |
+|-----------|--------|--------------|
+| \`chat:send\` | Send chat messages | Standard |
+| \`chat:read\` | Read incoming chat messages | Standard |
+| \`chat:delete\` | Delete chat messages | Enhanced |
+| \`chat:ban\` | Ban, unban, and timeout users | Enhanced |
+| \`events:read\` | Subscribe to platform events | Standard |
+| \`events:write\` | Emit custom events | Standard |
 `;
 
 // src/content/cli-workflows.ts
@@ -1177,7 +1393,7 @@ The Lumio auth system has 9 token types:
 | 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 |
+| 5 | \`lm_overlay_\` | Overlay Token | Permanent | Per-overlay 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 |
@@ -1287,7 +1503,7 @@ var runtimeScopesContent = `# Runtime Scopes
 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)
+Host (lumio.vision / 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
@@ -1325,7 +1541,7 @@ Data is scoped to a specific extension installation within a specific overlay.
 defineTable({...}).storage("instance")
 \`\`\`
 
-- Filtered by: \`_account_id\` + \`_overlay_id\`
+- Filtered by: \`_account_id\` + \`_overlay_id\` + \`_install_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
 
@@ -1383,7 +1599,7 @@ Each scope maps to automatic WHERE clauses:
 
 \`\`\`sql
 -- instance scope:
-SELECT * FROM ext_{id}.items WHERE _account_id = $1 AND _overlay_id = $2
+SELECT * FROM ext_{id}.items WHERE _account_id = $1 AND _overlay_id = $2 AND _install_id = $3
 
 -- overlay scope:
 SELECT * FROM ext_{id}.items WHERE _account_id = $1 AND _overlay_id = $2
@@ -1420,7 +1636,7 @@ var bestPracticesContent = `# Best Practices
 
 ### 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
+- Keep the layer surface minimal \u2014 it runs in an Browser Source at 30/60 fps
 - Return \`null\` from components when they should be invisible (do not use \`display: none\`)
 
 ## UX Patterns
@@ -1471,7 +1687,7 @@ Wrap editor settings in \`CompactView\` for consistent styling with the Lumio da
 \`\`\`
 
 ### Transparent backgrounds on layer
-The layer surface should have a transparent background so it composites correctly over the stream in OBS:
+The layer surface should have a transparent background so it composites correctly over the stream:
 
 \`\`\`tsx
 // layer.tsx \u2014 no background, content floats over stream
@@ -1485,23 +1701,19 @@ Use \`config_schema\` in \`lumio.config.json\` for user-customizable settings. T
 
 \`\`\`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"
-      }
-    ]
-  }
+  "config_schema": [
+    { "key": "title", "type": "string", "label": "Widget Title", "default_value": "My Widget", "required": true },
+    { "key": "maxItems", "type": "number", "label": "Max Items", "default_value": 10, "required": false },
+    { "key": "showBorder", "type": "boolean", "label": "Show Border", "default_value": true, "required": false },
+    {
+      "key": "theme",
+      "type": "select",
+      "label": "Color Theme",
+      "options": ["dark", "light"],
+      "default_value": "dark",
+      "required": false
+    }
+  ]
 }
 \`\`\`
 
@@ -1521,7 +1733,7 @@ const maxItems = config.maxItems ?? 10;
 
 - 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
+- Keep durations short on the layer (< 400ms). Longer animations cause visible frame drops in the Browser Source at 30/60 fps
 - Prefer animating \`opacity\` and \`transform\` (GPU-composited) over \`width\`, \`height\`, \`margin\`, \`padding\` (layout-triggering)
 
 \`\`\`tsx
@@ -1560,6 +1772,120 @@ For beta testing before public launch:
 | 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 |
+
+## Bot Module Security
+
+### Rate Limiting Awareness
+
+Bot module handlers are subject to the same rate limits as other server functions. Plan for these limits in moderation logic:
+
+- Actions (with fetch): 20/min per installation
+- Mutations: 50/min per installation
+- Storage writes: 200/min per installation
+
+If your module processes high-volume chat, avoid issuing a moderation action on every message. Use \`ctx.cache\` for cooldowns:
+
+\`\`\`tsx
+export const spamGuard = moderate({
+  handler: async (ctx, message) => {
+    const key = \`cooldown:\${ctx.user.platform_user_id}\`;
+    if (await ctx.cache.get(key)) return { action: "none" };
+
+    if (isSpam(message.text)) {
+      await ctx.cache.set(key, "1", { ttl: 30 });
+      return { action: "timeout", duration: 60, message: "Spam detected." };
+    }
+    return { action: "none" };
+  },
+});
+\`\`\`
+
+### Moderation Escalation Pattern
+
+For moderation modules, escalate actions progressively rather than jumping to bans. Track offense counts in the extension database:
+
+\`\`\`tsx
+export const escalatingMod = moderate({
+  handler: async (ctx, message) => {
+    if (!isViolation(message.text)) return { action: "none" };
+
+    const offenses = await ctx.db.get("offenses", ctx.user.platform_user_id);
+    const count = (offenses?.count ?? 0) + 1;
+    await ctx.db.patch("offenses", ctx.user.platform_user_id, { count });
+
+    if (count >= 3) return { action: "ban", message: "Repeated violations." };
+    if (count === 2) return { action: "timeout", duration: 600, message: "Second warning." };
+    return { action: "delete", message: "First warning: message removed." };
+  },
+});
+\`\`\`
+
+### User Override Preservation
+
+Account owners can override trigger configuration (command prefixes, keywords, regex patterns) via the dashboard. Always read trigger config from the handler context rather than hardcoding values:
+
+\`\`\`tsx
+// Good: reads overridable config
+export const customCmd = command("!points", {
+  handler: async (ctx, message) => {
+    // The prefix "!points" is the default \u2014 users can override it in dashboard
+    // Handler logic stays the same regardless of the configured prefix
+    return { action: "send_message", message: "You have 100 points!" };
+  },
+});
+\`\`\`
+
+Extension developers should document which triggers are overridable in the extension's description so account owners know what they can customize.
+
+### Cache-First + Defer Pattern
+
+For handlers that need fast responses but also need to persist data, use \`ctx.cache\` for the immediate check and \`ctx.defer()\` to write to the database asynchronously:
+
+\`\`\`tsx
+export const rateLimitedGreet = command("!greet", {
+  handler: async (ctx, message) => {
+    const cacheKey = \`greeted:\${ctx.user.platform_user_id}\`;
+
+    // Fast path: check cache
+    if (await ctx.cache.get(cacheKey)) {
+      return { action: "send_message", message: "You already greeted today!" };
+    }
+
+    // Set cache immediately (fast)
+    await ctx.cache.set(cacheKey, "1", { ttl: 86400 });
+
+    // Defer the DB write (does not block response)
+    ctx.defer(async () => {
+      await ctx.db.insert("greet_log", {
+        user_id: ctx.user.platform_user_id,
+        greeted_at: new Date().toISOString(),
+      });
+    });
+
+    return { action: "send_message", message: \`Hello @\${ctx.user.display_name}!\` };
+  },
+});
+\`\`\`
+
+### Exempt Role Support
+
+Moderation modules should respect the account's exempt role configuration. The exempt roles (moderator, VIP, subscriber) are passed to the handler via \`ctx.user.roles\`. Check them before taking action:
+
+\`\`\`tsx
+export const linkFilter = moderate({
+  handler: async (ctx, message) => {
+    // Respect exempt roles \u2014 do not moderate mods/VIPs
+    if (ctx.user.roles.moderator || ctx.user.roles.vip) {
+      return { action: "none" };
+    }
+
+    if (containsLink(message.text)) {
+      return { action: "delete", message: "Links are not allowed." };
+    }
+    return { action: "none" };
+  },
+});
+\`\`\`
 `;
 
 // src/content/troubleshooting.ts

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   ROOT_FILES,
   SKILL_FILES,
   installSkillFiles
-} from "./chunk-I2USQPPS.js";
+} from "./chunk-SSYJXSJX.js";
 export {
   ROOT_FILES,
   SKILL_FILES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaflun/lumio-agent-skill",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "AI agent skill files for building Lumio Extensions",
   "type": "module",
   "main": "dist/index.js",