introduce actors skill

README.md

@@ -64,11 +64,11 @@ npx skills add base44/skills --skill base44-remote-dev --skill base44-sandbox --
 
 | Skill | Description |
 |-------|-------------|
-| [`base44-cli`](skills/base44-cli/SKILL.md) | Create and manage Base44 projects using the CLI. Handles resource configuration (entities, backend functions, AI agents), initialization, and deployment. |
-| [`base44-sdk`](skills/base44-sdk/SKILL.md) | Build apps using the Base44 JavaScript SDK. Communicate with remote resources like entities, backend functions, and AI agents. |
+| [`base44-cli`](skills/base44-cli/SKILL.md) | Create and manage Base44 projects using the CLI. Handles resource configuration (entities, backend functions, realtime actors, AI agents), initialization, and deployment. |
+| [`base44-sdk`](skills/base44-sdk/SKILL.md) | Build apps using the Base44 JavaScript SDK. Communicate with remote resources like entities, backend functions, realtime actors, and AI agents. |
 | [`base44-troubleshooter`](skills/base44-troubleshooter/SKILL.md) | Troubleshoot production issues using backend function logs. Use when investigating app errors or diagnosing production problems. |
 | [`base44-remote-dev`](skills/base44-remote-dev/SKILL.md) | Develop a Base44 app remotely from your own coding agent by connecting it to the Base44 sandbox over MCP or the `base44 sandbox` CLI. |
-| [`base44-sandbox`](skills/base44-sandbox/SKILL.md) | Author Base44 app code inside the cloud sandbox — no deploy/push; writing a resource file (function, entity, agent) into the sandbox is what ships it. |
+| [`base44-sandbox`](skills/base44-sandbox/SKILL.md) | Author Base44 app code inside the cloud sandbox — no deploy/push; writing a resource file (function, actor, entity, agent) into the sandbox is what ships it. |
 
 ## About Agent Skills
 

skills/base44-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: base44-cli
-description: "The base44 CLI is used for EVERYTHING related to base44 projects: resource configuration (entities, backend functions, ai agents), initialization and actions (resource creation, deployment). This skill is the place for learning about how to configure resources. When you plan or implement a feature, you must learn this skill"
+description: "The base44 CLI is used for EVERYTHING related to base44 projects: resource configuration (entities, backend functions, realtime actors, ai agents), initialization and actions (resource creation, deployment). This skill is the place for learning about how to configure resources, including actors — the realtime/WebSocket primitive behind multiplayer, collaborative boards, presence and live cursors, in-room chat, and live auctions. When you plan or implement a feature, you must learn this skill"
 metadata:
   sourcePackage:
     name: base44
@@ -119,6 +119,9 @@ my-app/
 │   ├── functions/               # Backend functions (optional)
 │   │   └── my-function/
 │   │       └── entry.ts
+│   ├── actors/                  # Realtime actors (optional)
+│   │   └── ChatRoom/
+│   │       └── entry.ts
 │   ├── agents/                  # Agent configurations (optional)
 │   │   └── support_agent.jsonc
 │   ├── agent-skills/            # Agent skill instructions (optional)
@@ -140,6 +143,7 @@ my-app/
 - `base44/config.jsonc` - Project name, description, site build settings
 - `base44/entities/*.jsonc` - Data model schemas (see Entity Schema section)
 - `base44/functions/*/entry.ts` - Backend function entry point
+- `base44/actors/*/entry.ts` - Realtime actor entry point (optional)
 - `base44/agents/*.jsonc` - Agent configurations (optional)
 - `base44/agent-skills/*.md` - Agent skill instructions (optional)
 - `base44/.types/types.d.ts` - Auto-generated TypeScript types for entities, functions, and agents (created by `npx base44 types generate`)
@@ -154,6 +158,7 @@ my-app/
   "visibility": "public",              // Optional: "public" | "private" | "workspace"
   "entitiesDir": "./entities",         // Optional: default "entities"
   "functionsDir": "./functions",       // Optional: default "functions"
+  "actorsDir": "./actors",             // Optional: default "actors"
   "agentsDir": "./agents",             // Optional: default "agents"
   "agentSkillsDir": "./agent-skills",  // Optional: default "agent-skills"
   "connectorsDir": "./connectors",     // Optional: default "connectors"
@@ -175,6 +180,7 @@ my-app/
 | `visibility` | App visibility: `public`, `private`, or `workspace` | - |
 | `entitiesDir` | Directory for entity schemas | `"entities"` |
 | `functionsDir` | Directory for backend functions | `"functions"` |
+| `actorsDir` | Directory for realtime actors | `"actors"` |
 | `agentsDir` | Directory for agent configs | `"agents"` |
 | `agentSkillsDir` | Directory for agent skill instructions | `"agent-skills"` |
 | `connectorsDir` | Directory for connector configs | `"connectors"` |
@@ -274,7 +280,7 @@ Workspaces (a.k.a. organizations) group apps under shared membership. By default
 
 | Command | Description | Reference |
 |---------|-------------|-----------|
-| `base44 deploy` | Deploy all resources (entities, functions, agents, agent skills, connectors, auth config, and site) | [deploy.md](references/deploy.md) |
+| `base44 deploy` | Deploy all resources (entities, functions, actors, agents, agent skills, connectors, auth config, and site) | [deploy.md](references/deploy.md) |
 
 ### Entity Management
 
@@ -322,6 +328,45 @@ For complete documentation, see [entities-create.md](references/entities-create.
 | `base44 functions list`   | List all deployed functions on Base44 remote  | [functions-list.md](references/functions-list.md)       |
 | `base44 functions pull [name]` | Pull deployed functions from Base44 to local files | [functions-pull.md](references/functions-pull.md)  |
 
+### Actor Management
+
+Actors are stateful realtime server rooms over WebSockets — one live instance per room id, shared by every client connected to that id. Use them for multiplayer sessions, collaborative boards, presence and live cursors, in-room chat, and live auctions.
+
+| Action / Command | Description | Reference |
+| ---------------- | ----------- | --------- |
+| Create Actors | Define actors in `base44/actors` | [actors-create.md](references/actors-create.md) |
+| `base44 actors deploy [names...]` | Deploy local actors to Base44; optionally target specific actors | [actors-deploy.md](references/actors-deploy.md) |
+| `base44 actors delete <names...>` | Tear down deployed actors (destroys the published script) | [actors-deploy.md](references/actors-deploy.md#deleting-a-deployed-actor) |
+
+#### Actor Layout (Quick Reference)
+
+**File naming:** `base44/actors/{ActorName}/entry.ts` — the folder is the actor's identity.
+
+```javascript
+// base44/actors/ChatRoom/entry.ts
+import { Actor } from "base44:runtime/actors";
+
+export default class ChatRoom extends Actor {
+  handleConnect(conn) { conn.send({ type: "welcome" }); }   // this client only
+  handleMessage(conn, msg) {
+    // Always validate: the payload is attacker-controlled and msg can even be null.
+    if (msg?.type !== "message" || typeof msg.text !== "string") return;
+    this.broadcast({ type: "message", text: msg.text.slice(0, 2000) });   // the whole room
+  }
+  handleClose(conn) {}
+}
+```
+
+**Naming rules:** actor names become a JavaScript class binding and the WebSocket connect handler — they must match `[A-Za-z_][A-Za-z0-9_]*` (max 128 chars, no `/`, `-`, `.` or `:`), must not be a JS reserved word, must not collide with a backend function name, and cannot be nested in subfolders. The CLI checks all of this locally before uploading; a folder with a dot in its name is skipped instead (so `ChatRoom.bak/` is safe scratch space).
+- Valid: `ChatRoom`, `BoardRoom`, `Lobby`
+- Invalid: `chat-room`, `games/Arena`, `class`
+
+**Required:** `entry.ts` (or `entry.js`) that **default-exports** a class extending `Actor` from `base44:runtime/actors`. In TypeScript, also declare `handleTick() {}` — it is an abstract member of `Actor`.
+
+**Differs from functions:** only the actor's own folder is uploaded (no `base44/shared/`), no `--force` prune, no `list`/`pull` commands, no local `base44 dev` runtime, names cannot be path-like, and automations are not supported.
+
+For complete documentation, see [actors-create.md](references/actors-create.md).
+
 ### Agent Management
 
 Agents are conversational AI assistants that can interact with users, access your app's entities, and call backend functions. Use these commands to manage agent configurations.
@@ -484,9 +529,9 @@ Run one-off scripts against your app with the Base44 SDK pre-authenticated. Use
 
 | Command | Description | Reference |
 |---------|-------------|-----------|
-| `base44 types generate` | Generate TypeScript types (`types.d.ts`) from entities, functions, agents, and connectors | [types-generate.md](references/types-generate.md) |
+| `base44 types generate` | Generate TypeScript types (`types.d.ts`) from entities, functions, actors, agents, and connectors | [types-generate.md](references/types-generate.md) |
 
-**Output:** `base44/.types/types.d.ts` — augments `@base44/sdk` module with typed registries (`EntityTypeRegistry`, `FunctionNameRegistry`, `AgentNameRegistry`, `ConnectorTypeRegistry`).
+**Output:** `base44/.types/types.d.ts` — augments `@base44/sdk` module with typed registries (`EntityTypeRegistry`, `FunctionNameRegistry`, `AgentNameRegistry`, `ConnectorTypeRegistry`, `ActorNameRegistry`).
 
 **No authentication required.** Runs entirely locally. Automatically updates `tsconfig.json` to include the generated types.
 
@@ -533,6 +578,8 @@ Or deploy individual resources:
 - `npx base44 functions delete <name>` - Delete a deployed function
 - `npx base44 functions list` - List all deployed functions
 - `npx base44 functions pull` - Pull deployed functions to local files
+- `npx base44 actors deploy` - Deploy realtime actors only
+- `npx base44 actors delete <name>` - Tear down a deployed actor
 - `npx base44 agents push` - Push agents only
 - `npx base44 agent-skills push` - Push agent skills only
 - `npx base44 connectors pull` - Pull connectors from Base44
@@ -580,11 +627,11 @@ npx base44 deploy -y
 
 ### Generating TypeScript Types
 ```bash
-# Generate types from entities, functions, agents, and connectors
+# Generate types from entities, functions, actors, agents, and connectors
 npx base44 types generate
 ```
 
-This creates `base44/.types/types.d.ts` with typed registries for the `@base44/sdk` module. Run this after changing entities, functions, agents, or connectors to keep your types in sync. No authentication required.
+This creates `base44/.types/types.d.ts` with typed registries for the `@base44/sdk` module. Run this after changing entities, functions, actors, agents, or connectors to keep your types in sync. No authentication required.
 
 ### Deploying Individual Resources
 ```bash
@@ -598,6 +645,13 @@ npx base44 functions deploy my-function other-function
 # Deploy and prune removed functions
 npx base44 functions deploy --force
 
+# Deploy only actors (all)
+npx base44 actors deploy
+# Deploy specific actors
+npx base44 actors deploy ChatRoom BoardRoom
+# Tear down a deployed actor
+npx base44 actors delete ChatRoom
+
 # Push only agents
 npx base44 agents push
 
@@ -632,6 +686,11 @@ Most commands require authentication. If you're not logged in, the CLI will auto
 | No entities found           | Ensure entities exist in `base44/entities/` directory                               |
 | Entity not recognized       | Ensure file uses kebab-case naming (e.g., `team-member.jsonc` not `TeamMember.jsonc`) |
 | No functions found          | Ensure functions exist in `base44/functions/` with `entry.ts` or `entry.js`   |
+| No actors found             | Ensure actors exist as `base44/actors/<ActorName>/entry.ts` (never directly in `base44/actors/`) |
+| Invalid actor name          | Actor names must match `[A-Za-z_][A-Za-z0-9_]*` (no `/`, `-`, `.` or `:`), avoid JS reserved words, and cannot be nested. Caught locally, before any upload |
+| `actors cannot be nested`   | Flatten to `base44/actors/<ActorName>/entry.ts`, or rename a helper you called `entry.ts` — every entry file under `base44/actors/` counts as an actor |
+| Actor and function share a name | They deploy into one namespace — rename one of them |
+| Actor file rejected in the functions bucket | A file importing `base44:runtime/actors` must live at `base44/actors/<ActorName>/entry.ts` — move it out of `base44/functions/` |
 | No agents found             | Ensure agents exist in `base44/agents/` directory with valid `.jsonc` configs       |
 | Invalid agent name          | Agent names must be lowercase alphanumeric with underscores only                    |
 | No agent skills found       | Ensure skill files exist in `base44/agent-skills/` directory with valid `.md` files  |