@zaflun/lumio-agent-skill 0.5.3 → 0.6.5

package/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+All notable changes to `@zaflun/lumio-agent-skill` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.6.5
+
+### Added
+
+- **`CHANGELOG.md` in the package** — the npm tarball ships this changelog.
+- **Shopify events** — `SKILL.md` lists `shopify:order`,
+  `shopify:order_paid` and `shopify:product` (65 event types in total) and
+  describes their payloads: the store in `shop { domain, label }`, order
+  totals and line items only as the store's settings allow, and
+  `customer_display` only with the buyer's consent, to be rendered as text,
+  never as HTML.
+- **Which URLs the host loads** — `components.md` explains that `<Image>`,
+  `<img src>` and `<a href>` load only from an `https` host in
+  `egress.allowHosts`, a `data:image/*` URL, the Lumio page, the extension's
+  runtime origin, or a platform avatar or emote URL served by Lumio's image
+  proxy. Any other URL renders an empty placeholder, and `style` values with
+  `url()` are dropped.
+
+## 0.6.2
+
+### Changed
+
+- **No `interactive` surface** — the skill files describe two surfaces,
+  editor and layer. Viewer input (votes, games) goes through chat commands
+  and channel point rewards handled by a bot module, which writes `ctx.db`
+  and calls `ctx.realtime.push`; the layer and editor receive it with
+  `useRealtime(topic, cb)`. The `interactive` template and target are gone
+  from the CLI and auth docs.
+- **`useExtensionStorage(key, initialValue)`** — every example uses the
+  one-key-per-call signature instead of a whole-storage object with spread
+  updates.
+- **Server functions** — they run in a V8 isolate on the Bot Module Worker
+  with a 5-second limit per call. `ctx.realtime.push` and `useRealtime` are
+  documented, `ctx.fetch` refuses every host in server functions, and
+  `secret()` works only in `action()` handlers. `lumio build` writes
+  `dist/functions.json` from `server/functions.ts`; declarative queries take
+  `orderBy`, `orderDir`, `limit` and `offset`.
+- **`lumio env` replaces `lumio secrets`** — set, list and delete extension
+  secrets, with the key and value rules. Bot-module handlers read them with
+  `await ctx.secrets.get("KEY")`; server functions and automation nodes get
+  `null`.
+- **Event list** — 62 event types: `twitch:gift_sub` is `twitch:gift`, and
+  `twitch:reward_status`, `twitch:reward_add`, `twitch:reward_update` and
+  `twitch:reward_remove` are added. `useLumioEvent()` examples show the typed
+  payload.
+- **Developer limits link** — points to
+  `/dashboard/settings/developer/limits`.
+
+## 0.5.3
+
+### Added
+
+- **Bundled sounds** — the `sounds` array in `lumio.config.json`, supported
+  formats and default limits.
+
+### Changed
+
+- **Per-extension runtime origin** — the skill files describe the Extension
+  Runtime on `<label>.runtime.ext.lumio.vision` (one origin per extension)
+  and the Supervisor on `supervisor.ext.lumio.vision`.
+- **Extension actions** — the action list matches what the Lumio API
+  dispatches: chat send and delete, the OBS scene, source and stream
+  actions, `events:emit` and `overlay:update_layer`, each with its own
+  permission. Example parameters use the snake_case payloads
+  (`scene_name`, `event_type`, `layer_id`, …).
+- **Event list** — 58 event types, including Kick resubs, KICKs, rewards and
+  stream updates, Twitch end and lock events, `streamelements:tip` and
+  `chat:message`.
+- **`lumio build`** — documents the JS bundles, the bot-module server bundle,
+  Tailwind compilation and the pre-flight checks before upload.
+
+## 0.5.0
+
+### Added
+
+- **Automation nodes** — `defineAutomationAction`, `defineAutomationTrigger`
+  and `defineAutomationLogic` handlers, the `lumio init` automation templates
+  and the `lumio dev` automation simulator.
+- **Editor and picker components** — the 14 `Editor*` components with
+  `useEditorAction`, and `IconPicker`, `IconDisplay` and `useIconPicker`.
+- **Config schema field types** — the extended field types, `visible_when`,
+  groups, and `designer_schema` for the full-page designer.
+
+## 0.4.0
+
+### Added
+
+- **Bot modules** — the `command`, `keyword`, `pattern`, `event`, `timer`
+  and `moderate` handlers, their return actions and permissions, the handler
+  context (`ctx.user`, `ctx.cache`, `ctx.defer()`), and best practices for
+  rate limits, moderation escalation, overridable triggers and exempt roles.
+
+### Changed
+
+- **OBS wording** — the layer is described as running in a Browser Source,
+  not specifically OBS.
+
+## 0.2.0
+
+### Changed
+
+- **`config_schema` is an array** of fields with `default_value` and
+  `required` in every example, and the config example uses the
+  `https://lumio.vision/schemas/lumio.config.schema.json` schema URL.
+- **`useLumioAction(action)`** — examples drop the second argument; the
+  action list adds `chat:delete` and the OBS source and stream actions.
+- **`instance` storage scope** — filtered by install as well as account and
+  overlay.
+
+## 0.1.0
+
+### Added
+
+- **Initial release** — `npx lumio-skills add` writes eight skill files to
+  `.lumio/skills/` (`SKILL.md`, components, server functions, CLI workflows,
+  auth, runtime scopes, best practices, troubleshooting) and pointer files
+  for AI assistants (`AGENTS.md`, `GEMINI.md`, `.windsurfrules`,
+  `.github/copilot-instructions.md`). `installSkillFiles`, `SKILL_FILES` and
+  `ROOT_FILES` are exported for programmatic use.

package/README.md

@@ -21,7 +21,7 @@ This creates `.lumio/skills/` in your project with reference docs, plus agent co
 | `server-functions.md` | Server function patterns, ctx API |
 | `cli-workflows.md` | All 12 CLI commands |
 | `auth.md` | Token types, permissions |
-| `runtime-scopes.md` | Editor/layer/interactive surfaces |
+| `runtime-scopes.md` | Storage scopes (instance/overlay/account/global) |
 | `best-practices.md` | Performance, security, UX |
 | `troubleshooting.md` | Common errors and fixes |
 

package/dist/bin/lumio-skills.js

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

package/dist/{chunk-TKNV5K6F.js → chunk-LKWF2Y7K.js}

@@ -16,7 +16,7 @@ Lumio Extensions are sandboxed React apps that run inside a 3-layer iframe sandb
   Host (lumio.vision / browser source)
     \u2514\u2500\u2500 Supervisor iframe (supervisor.ext.lumio.vision)
           \u2514\u2500\u2500 Extension Runtime iframe (<label>.runtime.ext.lumio.vision)
-                \u2514\u2500\u2500 Web Worker (server function execution)
+                \u2514\u2500\u2500 Web Worker (the extension's UI code)
 \`\`\`
 
 \`\`\`
@@ -24,7 +24,6 @@ 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              <- 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)
 \`\`\`
@@ -34,7 +33,7 @@ Extension Project:
 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)
+5. Server functions run on the Lumio backend (Bot Module Worker) in a V8 isolate (256 MB memory, 5 s per call); a handler's \`ctx.realtime.push(topic, payload)\` reaches every surface of the install through \`useRealtime(topic, cb)\`
 6. Cross-frame messaging uses \`WorkerBridge\` (exported from \`@zaflun/lumio-sdk\`; replaces the legacy \`PostMessageBridge\`)
 
 **Key constraints:**
@@ -47,15 +46,16 @@ Extension Project:
 
 ## Core Concepts
 
-### Three Surfaces
+### Two Surfaces
 
 | Target | Where | Purpose |
 |--------|-------|---------|
 | \`editor\` | Dashboard overlay editor sidebar | Config UI, settings, content management |
 | \`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.
+Both surfaces share storage via \`useExtensionStorage()\` \u2014 changes in editor propagate to layer in real-time.
+
+**Viewer input** (votes, games) has no page of its own: viewers act through chat commands and channel point rewards. A bot-module handler \u2014 \`command("!vote", \u2026)\` or \`event("twitch:reward" | "kick:reward", \u2026)\` \u2014 writes \`ctx.db\` and calls \`ctx.realtime.push(topic, payload)\`; the layer and editor receive it with \`useRealtime(topic, cb)\`.
 
 ### lumio.config.json
 
@@ -99,7 +99,7 @@ All three surfaces share storage via \`useExtensionStorage()\` \u2014 changes in
 - \`"visibility": "unlisted"\` \u2014 accessible by direct link only
 - Private invite: grant \`free_access\` to specific accounts via dashboard
 
-**Bundled sounds:** Place audio files in \`dist/sounds/\` and declare them in the \`sounds\` array. Supported: MP3, WAV, OGG, WebM, M4A, AAC, FLAC. Default limits: 50 sounds per extension, 10 MB per file, 200 MB total storage (all admin-configurable). Developers can view limits at \`/account/developer/limits\` and request increases via a 4-step wizard. Requests are reviewed by admins in the admin app. Users cannot delete bundled sounds \u2014 uninstalling the extension removes them.
+**Bundled sounds:** Place audio files in \`dist/sounds/\` and declare them in the \`sounds\` array. Supported: MP3, WAV, OGG, WebM, M4A, AAC, FLAC. Default limits: 50 sounds per extension, 10 MB per file, 200 MB total storage (all admin-configurable). Developers can view limits at \`/dashboard/settings/developer/limits\` and request increases via a 4-step wizard. Requests are reviewed by admins in the admin app. Users cannot delete bundled sounds \u2014 uninstalling the extension removes them.
 
 **Revenue split:** Configurable per developer (default 70/30 developer/Lumio).
 
@@ -161,9 +161,9 @@ See \`components.md\` for full props and examples.
 
 | 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 |
+| \`useExtensionStorage(key, initialValue)\` | \`[value, setValue]\` | Persistent KV store, one key per call, synced across targets |
+| \`useVisionState(key, default)\` | \`[value, setValue]\` | Same contract as \`useExtensionStorage\` |
+| \`useExtensionContext()\` | \`{ extensionId, target, overlayId }\` | 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) |
@@ -171,10 +171,11 @@ See \`components.md\` for full props and examples.
 | \`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 |
+| \`useRealtime(topic, cb)\` | \`void\` | Receive \`ctx.realtime.push(topic, payload)\` messages of this install |
 | \`useAnimation(preset, options?)\` | \`animationProps\` | SDK animation presets for \`Animated\` component |
 | \`useIconPicker(options?)\` | \`{ isOpen, selected, open, close, select, clear, sources }\` | Headless state for custom icon picker UIs |
 
-**Important:** \`setStorage\` must always spread: \`setStorage({ ...storage, key: value })\`
+**Important:** \`useExtensionStorage\` always takes a key and an initial value \u2014 call it once per key. A setter replaces only its own key; spread only when you store an object under one key: \`setScore({ ...score, home: 2 })\`
 
 ## Server Functions
 
@@ -189,7 +190,7 @@ 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):
+**Handler-based** (V8 isolate on the Bot Module Worker, full control):
 \`\`\`typescript
 import { action, arg, v } from "@zaflun/lumio-sdk/server";
 export const fetchScores = action({
@@ -327,7 +328,7 @@ export const modCheck = moderate({
 | \`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 env\` | Manage extension secrets (\`set\` / \`list\` / \`delete\`) |
 | \`lumio team\` | Manage developer team members |
 | \`lumio config\` | Show/set CLI configuration |
 
@@ -342,7 +343,7 @@ See \`cli-workflows.md\` for detailed usage and examples.
 
 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).
+**\`editorOnly: true\`** on server functions restricts mutations to editor surface only (the layer cannot call them).
 
 See \`auth.md\` for all 9 token types and the full token lifecycle.
 
@@ -360,26 +361,27 @@ lumio deploy -> draft -> [Submit via dashboard] -> pending_review
 ### Editor + Layer sync
 \`\`\`tsx
 // editor.tsx
-const [storage, setStorage] = useExtensionStorage();
-<Toggle label="Show" checked={storage.visible ?? false}
-  onChange={(v) => setStorage({ ...storage, visible: v })} />
+const [visible, setVisible] = useExtensionStorage("visible", false);
+<Toggle label="Show" checked={visible} onChange={setVisible} />
 
 // layer.tsx
-const [storage] = useExtensionStorage();
-if (!storage.visible) return null;
-return <Text content={storage.text} />;
+const [visible] = useExtensionStorage("visible", false);
+const [text] = useExtensionStorage("text", "");
+if (!visible) return null;
+return <Text content={text} />;
 \`\`\`
 
 ### Live events
 \`\`\`tsx
-// eventType is LumioEventType \u2014 autocomplete shows all 58 valid event strings
-const event = useLumioEvent("twitch:follower");
-// event updates automatically when a new follower event arrives
+// eventType is LumioEventType \u2014 autocomplete shows all 65 valid event strings
+const event = useLumioEvent("twitch:cheer");
+// event updates automatically when a new cheer arrives; it is typed
+// LumioEventPayloadMap["twitch:cheer"] | null, so event?.bits is a number
 \`\`\`
 
-**All 58 event types** (\`LumioEventType\`):
+**All 65 event types** (\`LumioEventType\`):
 
-Twitch (23): \`twitch:follower\`, \`twitch:subscribe\`, \`twitch:gift_sub\`, \`twitch:resub\`, \`twitch:cheer\`, \`twitch:raid\`, \`twitch:reward\`, \`twitch:hype_train\`, \`twitch:hype_train_end\`, \`twitch:poll\`, \`twitch:poll_end\`, \`twitch:prediction\`, \`twitch:prediction_lock\`, \`twitch:prediction_end\`, \`twitch:goal\`, \`twitch:goal_end\`, \`twitch:ad_break\`, \`twitch:ban\`, \`twitch:unban\`, \`twitch:stream_online\`, \`twitch:stream_offline\`, \`twitch:stream_update\`, \`twitch:chat\`
+Twitch (27): \`twitch:follower\`, \`twitch:subscribe\`, \`twitch:gift\`, \`twitch:resub\`, \`twitch:cheer\`, \`twitch:raid\`, \`twitch:reward\`, \`twitch:reward_status\`, \`twitch:reward_add\`, \`twitch:reward_update\`, \`twitch:reward_remove\`, \`twitch:hype_train\`, \`twitch:hype_train_end\`, \`twitch:poll\`, \`twitch:poll_end\`, \`twitch:prediction\`, \`twitch:prediction_lock\`, \`twitch:prediction_end\`, \`twitch:goal\`, \`twitch:goal_end\`, \`twitch:ad_break\`, \`twitch:ban\`, \`twitch:unban\`, \`twitch:stream_online\`, \`twitch:stream_offline\`, \`twitch:stream_update\`, \`twitch:chat\`
 
 YouTube (10): \`youtube:subscribe\`, \`youtube:member\`, \`youtube:superchat\`, \`youtube:supersticker\`, \`youtube:gift_membership\`, \`youtube:gift_membership_received\`, \`youtube:poll\`, \`youtube:stream_online\`, \`youtube:stream_offline\`, \`youtube:chat\`
 
@@ -389,9 +391,11 @@ Spotify (12): \`spotify:track\`, \`spotify:play\`, \`spotify:pause\`, \`spotify:
 
 StreamElements (1): \`streamelements:tip\`
 
+Shopify (3): \`shopify:order\`, \`shopify:order_paid\`, \`shopify:product\`
+
 Cross-platform chat (1, fires for every platform): \`chat:message\`
 
-Kick events carry canonical top-level fields (\`user_id\`, \`user_login\`, \`user_name\`, \`avatarUrl\`, \`is_anonymous\`) plus the original Kick payload. \`kick:kicks\` has \`kicks\` (amount, like Twitch \`bits\`) and \`message\`; \`kick:reward\` / \`kick:reward_status\` have \`status\`, \`user_input\` and \`reward { id, title, cost, prompt }\`; \`kick:resub\` has \`cumulative_months\`.
+Kick events carry canonical top-level fields (\`user_id\`, \`user_login\`, \`user_name\`, \`avatarUrl\`, \`is_anonymous\`) plus the original Kick payload. \`kick:kicks\` has \`kicks\` (amount, like Twitch \`bits\`) and \`message\`; \`kick:reward\` / \`kick:reward_status\` have \`status\`, \`user_input\` and \`reward { id, title, cost, prompt }\`; \`kick:resub\` has \`cumulative_months\`. \`twitch:reward_status\` has the \`twitch:reward\` shape with \`status\` \`fulfilled\` / \`canceled\`. \`twitch:reward_add\` / \`_update\` / \`_remove\` carry the Twitch reward (\`id\`, \`title\`, \`cost\`, \`prompt\`, \`is_enabled\`, \`is_paused\`, \u2026); these three arrive live only (\`broadcast_only\`), never from the event history. Every \`shopify:*\` event names its store in \`shop { domain, label }\` (absent on events stored before stores carried it). \`shopify:order\` / \`shopify:order_paid\` carry \`order_number\`, \`name\`, \`financial_status\`, \`line_items\` and \`total_price\` / \`currency\` only as the store's settings allow, and \`customer_display\` only with the buyer's consent \u2014 untrusted buyer text, render it with \`<Text>\`, never as HTML. \`shopify:product\` has \`title\`, \`vendor\`, \`product_type\`, \`handle\`, \`image_url\`.
 
 ### Server queries
 \`\`\`tsx
@@ -421,7 +425,7 @@ const anim = useAnimation("slide-in", { duration: 300 });
 | \`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 |
+| \`EDITOR_ONLY\` | Mutation called from the layer | Remove \`editorOnly\` or restrict to editor |
 | \`SUPERVISOR_BLOCKED\` | Supervisor rejected a postMessage | Check message origin matches the extension's runtime origin (\`<label>.runtime.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) |
@@ -620,6 +624,8 @@ import { Image } from "@zaflun/lumio-sdk";
 - \`height?: number | string\`
 - \`style?: VisionStyle\`
 
+The host loads \`src\` only from an \`https\` host listed in \`egress.allowHosts\` (default port), a \`data:image/*\` URL, the Lumio page itself, the extension's runtime origin, or a Twitch/7TV/BTTV/FFZ/YouTube/Discord/Kick avatar or emote URL that Lumio's image proxy serves. Any other URL renders an empty placeholder. The same applies to \`<img src>\` and \`<a href>\`; \`style\` values with \`url()\` are dropped.
+
 ## Input Components
 
 **Important:** On the layer surface, all input components become read-only. Buttons are hidden, toggles show "On"/"Off" text, dropdowns show the selected value.
@@ -816,18 +822,18 @@ import { IconPicker, IconDisplay } from "@zaflun/lumio-sdk";
 import type { IconValue } from "@zaflun/lumio-sdk";
 
 // In editor.tsx \u2014 let the user pick an icon
-const [storage, setStorage] = useExtensionStorage();
+const [icon, setIcon] = useExtensionStorage<IconValue | null>("icon", null);
 
 <IconPicker
-  value={storage.icon ?? null}
-  onChange={(icon) => setStorage({ ...storage, icon })}
+  value={icon}
+  onChange={setIcon}
   sources={["lucide", "emoji", "emote", "upload"]}
   size="md"
   placeholder="Choose an icon..."
 />
 
 // In layer.tsx \u2014 render the selected icon
-<IconDisplay icon={storage.icon ?? null} size={32} />
+<IconDisplay icon={icon} size={32} />
 \`\`\`
 
 **IconPickerProps:**
@@ -950,9 +956,12 @@ import { queryRows, insertRow, patchRow, deleteRow, arg, filter } from "@zaflun/
 // Read all rows
 export const getItems = queryRows("items");
 
-// Read with filter
+// Read with filter, order and paging
 export const getDoneItems = queryRows("items", {
   filter: filter("done", "=", true),
+  orderBy: "created_at",
+  orderDir: "desc",
+  limit: arg("limit"),
 });
 
 // Insert a row (editorOnly: only callable from editor surface)
@@ -975,8 +984,10 @@ export const removeItem = deleteRow("items", arg("id"), { editorOnly: true });
 
 - \`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)
+- \`secret("KEY")\` \u2014 reads a server-side secret in \`action()\` handlers only; \`lumio build\` rejects it in declarative functions
+- \`filter(field, op, value)\` \u2014 query filter, \`op\` one of \`=\`, \`!=\`, \`>\`, \`>=\`, \`<\`, \`<=\`, \`like\`, \`in\`; pass a list for AND
+- \`queryRows\` options: \`filter\`, \`orderBy\`, \`orderDir\` (\`asc\`/\`desc\`), \`limit\` / \`offset\` (integer or \`arg()\`)
+- Definitions must be plain JSON: \`lumio build\` serialises every export of \`server/functions.ts\` to \`dist/functions.json\` and fails on anything else (keep helpers in another module)
 
 ## Handler-Based Functions
 
@@ -1006,45 +1017,48 @@ export const submitScore = mutation({
   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() },
+// Push a live update to every surface of the install (overlay, widget, editor)
+export const castVote = mutation({
+  args: { choice: 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();
+    await ctx.db.insert("votes", { choice: args.choice });
+    const votes = await ctx.db.list("votes");
+    ctx.realtime.push("poll:votes", { total: votes.length });
   },
 });
 \`\`\`
 
+Receive the push in any surface with \`useRealtime\`:
+
+\`\`\`tsx
+import { useRealtime } from "@zaflun/lumio-sdk";
+
+useRealtime<{ total: number }>("poll:votes", (payload) => setTotal(payload.total));
+\`\`\`
+
 ### Handler Context (\`ctx\`)
 
-Handler-based functions run inside a V8 isolate Web Worker. The \`ctx\` object provides the full sandbox API:
+Handler-based functions run in a V8 isolate on the Bot Module Worker (never in the API process or the browser). The \`ctx\` object:
 
 | Property | Description |
 |----------|-------------|
-| \`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 |
-| \`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 |
+| \`ctx.db.get(table, id)\` / \`list(table, filters?)\` | Read rows of the extension's tables (install's account only) |
+| \`ctx.db.insert(table, data)\` / \`patch\` / \`delete\` | Write rows |
+| \`ctx.realtime.push(topic, payload?)\` | Push \`{ topic, payload }\` to every rendered surface of the install (\`useRealtime\`). Topic: 1-64 chars of \`A-Z a-z 0-9 _ . : -\`; payload \u2264 16 KiB; \u2264 32 per call, 300 per install and minute. Sent after the handler returns, only if it did not throw |
+| \`ctx.cache\` / \`ctx.defer\` | Install-scoped cache and background jobs, as in bot modules |
+| \`ctx.secrets.get(key)\` | The extension's owner secret (\`lumio env set\`), or \`null\` |
+| \`ctx.fetch(url, options?)\` | Refuses every host in server functions (no egress allow-list yet); call external APIs from a bot module |
+| \`ctx.auth\` | \`{ userId, accountId, role }\` \u2014 \`userId\` is \`null\` for overlay, widget and extension tokens |
 
 ### Sandbox Limits
 
 | Limit | Value |
 |-------|-------|
 | Memory | 256 MB per invocation |
-| CPU timeout | 10 seconds |
+| Wall-clock timeout | 5 seconds per call |
 | Filesystem | No access |
-| Network | Only \`ctx.fetch()\` via egress allowlist (Supervisor-enforced) |
+| Network | None for server functions (\`ctx.fetch\` refuses every host) |
 | Dynamic code | Blocked (\`eval\`, \`Function\`, \`import()\`) |
-| Storage APIs | localStorage/sessionStorage blocked (separate origin) |
 
 ### Rate Limits
 
@@ -1145,7 +1159,8 @@ export default defineAutomationTrigger({
     const lastCheck = await ctx.cache.get("last_check") ?? "1970-01-01T00:00:00Z";
     const res = await ctx.fetch(
       \`https://api.example.com/events?since=\${lastCheck}\`,
-      { headers: { "Authorization": \`Bearer \${ctx.secrets.get("API_KEY")}\` } }
+      // Automation nodes get no secrets yet: the token comes from the node config.
+      { headers: { "Authorization": \`Bearer \${ctx.nodeConfig.apiToken}\` } }
     );
     const events = await res.json();
     await ctx.cache.set("last_check", new Date().toISOString());
@@ -1179,7 +1194,7 @@ export default defineAutomationLogic({
 | \`ctx.inputData\` | Action, Logic | Data from the upstream node |
 | \`ctx.fetch(url, options?)\` | All | HTTP request (egress allowlist enforced) |
 | \`ctx.cache.get(key)\` / \`ctx.cache.set(key, value, ttl?)\` | All | Per-installation KV cache (Redis, 1h default TTL) |
-| \`ctx.secrets.get(key)\` | All | Server-side secret |
+| \`ctx.secrets.get(key)\` | All | Not wired for automation nodes yet: always \`null\` |
 | \`ctx.db\` | All | Extension DB schema access |
 | \`ctx.auth\` | All | \`{ accountId }\` \u2014 account identity |
 | \`ctx.defer()\` | Action | Mark execution as async (returns 202, completes in background) |
@@ -1444,7 +1459,6 @@ Automation nodes always generate \`server/handler.ts\` (not \`server/functions.t
 | 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 |
 | Automation Action | server + editor | Yes | Automation workflow action node |
 | Automation Trigger | server + editor | Yes | Automation workflow trigger node |
@@ -1461,9 +1475,8 @@ 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
+# Editor: http://localhost:5173/editor
+# Layer:  http://localhost:5173/layer
 #
 # Mock events available. Press 'e' to emit a test event.
 # Press 'q' to quit.
@@ -1507,6 +1520,7 @@ lumio build
 # Output for widgets:
 #   Built: dist/editor.js
 #   Built: dist/layer.js
+#   Built: dist/server.js + dist/functions.json (if server: true)
 #   Compiled: dist/styles.css (if Tailwind detected)
 #   Archive: dist/source.tar.gz
 #
@@ -1517,10 +1531,11 @@ lumio build
 \`\`\`
 
 Build steps:
-1. UI targets (\`editor\`, \`layer\`, \`interactive\`, \`designer\`) \u2014 esbuild IIFE bundles
-2. Server handler (\`server: true\`) \u2014 compiles \`server/handler.ts\` to \`dist/server.js\` (ESM)
-3. CSS \u2014 Tailwind v4 auto-detected and compiled, or plain CSS copied
-4. Source archive \u2014 \`dist/source.tar.gz\`
+1. UI targets (\`editor\`, \`layer\`, \`designer\`) \u2014 esbuild IIFE bundles
+2. Server handler (\`server: true\`) \u2014 compiles \`server/handler.ts\` (or \`server/index.ts\`, else \`server/functions.ts\`) to \`dist/server.js\` (ESM)
+3. Functions manifest (\`server: true\`, not bot modules / automation nodes) \u2014 evaluates \`server/functions.ts\` and writes every export to \`dist/functions.json\` (\`{ version: 1, functions: { name: { kind, category, editorOnly, table?, \u2026 } } }\`; handlers become \`{ kind: "handler", category }\` stubs). Fails on a non-definition export, a non-JSON value, \`secret()\` in a declarative function, a table missing from \`server/schema.ts\`, or names that differ only in case. \`lumio deploy\` uploads it with the version.
+4. CSS \u2014 Tailwind v4 auto-detected and compiled, or plain CSS copied
+5. Source archive \u2014 \`dist/source.tar.gz\`
 
 Warns if \`CHANGELOG.md\` is missing.
 
@@ -1617,25 +1632,27 @@ lumio logs --filter fetchScores
 lumio logs --level error
 \`\`\`
 
-## lumio secrets
+## lumio env
 
-Manage server-side secrets used by handler-based server functions via \`ctx.secrets.get("KEY")\`.
+Manage the extension's secrets. Bot-module handlers read them via \`await ctx.secrets.get("KEY")\` (\`null\` when unset). Server functions and automation nodes do not get secrets yet (\`ctx.secrets.get\` returns \`null\` there).
 
 \`\`\`bash
-# Set a secret
-lumio secrets set ESPN_API_KEY abc123xyz
+# Set a secret (prompts with hidden input when VALUE is omitted)
+lumio env set ESPN_API_KEY
+
+# Non-interactive (CI): value from LUMIO_SECRET, keeps it out of shell history
+LUMIO_SECRET="$ESPN_API_KEY" lumio env set ESPN_API_KEY
 
 # List secret keys (values are never shown)
-lumio secrets list
+lumio env list
 # Output:
-# ESPN_API_KEY   (set 2026-05-19)
-# WEATHER_TOKEN  (set 2026-04-01)
+#   ESPN_API_KEY  (created 2026-05-19T00:00:00Z)
 
 # Delete a secret
-lumio secrets delete ESPN_API_KEY
+lumio env 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.
+Keys match \`^[A-Z0-9_]{1,64}$\`; values are 1 to 4096 bytes. A developer API key (\`lm_dev_\`) may manage secrets, so this works in CI. Secrets are stored encrypted (AES-256-GCM), one set per extension shared by every install, and are never returned by the API or exposed to the frontend or other extensions.
 
 ## lumio team
 
@@ -1711,7 +1728,7 @@ AuthContext::ExtensionToken {
     extension_id: Uuid,
     install_id: Uuid,
     account_id: Uuid,
-    target: "editor" | "layer" | "interactive",
+    target: "editor" | "layer",
 }
 \`\`\`
 
@@ -1752,7 +1769,7 @@ Widget tokens are suitable for persistent, public-facing embeds where session re
 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
+// Only callable from editor.tsx \u2014 layer.tsx gets 403
 export const addItem = insertRow("items", { text: arg("text") }, { editorOnly: true });
 
 // Callable from any surface
@@ -1912,8 +1929,8 @@ 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
+- Call \`useExtensionStorage(key, initialValue)\` once per value \u2014 each key loads, syncs and re-renders on its own
+- Debounce text inputs \u2014 every setter call is one storage write
 - Use \`useMemo\` and \`useCallback\` to avoid unnecessary re-renders
 
 ### Optimize server function calls
@@ -1938,22 +1955,21 @@ Always use \`useExtensionStorage()\` for state that should be visible on both ed
 
 \`\`\`tsx
 // editor.tsx \u2014 user configures
-const [storage, setStorage] = useExtensionStorage();
-<TextField label="Title" value={storage.title ?? ""}
-  onChange={(v) => setStorage({ ...storage, title: v })} />
+const [title, setTitle] = useExtensionStorage("title", "Default Title");
+<TextField label="Title" value={title} onChange={setTitle} />
 
 // layer.tsx \u2014 displays result
-const [storage] = useExtensionStorage();
-<Text content={storage.title ?? "Default Title"} variant="heading" />
+const [title] = useExtensionStorage("title", "Default Title");
+<Text content={title} variant="heading" />
 \`\`\`
 
 ### Graceful defaults
-Always provide sensible defaults using \`??\` (nullish coalescing). Storage might be empty on first load.
+Pass a sensible \`initialValue\` for every key. The hook returns it until the stored value has loaded, and for a key that was never stored.
 
 \`\`\`tsx
-const visible = storage.visible ?? true;
-const maxItems = storage.maxItems ?? 10;
-const theme = storage.theme ?? "dark";
+const [visible] = useExtensionStorage("visible", true);
+const [maxItems] = useExtensionStorage("maxItems", 10);
+const [theme] = useExtensionStorage("theme", "dark");
 \`\`\`
 
 ### Loading states
@@ -2081,7 +2097,8 @@ For beta testing before public launch:
 | Mistake | Fix |
 |---------|-----|
 | Direct DOM manipulation | Use SDK components only \u2014 reconciler serializes to \`LumioComponentNode[]\` |
-| \`setStorage(newObj)\` without spread | \`setStorage({ ...storage, key: value })\` |
+| \`useExtensionStorage()\` without a key | \`useExtensionStorage(key, initialValue)\` \u2014 one call per key |
+| Object under one key set without spread | \`setScore({ ...score, home: 2 })\` \u2014 the setter replaces that key's 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 |
@@ -2217,7 +2234,7 @@ var troubleshootingContent = `# Troubleshooting
 | \`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 |
+| \`EDITOR_ONLY\` | Function restricted to editor | Mutation with \`editorOnly: true\` called from the layer | 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 |
@@ -2225,7 +2242,8 @@ var troubleshootingContent = `# Troubleshooting
 | \`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\`) |
+| \`ctx.secrets.get\` returns \`null\` | Secret key not set | Bot-module handler reads a key nobody set | \`lumio env set KEY\` or Dashboard \u2192 Extensions \u2192 your extension \u2192 Secrets |
+| \`ctx.secrets is unavailable\` | Secret store unreadable right now | Transient platform issue | Retry; handle the error instead of crashing the handler |
 | \`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 |

package/dist/index.d.ts

@@ -13,4 +13,5 @@ declare const ROOT_FILES: SkillFile[];
  */
 declare function installSkillFiles(targetDir: string): void;
 
-export { ROOT_FILES, SKILL_FILES, type SkillFile, installSkillFiles };
+export { ROOT_FILES, SKILL_FILES, installSkillFiles };
+export type { SkillFile };

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaflun/lumio-agent-skill",
-  "version": "0.5.3",
+  "version": "0.6.5",
   "description": "AI agent skill files for building Lumio Extensions",
   "type": "module",
   "main": "dist/index.js",
@@ -9,7 +9,8 @@
     "lumio-skills": "dist/bin/lumio-skills.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "lumio",
@@ -28,9 +29,9 @@
   "license": "MIT",
   "devDependencies": {
     "@types/node": "^26.1.2",
-    "tsup": "^8.4.0",
+    "tsup": "^9.0.0",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.5"
   },
   "repository": {
     "type": "git",