docs: clarify actor accept schemas

README.md

@@ -104,7 +104,9 @@ cat > GreeterActor.mjs <<'EOF'
 import { MatrixActor } from '@open-matrix/sdk';
 
 export default class GreeterActor extends MatrixActor {
-  static accepts = { echo: {} };
+  static accepts = {
+    echo: { description: 'Echo a message', message: 'string' },
+  };
   onEcho(payload = {}) {
     return {
       ok: true,
@@ -130,8 +132,9 @@ Expected result: the actor run command prints JSON with `ok: true` and the
 `echo` result from `GreeterActor`.
 
 Handler names are part of the Matrix actor contract: `static accepts = { echo:
-{} }` maps to `onEcho(payload)`. Do not implement `echo(payload)` directly; the
-CLI rejects that shape before it connects to the broker.
+... }` maps to `onEcho(payload)`. Do not implement `echo(payload)` directly; the
+CLI rejects that shape before it connects to the broker. Include parameter
+fields such as `message: 'string'` so agents can construct valid payloads.
 
 If you need the HiveCast browser proof and `pnpm doctor:hivecast` reports
 missing Chromium:
@@ -170,7 +173,7 @@ import {
 
 class EchoActor extends MatrixActor {
   static accepts = {
-    echo: {},
+    echo: { description: 'Echo a message', message: 'string' },
   };
 
   onEcho(payload: { message?: string }) {

demos/fresh-server-actor/src/server.ts

@@ -9,7 +9,7 @@ import {
 
 class FreshServerEchoActor extends MatrixActor {
   static accepts = {
-    echo: {},
+    echo: { description: 'Echo a message', message: 'string' },
     getStatus: {},
   };
 

demos/fresh-web-page/src/main.ts

@@ -8,7 +8,7 @@ import type { HiveCastActorCredential } from '@open-matrix/sdk';
 
 class FreshBrowserEchoActor extends MatrixActor {
   static accepts = {
-    echo: {},
+    echo: { description: 'Echo a message', message: 'string' },
     getStatus: {},
   };
 

demos/fresh-web-page/vite.config.ts

@@ -38,7 +38,7 @@ function hiveCastActorCredentialPlugin(): Plugin {
             actorId: 'FreshBrowserEchoActor',
             packageId: 'matrix-sdk-demo-fresh-web-page',
             runtimeId: `fresh-web-${process.pid}`,
-            accepts: { echo: {}, getStatus: {} },
+            accepts: { echo: { description: 'Echo a message', message: 'string' }, getStatus: {} },
             ttlSeconds: 300,
           });
           sendJson(res, 200, credential);

demos/standalone-greeter/src/GreeterActor.ts

@@ -2,7 +2,7 @@ import { MatrixActor } from '@open-matrix/core';
 
 export class GreeterActor extends MatrixActor {
   static accepts = {
-    echo: {},
+    echo: { description: 'Echo a message', message: 'string' },
     getStatus: {},
   };
 

packages/sdk/README.md

@@ -29,7 +29,7 @@ const credential = await exchangeHiveCastActorCredential({
   apiKey: process.env.MATRIX_API_KEY!,
 }, {
   mount: 'fresh.server.echo',
-  accepts: { echo: {} },
+  accepts: { echo: { description: 'Echo a message', message: 'string' } },
 });
 ```