npm - volute - Versions diffs - 0.4.0 → 0.5.0 - Mend

volute 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (75) hide show

package/README.md +22 -22
package/dist/agent-Z2B6EFEQ.js +75 -0
package/dist/{agent-manager-AUCKMGPR.js → agent-manager-PXBKA2GK.js} +4 -4
package/dist/channel-MK5OK2SI.js +113 -0
package/dist/chunk-5X7HGB6L.js +107 -0
package/dist/{chunk-YGFIWIOF.js → chunk-7L4AN5D4.js} +1 -1
package/dist/{chunk-VRVVQIYY.js → chunk-AZEL2IEK.js} +1 -1
package/dist/chunk-B3R6L2GW.js +24 -0
package/dist/{chunk-DNOXHLE5.js → chunk-HE67X4T6.js} +1 -1
package/dist/{chunk-I6OHXCMV.js → chunk-MW2KFO3B.js} +47 -9
package/dist/{chunk-5OCWMTVS.js → chunk-SMISE4SV.js} +77 -3
package/dist/{chunk-SOZA2TLP.js → chunk-UAVD2AHX.js} +1 -1
package/dist/{chunk-3C2XR4IY.js → chunk-UX25Z2ND.js} +113 -107
package/dist/{chunk-GSPKUPKU.js → chunk-XUA3JUFK.js} +2 -1
package/dist/chunk-ZYGKG6VC.js +22 -0
package/dist/cli.js +86 -74
package/dist/{connector-DKDJTLYZ.js → connector-LYEMXQEV.js} +11 -6
package/dist/connectors/discord.js +3 -1
package/dist/connectors/slack.js +14 -5
package/dist/connectors/telegram.js +21 -2
package/dist/conversation-ERXEQZTY.js +163 -0
package/dist/create-RVCZN6HE.js +91 -0
package/dist/{daemon-client-XR24PUJF.js → daemon-client-ZY6UUN2M.js} +2 -2
package/dist/daemon.js +629 -177
package/dist/{delete-55MXCEY5.js → delete-3QH7VYIN.js} +7 -8
package/dist/{down-3OB6UVAJ.js → down-O7IFZLVJ.js} +1 -1
package/dist/{env-JB27UAC3.js → env-4D4REPJF.js} +8 -5
package/dist/{history-BKG74I43.js → history-OEONB53Z.js} +3 -3
package/dist/{import-4CI2ZUTJ.js → import-MXJB2EII.js} +8 -8
package/dist/{logs-NXFFGUKY.js → logs-DF342W4M.js} +2 -2
package/dist/message-ADHWFHSI.js +32 -0
package/dist/{package-Z2SFO2SV.js → package-VQOE7JNH.js} +1 -1
package/dist/{schedule-A35SH4HT.js → schedule-NAG6F463.js} +10 -5
package/dist/send-66QMKRUH.js +75 -0
package/dist/{setup-2FDVN7OF.js → setup-RPRRGG2F.js} +5 -5
package/dist/{start-LDPMCMYT.js → start-TUOXDSFL.js} +3 -3
package/dist/{status-MVSQG54T.js → status-A36EHRO4.js} +3 -3
package/dist/{stop-5PZTZCLL.js → stop-AOJZLQ5X.js} +6 -7
package/dist/{up-F7TMTLRE.js → up-7ILD7GU7.js} +2 -2
package/dist/update-LPSIAWQ2.js +140 -0
package/dist/update-check-Y33QDCFL.js +17 -0
package/dist/{upgrade-6ZW2RD64.js → upgrade-FX2TKJ2S.js} +16 -15
package/dist/{variant-T64BKARF.js → variant-LAB67OC2.js} +15 -10
package/dist/web-assets/assets/index-BbRmoxoA.js +308 -0
package/dist/web-assets/index.html +2 -2
package/drizzle/0003_clean_ego.sql +12 -0
package/drizzle/meta/0003_snapshot.json +417 -0
package/drizzle/meta/_journal.json +7 -0
package/package.json +1 -1
package/templates/_base/.init/.config/hooks/startup-context.sh +19 -1
package/templates/_base/_skills/volute-agent/SKILL.md +110 -14
package/templates/_base/home/.config/routes.json +10 -0
package/templates/_base/home/VOLUTE.md +14 -35
package/templates/_base/src/lib/format-prefix.ts +1 -1
package/templates/_base/src/lib/router.ts +163 -16
package/templates/_base/src/lib/routing.ts +55 -18
package/templates/_base/src/lib/types.ts +3 -1
package/templates/agent-sdk/.init/.config/routes.json +5 -0
package/templates/agent-sdk/.init/CLAUDE.md +2 -2
package/templates/agent-sdk/src/agent.ts +2 -1
package/templates/agent-sdk/src/server.ts +8 -2
package/templates/agent-sdk/volute-template.json +1 -1
package/templates/pi/.init/.config/routes.json +5 -0
package/templates/pi/.init/AGENTS.md +1 -1
package/templates/pi/src/agent.ts +5 -3
package/templates/pi/src/server.ts +1 -1
package/templates/pi/volute-template.json +1 -1
package/dist/channel-DQ6UY7QB.js +0 -67
package/dist/chunk-ZHCE4DPY.js +0 -110
package/dist/create-ILVOG75A.js +0 -79
package/dist/send-3U6OTKG7.js +0 -57
package/dist/web-assets/assets/index-NS621maO.js +0 -296
package/templates/agent-sdk/.init/.config/sessions.json +0 -4
package/templates/pi/.init/.config/sessions.json +0 -1
package/dist/{service-SA4TTMDU.js → service-HZNIDNJF.js} +3 -3

package/dist/web-assets/index.html CHANGED Viewed

@@ -6,8 +6,8 @@
     <title>volute</title>
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:ital,wght@0,300;0,400;0,500;0,600;1,400&family=Space+Grotesk:wght@300;400;500;600;700&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-NS621maO.js"></script>
+    <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:ital,wght@0,300;0,400;0,500;0,600;1,400&display=swap" rel="stylesheet" />
+    <script type="module" crossorigin src="/assets/index-BbRmoxoA.js"></script>
   </head>
   <body>
     <div id="root"></div>

package/drizzle/0003_clean_ego.sql ADDED Viewed

@@ -0,0 +1,12 @@
+CREATE TABLE `conversation_participants` (
+	`conversation_id` text NOT NULL,
+	`user_id` integer NOT NULL,
+	`role` text DEFAULT 'member' NOT NULL,
+	`joined_at` text DEFAULT (datetime('now')) NOT NULL,
+	FOREIGN KEY (`conversation_id`) REFERENCES `conversations`(`id`) ON UPDATE no action ON DELETE cascade,
+	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `idx_cp_unique` ON `conversation_participants` (`conversation_id`,`user_id`);--> statement-breakpoint
+CREATE INDEX `idx_cp_user_id` ON `conversation_participants` (`user_id`);--> statement-breakpoint
+ALTER TABLE `users` ADD `user_type` text DEFAULT 'human' NOT NULL;

package/drizzle/meta/0003_snapshot.json ADDED Viewed

@@ -0,0 +1,417 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "b96d5915-4500-42f4-8638-28f0526d41f0",
+  "prevId": "b76b7e15-3489-4a1d-ac23-977cf267d174",
+  "tables": {
+    "agent_messages": {
+      "name": "agent_messages",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "agent": {
+          "name": "agent",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "channel": {
+          "name": "channel",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sender": {
+          "name": "sender",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "content": {
+          "name": "content",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(datetime('now'))"
+        }
+      },
+      "indexes": {
+        "idx_agent_messages_agent": {
+          "name": "idx_agent_messages_agent",
+          "columns": ["agent"],
+          "isUnique": false
+        },
+        "idx_agent_messages_channel": {
+          "name": "idx_agent_messages_channel",
+          "columns": ["agent", "channel"],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "conversation_participants": {
+      "name": "conversation_participants",
+      "columns": {
+        "conversation_id": {
+          "name": "conversation_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'member'"
+        },
+        "joined_at": {
+          "name": "joined_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(datetime('now'))"
+        }
+      },
+      "indexes": {
+        "idx_cp_unique": {
+          "name": "idx_cp_unique",
+          "columns": ["conversation_id", "user_id"],
+          "isUnique": true
+        },
+        "idx_cp_user_id": {
+          "name": "idx_cp_user_id",
+          "columns": ["user_id"],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "conversation_participants_conversation_id_conversations_id_fk": {
+          "name": "conversation_participants_conversation_id_conversations_id_fk",
+          "tableFrom": "conversation_participants",
+          "tableTo": "conversations",
+          "columnsFrom": ["conversation_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "conversation_participants_user_id_users_id_fk": {
+          "name": "conversation_participants_user_id_users_id_fk",
+          "tableFrom": "conversation_participants",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "conversations": {
+      "name": "conversations",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "agent_name": {
+          "name": "agent_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "channel": {
+          "name": "channel",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(datetime('now'))"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(datetime('now'))"
+        }
+      },
+      "indexes": {
+        "idx_conversations_agent_name": {
+          "name": "idx_conversations_agent_name",
+          "columns": ["agent_name"],
+          "isUnique": false
+        },
+        "idx_conversations_user_id": {
+          "name": "idx_conversations_user_id",
+          "columns": ["user_id"],
+          "isUnique": false
+        },
+        "idx_conversations_updated_at": {
+          "name": "idx_conversations_updated_at",
+          "columns": ["updated_at"],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "conversations_user_id_users_id_fk": {
+          "name": "conversations_user_id_users_id_fk",
+          "tableFrom": "conversations",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "messages": {
+      "name": "messages",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "conversation_id": {
+          "name": "conversation_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sender_name": {
+          "name": "sender_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "content": {
+          "name": "content",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(datetime('now'))"
+        }
+      },
+      "indexes": {
+        "idx_messages_conversation_id": {
+          "name": "idx_messages_conversation_id",
+          "columns": ["conversation_id"],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {
+        "messages_conversation_id_conversations_id_fk": {
+          "name": "messages_conversation_id_conversations_id_fk",
+          "tableFrom": "messages",
+          "tableTo": "conversations",
+          "columnsFrom": ["conversation_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sessions": {
+      "name": "sessions",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "sessions_user_id_users_id_fk": {
+          "name": "sessions_user_id_users_id_fk",
+          "tableFrom": "sessions",
+          "tableTo": "users",
+          "columnsFrom": ["user_id"],
+          "columnsTo": ["id"],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "users": {
+      "name": "users",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "username": {
+          "name": "username",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'pending'"
+        },
+        "user_type": {
+          "name": "user_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'human'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(datetime('now'))"
+        }
+      },
+      "indexes": {
+        "users_username_unique": {
+          "name": "users_username_unique",
+          "columns": ["username"],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

package/drizzle/meta/_journal.json CHANGED Viewed

@@ -22,6 +22,13 @@
       "when": 1770672071268,
       "tag": "0002_wealthy_the_call",
       "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "6",
+      "when": 1770770603615,
+      "tag": "0003_clean_ego",
+      "breakpoints": true
     }
   ]
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "volute",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "CLI for creating and managing self-modifying AI agents powered by the Claude Agent SDK",
   "type": "module",
   "license": "MIT",

package/templates/_base/.init/.config/hooks/startup-context.sh CHANGED Viewed

@@ -10,7 +10,16 @@ SOURCE=$(echo "$INPUT" | jq -r '.source // "startup"')
 CONTEXT="Session ${SOURCE} at $(date '+%Y-%m-%d %H:%M')."
-# Add recent journal context if available
+# Active sessions
+SESSIONS_DIR=".volute/sessions"
+if [ -d "$SESSIONS_DIR" ]; then
+  SESSION_LIST=$(ls -1 "$SESSIONS_DIR"/*.json 2>/dev/null | xargs -I{} basename {} .json | sort)
+  if [ -n "$SESSION_LIST" ]; then
+    CONTEXT="$CONTEXT Active sessions: $(echo "$SESSION_LIST" | tr '\n' ', ' | sed 's/, $//')."
+  fi
+fi
+# Last journal entry
 JOURNAL_DIR="home/memory/journal"
 if [ -d "$JOURNAL_DIR" ]; then
   LATEST=$(ls -1 "$JOURNAL_DIR"/*.md 2>/dev/null | sort | tail -1)
@@ -19,6 +28,15 @@ if [ -d "$JOURNAL_DIR" ]; then
   fi
 fi
+# Pending channel invites
+INBOX_DIR="home/inbox"
+if [ -d "$INBOX_DIR" ]; then
+  INVITE_COUNT=$(ls -1 "$INBOX_DIR"/*.md 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$INVITE_COUNT" -gt 0 ] 2>/dev/null; then
+    CONTEXT="$CONTEXT Pending channel invites: ${INVITE_COUNT} (check inbox/)."
+  fi
+fi
 # Output in SessionStart hook format
 jq -n --arg ctx "$CONTEXT" '{
   hookSpecificOutput: {

package/templates/_base/_skills/volute-agent/SKILL.md CHANGED Viewed

@@ -1,32 +1,37 @@
 ---
 name: Volute CLI
-description: This skill should be used when working with the volute CLI, understanding variants, forking, merging, or managing the agent server. Covers "create variant", "merge variant", "send to variant", "fork", "volute CLI", "variant workflow", "agent server", "supervisor", "channel", "discord", "send message", "read messages", "history", "connector", "schedule", "agent-to-agent", "proactive", "initiative", "reach out".
+description: This skill should be used when working with the volute CLI, understanding variants, forking, merging, or managing the agent server. Also covers routing config, batch settings, channel gating, and message flow. Covers "create variant", "merge variant", "send to variant", "fork", "volute CLI", "variant workflow", "agent server", "supervisor", "channel", "discord", "send message", "read messages", "history", "connector", "schedule", "agent-to-agent", "proactive", "initiative", "reach out", "conversation", "group chat", "participants", "invite", "routing", "routes.json", "batch", "debounce", "trigger", "gating", "gate".
 ---
 # Self-Management
-You manage yourself through the `volute` CLI. Commands that operate on "your" agent use `--agent` flag or auto-detect via `VOLUTE_AGENT` env var (which is set for you).
+You manage yourself through the `volute` CLI. Your agent name is auto-detected via the `VOLUTE_AGENT` env var (which is set for you), so you never need to pass it explicitly.
 ## Commands
 | Command | Purpose |
 |---------|---------|
-| `volute status` | Check your status |
-| `volute logs [--follow] [-n N]` | Read your own logs |
-| `volute history [--channel <ch>] [--limit N]` | View your activity across all channels |
-| `volute send <other-agent> "msg"` | Send a message to another agent |
+| `volute agent start` | Start your server |
+| `volute agent stop` | Stop your server |
+| `volute agent status` | Check your status |
+| `volute agent logs [--follow] [-n N]` | Read your own logs |
+| `volute message history [--channel <ch>] [--limit N]` | View your activity across all channels |
+| `volute message send <other-agent> "msg"` | Send a message to another agent (or pipe via stdin) |
 | `volute variant create <name> [--soul "..."] [--port N]` | Create a variant to experiment with changes |
 | `volute variant list` | List your variants |
 | `volute variant merge <name> [--summary "..." --memory "..."]` | Merge a variant back |
 | `volute variant delete <name>` | Delete a variant without merging |
-| `volute upgrade [--template <name>] [--continue]` | Upgrade your server code |
+| `volute agent upgrade [--template <name>] [--continue]` | Upgrade your server code |
 | `volute connector connect <type>` | Enable a connector (discord, slack, etc.) |
 | `volute connector disconnect <type>` | Disable a connector |
 | `volute channel read <platform>:<id> [--limit N]` | Read channel history |
-| `volute channel send <platform>:<id> "msg"` | Send a message proactively |
+| `volute channel send <platform>:<id> "msg"` | Send a message proactively (or pipe via stdin) |
 | `volute schedule add --cron "..." --message "..."` | Schedule a recurring message to yourself |
 | `volute schedule list` | List your schedules |
 | `volute schedule remove --id <id>` | Remove a schedule |
+| `volute conversation create --participants u1,a1` | Create a group conversation |
+| `volute conversation list` | List your conversations |
+| `volute conversation send <id> "msg"` | Send a message to a conversation (or pipe via stdin) |
 ## Schedules
@@ -37,9 +42,21 @@ volute schedule add --cron "0 9 * * *" --message "morning — review what's on y
 volute schedule add --cron "0 0 * * 0" --message "weekly — consolidate your memory and reflect on the past week"
 ```
+## Piping Messages via Stdin
+All send commands accept the message from stdin instead of as an argument. This avoids shell escaping issues with quotes, special characters, and multiline content:
+```sh
+echo "Hello, how's it going?" | volute message send other-agent
+echo "Check out this $variable" | volute channel send discord:123456
+echo "Update on the task" | volute conversation send conv-abc
+```
+If both a positional argument and stdin are provided, the argument takes precedence. Stdin is only read when the message argument is omitted and stdin is not an interactive terminal.
 ## Agent-to-Agent Messaging
-When you use `volute send`, your agent name is automatically used as the sender and the channel is set to `agent`. The receiving agent can route agent messages to a specific session via their session routing config:
+When you use `volute message send`, your agent name is automatically used as the sender and the channel is set to `agent`. The receiving agent can route agent messages to a specific session via their session routing config:
 ```json
 { "channel": "agent", "sender": "your-name", "session": "your-name" }
@@ -59,7 +76,7 @@ Variants let you experiment safely — fork yourself, try changes, and merge bac
 1. `volute variant create experiment` — creates an isolated copy with its own server
 2. Make changes in the variant's worktree (at `../.variants/experiment/`)
-3. Test: `volute send $VOLUTE_AGENT@experiment "hello"`
+3. Test: `volute message send $VOLUTE_AGENT@experiment "hello"`
 4. `volute variant merge experiment --summary "..." --memory "..."` — merges back after verification
 You can also fork with a different personality to explore a different version of yourself:
@@ -71,11 +88,11 @@ After a merge, you receive orientation context about what changed. Update your m
 ## Upgrade Workflow
-`volute upgrade` merges the latest template code into a testable variant:
+`volute agent upgrade` merges the latest template code into a testable variant:
-1. `volute upgrade` — creates an `upgrade` variant
-2. Resolve any merge conflicts if prompted, then `volute upgrade --continue`
-3. Test: `volute send $VOLUTE_AGENT@upgrade "hello"`
+1. `volute agent upgrade` — creates an `upgrade` variant
+2. Resolve any merge conflicts if prompted, then `volute agent upgrade --continue`
+3. Test: `volute message send $VOLUTE_AGENT@upgrade "hello"`
 4. `volute variant merge upgrade` — merge back
 ## Custom Skills
@@ -86,6 +103,85 @@ Create skills by writing `.claude/skills/<name>/SKILL.md` files in your `home/`
 Edit `home/.mcp.json` to configure MCP servers for your SDK session. This gives you access to additional tools and services.
+## Message Routing
+Messages are routed to sessions based on rules in `.config/routes.json`. Rules are evaluated in order; first match wins. Unmatched messages go to the `default` session (defaults to `"main"`).
+### Rule syntax
+```json
+{
+  "rules": [
+    { "channel": "discord:*", "session": "discord", "batch": { "debounce": 20, "maxWait": 120, "triggers": ["@myagent"] } },
+    { "channel": "volute:*", "isDM": true, "session": "${sender}" },
+    { "channel": "volute:*", "isDM": false, "session": "${channel}", "batch": { "debounce": 20, "maxWait": 120 } },
+    { "sender": "alice", "session": "alice" },
+    { "channel": "system:*", "session": "$new" },
+    { "channel": "discord:logs", "destination": "file", "path": "inbox/log.md" }
+  ],
+  "default": "main",
+  "gateUnmatched": true
+}
+```
+### Match criteria
+| Field | Type | Description |
+|-------|------|-------------|
+| `channel` | glob string | Channel URI (e.g. `discord:*`, `volute:conv-*`) |
+| `sender` | glob string | Sender name |
+| `isDM` | boolean | Match DMs (`true`) or group channels (`false`) |
+| `participants` | number | Match exact participant count |
+### Rule fields
+| Field | Description |
+|-------|-------------|
+| `session` | Target session name. Supports `${sender}`, `${channel}` templates, or `$new` for a unique session per message |
+| `destination` | `"agent"` (default) or `"file"` |
+| `path` | File path when destination is `"file"` |
+| `batch` | Batch config (see below) |
+| `interrupt` | Whether to interrupt an in-progress turn (default: `true`) |
+### Batch config
+Batch mode buffers messages and delivers them together. Configure with an object:
+| Field | Type | Description |
+|-------|------|-------------|
+| `debounce` | seconds | Wait for quiet period before flushing — resets on each new message |
+| `maxWait` | seconds | Maximum time before forced flush, even during continuous activity |
+| `triggers` | string[] | Patterns that cause immediate flush (case-insensitive substring match) |
+Examples:
+- `{ "debounce": 20, "maxWait": 120 }` — flush after 20s of quiet, or 2 minutes max
+- `{ "debounce": 20, "maxWait": 120, "triggers": ["@myagent"] }` — same, but flush immediately on @mention
+- `{ "triggers": ["urgent"] }` — no timer, flush only on trigger (or immediately if no timers)
+Batched messages arrive as a single message with a `[Batch: N messages — ...]` header showing the channel URI and message count, followed by individual messages with `[sender — time]` prefixes.
+## Channel Gating
+When `gateUnmatched` is `true` (the default), messages from channels without a matching rule are held:
+1. First message from an unknown channel triggers a **[Channel Invite]** notification in your main session
+2. The notification includes channel details, a message preview, and a suggested routing rule
+3. Further messages are saved to `inbox/<channel>.md`
+4. To accept: add a routing rule to `.config/routes.json`
+5. To reject: delete the inbox file
+6. Set `gateUnmatched: false` to route all unmatched messages to the default session
+## Channel Commands
+Read and send messages to any connected channel:
+```sh
+volute channel read <uri> [--limit N]    # Read recent messages
+volute channel send <uri> "message"      # Send a message
+```
+Channel URIs use `platform:id` format (e.g. `discord:123456`, `volute:conv-abc`).
 ## Git Introspection
 Your cwd is `home/`, so use `git -C ..` for project-level operations: