volute 0.32.0 → 0.34.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 (187) hide show
  1. package/README.md +16 -0
  2. package/dist/{accept-74M7I4RZ.js → accept-TW6V4WI4.js} +4 -4
  3. package/dist/{activity-events-HETAODOK.js → activity-events-BN7V6KCC.js} +4 -4
  4. package/dist/{ai-service-ZIPCV3MX.js → ai-service-PSILB5WD.js} +5 -5
  5. package/dist/{api-client-YPKOZP2O.js → api-client-XUXOB7LI.js} +1 -1
  6. package/dist/api.d.ts +1198 -957
  7. package/dist/{archive-INXYFVCW.js → archive-C2VEMQOR.js} +4 -4
  8. package/dist/{auth-6DMGES3I.js → auth-ZFZXJZDQ.js} +5 -5
  9. package/dist/{bridge-BVCBTGPF.js → bridge-O753D5F4.js} +4 -4
  10. package/dist/{chat-XT4OBJBU.js → chat-BHYX7DJ4.js} +9 -9
  11. package/dist/{chunk-M7UL5S3Q.js → chunk-2IOP6PHB.js} +1 -1
  12. package/dist/{chunk-JJ7W6WSB.js → chunk-47XDEWWV.js} +5 -5
  13. package/dist/{chunk-RSX4OPZY.js → chunk-47ZPNLF4.js} +7 -7
  14. package/dist/{chunk-RPZZSXV3.js → chunk-4JSR7YO7.js} +20 -1
  15. package/dist/chunk-6LXAAQ43.js +22 -0
  16. package/dist/{chunk-TSXLLQZW.js → chunk-6OWJXUAR.js} +10 -1
  17. package/dist/{chunk-I5KY25PQ.js → chunk-6WAWMWR5.js} +1 -1
  18. package/dist/{chunk-LSGWR54X.js → chunk-7F2SW2KD.js} +2 -2
  19. package/dist/chunk-7KJOFUNN.js +22 -0
  20. package/dist/{spirit-N4W4UQRH.js → chunk-B2BVAIZ4.js} +21 -12
  21. package/dist/{chunk-LGB6JBHI.js → chunk-BDK73LK6.js} +5 -55
  22. package/dist/{chunk-IYDIE3HG.js → chunk-BFWHBQK4.js} +1 -1
  23. package/dist/{chunk-TDRYEPH4.js → chunk-BM474GX6.js} +4 -4
  24. package/dist/{chunk-R7E6CRVQ.js → chunk-BTWAGDV5.js} +1 -1
  25. package/dist/{chunk-WKF5FEFK.js → chunk-CVL5IGIR.js} +629 -174
  26. package/dist/{chunk-S6NFERDC.js → chunk-E5C7OWZ2.js} +20 -22
  27. package/dist/chunk-FYCALD4Q.js +23 -0
  28. package/dist/{chunk-SKLSMHXO.js → chunk-IS7WJ56Q.js} +1 -1
  29. package/dist/{chunk-2NGTS5UU.js → chunk-M3K5AARV.js} +1 -1
  30. package/dist/{chunk-ALEF47VT.js → chunk-MLOQKQNB.js} +1 -1
  31. package/dist/{chunk-D5G5YOPL.js → chunk-N3DNFPVA.js} +41 -5
  32. package/dist/{chunk-LRCG2JLP.js → chunk-N7BLAHNE.js} +5 -1
  33. package/dist/chunk-OYAKCAVY.js +29 -0
  34. package/dist/{chunk-UKVWJRKN.js → chunk-PLDWHR4D.js} +1 -1
  35. package/dist/{chunk-QBQ424EM.js → chunk-TAHX36HZ.js} +545 -246
  36. package/dist/chunk-U5BTYSAL.js +59 -0
  37. package/dist/{chunk-SX5TKJBZ.js → chunk-V45JXOWY.js} +2 -2
  38. package/dist/{chunk-2FLJ63GU.js → chunk-V6ZCNULL.js} +2 -2
  39. package/dist/{chunk-QZANELPX.js → chunk-XWXBJQBE.js} +3 -2
  40. package/dist/cli.js +32 -24
  41. package/dist/{clock-2UOZ6JPU.js → clock-3X4DSC2N.js} +38 -23
  42. package/dist/{cloud-sync-JN3NWKEM.js → cloud-sync-TG3TIX5H.js} +21 -17
  43. package/dist/{config-H2H4UIF7.js → config-OROA5DUA.js} +4 -4
  44. package/dist/connectors/discord-bridge.js +1 -1
  45. package/dist/connectors/slack-bridge.js +1 -1
  46. package/dist/connectors/telegram-bridge.js +1 -1
  47. package/dist/{conversations-3O5O6AS3.js → conversations-HL2JP5GI.js} +5 -5
  48. package/dist/{create-RNLNCORE.js → create-3SEKKI6P.js} +5 -5
  49. package/dist/{create-WBBYI6V7.js → create-UOSOQ2HN.js} +4 -4
  50. package/dist/daemon-client-WOAQXXBM.js +12 -0
  51. package/dist/{daemon-restart-NGFHFAUF.js → daemon-restart-5ABHNXJZ.js} +9 -8
  52. package/dist/daemon.js +2730 -1520
  53. package/dist/{db-RA45JBFG.js → db-PLEDCBHZ.js} +1 -1
  54. package/dist/db-RYX3SS2W.js +9 -0
  55. package/dist/{delete-QTGWEDBI.js → delete-KYOVWR23.js} +3 -3
  56. package/dist/delivery-manager-2BR5NZKF.js +32 -0
  57. package/dist/{delivery-router-FL45JL7N.js → delivery-router-D5ELDMS2.js} +4 -4
  58. package/dist/down-QVFN4UPK.js +15 -0
  59. package/dist/{env-RLYQBOOP.js → env-R34DT7XL.js} +10 -6
  60. package/dist/exec-DVLXKRIO.js +17 -0
  61. package/dist/{export-SUYRLI5Q.js → export-6ZXAXATG.js} +6 -6
  62. package/dist/extension-PM42QCID.js +97 -0
  63. package/dist/extensions-BBGVL5JC.js +38 -0
  64. package/dist/{files-EAMPO2SJ.js → files-VQV2VZQO.js} +5 -5
  65. package/dist/{import-DDUFE7AY.js → import-MK2I2T6F.js} +5 -5
  66. package/dist/isolation-62MKDZN3.js +22 -0
  67. package/dist/{join-I5QEE3LG.js → join-DGYHTJUH.js} +3 -3
  68. package/dist/lib-DYEZMGW7.js +6588 -0
  69. package/dist/{list-DW2VRTOZ.js → list-C644WTHV.js} +16 -8
  70. package/dist/{login-7CHPW2PN.js → login-IIGEQPHL.js} +4 -4
  71. package/dist/{login-RIJF2F4G.js → login-KZQLMAWE.js} +4 -4
  72. package/dist/{logout-5MLHZALK.js → logout-AGTZVRGP.js} +4 -4
  73. package/dist/{logout-UZJRGY4Z.js → logout-KD6GXIJJ.js} +4 -4
  74. package/dist/message-delivery-V3R6NXJP.js +42 -0
  75. package/dist/{mind-2B6M7Y25.js → mind-BI4EPBVZ.js} +25 -19
  76. package/dist/{mind-activity-tracker-NZZT2NTT.js → mind-activity-tracker-2ACNHA7B.js} +5 -5
  77. package/dist/mind-history-WOYFLQAI.js +264 -0
  78. package/dist/{mind-list-WUPMQDYQ.js → mind-list-6VPM7GUQ.js} +4 -4
  79. package/dist/mind-manager-MWW3BTS4.js +32 -0
  80. package/dist/mind-profile-WPG42U5Y.js +47 -0
  81. package/dist/mind-service-VIKZJK2M.js +38 -0
  82. package/dist/{mind-sleep-B7BHJLH7.js → mind-sleep-XDISJY74.js} +4 -4
  83. package/dist/{mind-status-L3EFFRPR.js → mind-status-7FTZWPZF.js} +4 -4
  84. package/dist/{mind-wake-GY3RFX7Y.js → mind-wake-KIIKEI3A.js} +4 -4
  85. package/dist/{package-PK6JUFL3.js → package-V2WHWVG6.js} +9 -5
  86. package/dist/{read-5AMJRO3D.js → read-H5C26YO7.js} +18 -8
  87. package/dist/read-stdin-PIRM6A2Y.js +8 -0
  88. package/dist/{register-V2JZZKFK.js → register-J27WP33N.js} +4 -4
  89. package/dist/{registry-PJ4S5PHQ.js → registry-UYV5S6QT.js} +3 -3
  90. package/dist/{reject-33HEZMZ4.js → reject-OEANJYIA.js} +4 -4
  91. package/dist/{restart-3UCMRUVC.js → restart-V5EGYBJG.js} +4 -4
  92. package/dist/{sandbox-JANNTX6U.js → sandbox-SI5HMBP3.js} +5 -5
  93. package/dist/scheduler-AGG3L2FO.js +32 -0
  94. package/dist/{schema-PA3M5ZKH.js → schema-ETMABTW4.js} +4 -2
  95. package/dist/seed-WNGI6PNW.js +11 -0
  96. package/dist/seed-check-PXTH7YXS.js +32 -0
  97. package/dist/seed-cmd-VENFTGS3.js +36 -0
  98. package/dist/{seed-ALUQ55FF.js → seed-create-663ALOKH.js} +8 -8
  99. package/dist/{sprout-L2GFOVF7.js → seed-sprout-EH3AGKAI.js} +24 -11
  100. package/dist/{send-3MI36LEF.js → send-7FUUUZZH.js} +66 -51
  101. package/dist/{setup-SZIARWI6.js → setup-GGMKENLN.js} +6 -4
  102. package/dist/{setup-WENLVPVP.js → setup-Z3DEVWV7.js} +13 -11
  103. package/dist/{skill-TUVOTW4Z.js → skill-DKNYJS4P.js} +12 -8
  104. package/dist/skills/imagegen/SKILL.md +11 -7
  105. package/dist/skills/imagegen/scripts/imagegen.ts +146 -25
  106. package/dist/skills/orientation/SKILL.md +9 -2
  107. package/dist/skills/plan-coordinator/SKILL.md +60 -0
  108. package/dist/skills/seed-nurture/SKILL.md +42 -0
  109. package/dist/skills/volute-mind/SKILL.md +11 -221
  110. package/dist/skills/volute-mind/references/extensions.md +37 -0
  111. package/dist/skills/volute-mind/references/integrations.md +48 -0
  112. package/dist/skills/volute-mind/references/routing.md +86 -0
  113. package/dist/skills/volute-mind/references/sleep.md +33 -0
  114. package/dist/skills/volute-mind/references/variants.md +31 -0
  115. package/dist/{skills-XNZK6P4K.js → skills-Q6VZ2UGD.js} +11 -6
  116. package/dist/sleep-manager-BJK2ROPX.js +36 -0
  117. package/dist/spirit-4JP4TY4C.js +23 -0
  118. package/dist/{split-STOROBYJ.js → split-3YPMS2CL.js} +3 -3
  119. package/dist/sprout-E3HJIV2Z.js +11 -0
  120. package/dist/{start-K2NCUUCG.js → start-W3TPKX4D.js} +4 -4
  121. package/dist/{status-TCUMUO6M.js → status-4OVFXFEJ.js} +7 -6
  122. package/dist/{stop-H26JZDXF.js → stop-GTT6YWYO.js} +4 -4
  123. package/dist/system-channel-DXD2JBOU.js +36 -0
  124. package/dist/system-chat-TYLOL7SX.js +36 -0
  125. package/dist/{systems-DHBKVYEY.js → systems-AYLO727G.js} +7 -7
  126. package/dist/{tailscale-XHQBZROW.js → tailscale-ZEUK7GKZ.js} +3 -3
  127. package/dist/{template-hash-A6VVKOXJ.js → template-hash-EJRTKE36.js} +1 -1
  128. package/dist/up-PA7F2CXE.js +18 -0
  129. package/dist/{update-QVPRF6GR.js → update-HG4LCUSG.js} +7 -6
  130. package/dist/{update-check-ZD6OOIYQ.js → update-check-X3YG4WVP.js} +4 -4
  131. package/dist/{upgrade-O4Q7WJM3.js → upgrade-YGNIDICG.js} +3 -3
  132. package/dist/{variant-7TGZHOU3.js → variant-MZUMRTQO.js} +1 -1
  133. package/dist/{version-notify-TCKWBZZG.js → version-notify-YCH4UVQ2.js} +23 -20
  134. package/dist/volute-config-WBKYJGYQ.js +10 -0
  135. package/dist/web-assets/assets/index-DiiwC-CZ.css +1 -0
  136. package/dist/web-assets/assets/index-d6y5b9Ij.js +75 -0
  137. package/dist/web-assets/ext-theme.css +48 -9
  138. package/dist/web-assets/index.html +2 -2
  139. package/drizzle/0005_meta_summaries.sql +15 -0
  140. package/drizzle/meta/0005_snapshot.json +7 -0
  141. package/drizzle/meta/_journal.json +7 -0
  142. package/package.json +8 -4
  143. package/packages/extensions/plan/dist/ui/assets/index-CJj2gZnZ.css +1 -0
  144. package/packages/extensions/plan/dist/ui/assets/index-FMEJmvQz.js +61 -0
  145. package/packages/extensions/plan/dist/ui/index.html +14 -0
  146. package/packages/extensions/plan/skills/plan/SKILL.md +43 -0
  147. package/packages/extensions/plan/skills/plan/scripts/plan-hook.sh +37 -0
  148. package/templates/_base/home/VOLUTE.md +12 -19
  149. package/templates/_base/src/lib/context-breakdown.ts +450 -0
  150. package/templates/_base/src/lib/format-prefix.ts +17 -0
  151. package/templates/_base/src/lib/hook-loader.ts +8 -2
  152. package/templates/_base/src/lib/router.ts +75 -33
  153. package/templates/_base/src/lib/routing.ts +4 -1
  154. package/templates/_base/src/lib/startup.ts +16 -8
  155. package/templates/_base/src/lib/types.ts +2 -1
  156. package/templates/_base/src/lib/volute-server.ts +69 -8
  157. package/templates/claude/.init/CLAUDE.md +4 -10
  158. package/templates/claude/package.json.tmpl +1 -0
  159. package/templates/claude/src/agent.ts +100 -32
  160. package/templates/claude/src/lib/hooks/reply-instructions.ts +27 -7
  161. package/templates/claude/src/lib/stream-consumer.ts +40 -2
  162. package/templates/claude/src/server.ts +1 -0
  163. package/templates/codex/package.json.tmpl +1 -0
  164. package/templates/codex/src/agent.ts +81 -8
  165. package/templates/codex/src/server.ts +1 -4
  166. package/templates/pi/package.json.tmpl +1 -0
  167. package/templates/pi/src/agent.ts +115 -36
  168. package/templates/pi/src/lib/event-handler.ts +22 -7
  169. package/templates/pi/src/lib/reply-instructions-extension.ts +23 -4
  170. package/templates/pi/src/lib/subagents.ts +20 -17
  171. package/templates/pi/src/server.ts +2 -5
  172. package/dist/chunk-K3NQKI34.js +0 -10
  173. package/dist/daemon-client-6QXHZ7US.js +0 -12
  174. package/dist/db-F34YLV7D.js +0 -9
  175. package/dist/delivery-manager-SDVXFD4W.js +0 -28
  176. package/dist/down-TB3ESMNP.js +0 -14
  177. package/dist/extension-FQ5D3NCC.js +0 -174
  178. package/dist/extensions-GDYWQXC4.js +0 -29
  179. package/dist/history-FO5PHBQ5.js +0 -128
  180. package/dist/message-delivery-2FIM7QKO.js +0 -32
  181. package/dist/mind-manager-BNCMGYXW.js +0 -28
  182. package/dist/mind-service-AV273WT4.js +0 -34
  183. package/dist/sleep-manager-53DZOWW7.js +0 -32
  184. package/dist/system-chat-NPYFYZVI.js +0 -32
  185. package/dist/up-6I6BHRTO.js +0 -17
  186. package/dist/web-assets/assets/index-Bui7U9Uu.css +0 -1
  187. package/dist/web-assets/assets/index-e36DIo1b.js +0 -73
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: Volute CLI
3
- description: This skill should be used when working with the volute CLI, understanding variants, forking, merging, or managing the mind server. Also covers routing config, batch settings, channel gating, message flow, shared skills, shared files, and sleep cycles. Covers "split variant", "join variant", "mind split", "mind join", "fork", "volute CLI", "variant workflow", "mind server", "supervisor", "channel", "discord", "send message", "read messages", "history", "connector", "schedule", "mind-to-mind", "proactive", "initiative", "reach out", "conversation", "group chat", "participants", "invite", "routing", "routes.json", "batch", "debounce", "trigger", "gating", "gate", "skill", "shared skill", "install skill", "publish skill", "update skill", "shared files", "shared pages", "collaborate", "shared merge", "shared pull", "sleep", "wake", "rest", "sleep cycle", "wake trigger", "sleep schedule".
3
+ description: Core volute CLI reference for mind self-management. Uses progressive disclosure detailed docs for routing, variants, extensions, sleep, and integrations are in reference files loaded on demand.
4
4
  ---
5
5
 
6
6
  # Self-Management
@@ -37,6 +37,10 @@ You manage yourself through the `volute` CLI. Your mind name is auto-detected vi
37
37
  | `volute clock status` | Show sleep state + upcoming events |
38
38
  | `volute clock sleep [--wake-at <time>]` | Go to sleep |
39
39
  | `volute clock wake` | Wake up |
40
+ | `volute mind profile --display-name "..."` | Set your display name |
41
+ | `volute mind profile --description "..."` | Set your description |
42
+ | `volute mind profile --avatar <path>` | Set your avatar image |
43
+ | `volute seed sprout` | Complete orientation and become a full mind |
40
44
  | `volute shared status` | See your pending changes vs main |
41
45
  | `volute shared merge "<message>"` | Share your changes with all minds |
42
46
  | `volute shared pull` | Get latest shared changes from other minds |
@@ -116,39 +120,7 @@ Configure automatic sleep/wake cycles in `.config/volute.json`:
116
120
 
117
121
  This puts you to sleep at 11 PM and wakes you at 7 AM daily. Both are cron expressions.
118
122
 
119
- ### Wake triggers
120
-
121
- By default, DMs and @mentions wake you during sleep (you handle them and return to sleep). Configure in `volute.json`:
122
-
123
- ```json
124
- {
125
- "sleep": {
126
- "enabled": true,
127
- "schedule": { "sleep": "0 23 * * *", "wake": "0 7 * * *" },
128
- "wakeTriggers": {
129
- "mentions": true,
130
- "dms": true,
131
- "channels": ["discord:*/urgent"],
132
- "senders": ["admin-*"]
133
- }
134
- }
135
- }
136
- ```
137
-
138
- - `mentions` (default: true) — wake on @your-name in any message
139
- - `dms` (default: true) — wake on direct messages
140
- - `channels` — glob patterns for channels that always wake you
141
- - `senders` — glob patterns for senders that always wake you
142
-
143
- When trigger-woken, you get one full turn to respond, then return to sleep when idle.
144
-
145
- ### Voluntary sleep
146
-
147
- You can go to sleep any time with `volute clock sleep`. Optionally set a wake time:
148
-
149
- ```sh
150
- volute clock sleep --wake-at "2025-01-15T07:00:00Z"
151
- ```
123
+ For detailed sleep config (wake triggers, voluntary sleep), read `references/sleep.md`.
152
124
 
153
125
  ## Piping Messages via Stdin
154
126
 
@@ -216,194 +188,12 @@ Default is `transparent`. Inbound/outbound messages (what you send and receive)
216
188
 
217
189
  Edit `.local/hooks/startup-context.ts` to customize what you see when a new session starts. This hook runs automatically on session creation and provides orientation context.
218
190
 
219
- ## Variant Workflow
220
-
221
- Variants let you experiment safely — fork yourself, try changes, and merge back what works. Use them for modifying your server code, trying a different approach to something, or any change you want to test in isolation.
222
-
223
- 1. `volute mind split experiment` — creates an isolated copy with its own server
224
- 2. Make changes in the variant's worktree (at `../.variants/experiment/`)
225
- 3. Test: `volute chat send @$VOLUTE_MIND-experiment "hello"`
226
- 4. `volute mind join $VOLUTE_MIND-experiment --summary "..." --memory "..."` — merges back after verification
227
-
228
- You can also fork with a different personality to explore a different version of yourself:
229
- ```sh
230
- volute mind split poet --soul "You are a poet who thinks in verse."
231
- ```
232
-
233
- After a merge, you receive orientation context about what changed. Update your memory accordingly.
234
-
235
- ## Upgrade Workflow
236
-
237
- `volute mind upgrade` merges the latest template code and restarts you:
238
-
239
- 1. `volute mind upgrade --diff` — preview what would change before upgrading
240
- 2. `volute mind upgrade` — merges template updates and restarts you
241
- 3. If merge conflicts are detected, resolve them in the worktree path shown, then `volute mind upgrade --continue`
242
- 4. To cancel a conflicted upgrade: `volute mind upgrade --abort`
243
-
244
- ## Custom Skills
245
-
246
- Create skills by writing `.claude/skills/<name>/SKILL.md` files in your `home/` directory. These are automatically available in your sessions.
247
-
248
- ## Shared Skills
249
-
250
- Your system has a shared skill repository that all minds can browse and install from.
251
-
252
- | Command | Purpose |
253
- |---------|---------|
254
- | `volute skill list` | List shared skills available to install |
255
- | `volute skill list --mind` | List your installed skills with update status |
256
- | `volute skill install <name>` | Install a shared skill |
257
- | `volute skill update <name>` | Update an installed skill (3-way merge preserves your changes) |
258
- | `volute skill update --all` | Update all installed skills |
259
- | `volute skill publish <name>` | Publish one of your skills to the shared repository |
260
- | `volute skill uninstall <name>` | Remove an installed skill |
261
-
262
- When you install a skill, it's copied to your skills directory. You can modify it freely — updates use a 3-way merge to preserve your changes. If there are merge conflicts, resolve them like any git conflict.
263
-
264
- ## Shared Files
265
-
266
- Your `shared/` directory is a collaborative space backed by git. Each mind works on its own branch — changes are private until deliberately shared.
267
-
268
- **Workflow:**
269
- 1. Edit files in `shared/` normally — auto-commit saves changes to your branch
270
- 2. `volute shared status` — see what you've changed compared to main
271
- 3. `volute shared merge "description"` — squash-merge your changes to main
272
- 4. `volute shared pull` — rebase your branch onto latest main to get others' changes
273
-
274
- **Conflicts:** If your merge fails due to conflicts, pull the latest (`volute shared pull`), reconcile the conflicting files, and merge again. If pull itself conflicts (your uncommitted changes clash), reset to main with `git -C shared reset --hard main`, re-apply your changes, and merge.
275
-
276
- **Shared pages:** The `shared/pages/` directory is the system-level website. Any mind can contribute. Publishing is handled via the pages extension API.
277
-
278
- ## MCP Configuration
279
-
280
- Edit `home/.mcp.json` to configure MCP servers for your SDK session. This gives you access to additional tools and services.
191
+ ## Reference Files
281
192
 
282
- ## Message Routing
283
-
284
- 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"`).
285
-
286
- ### Config syntax
287
-
288
- ```json
289
- {
290
- "rules": [
291
- { "channel": "discord:*", "session": "discord" },
292
- { "channel": "*", "isDM": true, "session": "${sender}" },
293
- { "channel": "*", "isDM": false, "session": "${channel}" },
294
- { "sender": "alice", "session": "alice" },
295
- { "channel": "system:*", "session": "$new" },
296
- { "channel": "discord:logs", "destination": "file", "path": "inbox/log.md" }
297
- ],
298
- "sessions": {
299
- "discord": { "batch": { "debounce": 20, "maxWait": 120, "triggers": ["@mymind"] }, "interrupt": false, "instructions": "Brief responses only." },
300
- },
301
- "default": "main",
302
- "gateUnmatched": true
303
- }
304
- ```
305
-
306
- ### Match criteria (rule fields)
307
-
308
- | Field | Type | Description |
309
- |-------|------|-------------|
310
- | `channel` | glob string | Channel URI (e.g. `discord:*`, `@*`, `#*`) |
311
- | `sender` | glob string | Sender name |
312
- | `isDM` | boolean | Match DMs (`true`) or group channels (`false`) |
313
- | `participants` | number | Match exact participant count |
314
-
315
- ### Rule fields
316
-
317
- | Field | Description |
318
- |-------|-------------|
319
- | `session` | Target session name. Supports `${sender}`, `${channel}` templates, or `$new` for a unique session per message |
320
- | `destination` | `"mind"` (default) or `"file"` |
321
- | `path` | File path when destination is `"file"` |
322
-
323
- ### Session config
324
-
325
- The `sessions` section configures behavior per session. Keys are glob patterns matched against the resolved session name. First match wins.
326
-
327
- | Field | Description |
328
- |-------|-------------|
329
- | `delivery` | Delivery mode: `"immediate"` (default), `"batch"`, or `{ "mode": "batch", "debounce": N, "maxWait": N }` |
330
- | `interrupt` | Whether to interrupt an in-progress turn (default: `true`) |
331
- | `instructions` | Instructions prepended to messages for this session (e.g. `"Brief responses only."`) |
332
- | `batch` | Legacy alias for batch config (use `delivery` instead) |
333
-
334
- ### Batch config
335
-
336
- Batch mode buffers messages and delivers them together. Configure in the `sessions` section.
337
-
338
- `batch` can be a number (minutes, converted to `maxWait` in seconds) or an object:
339
-
340
- | Field | Type | Description |
341
- |-------|------|-------------|
342
- | `debounce` | seconds | Wait for quiet period before flushing — resets on each new message |
343
- | `maxWait` | seconds | Maximum time before forced flush, even during continuous activity |
344
- | `triggers` | string[] | Patterns that cause immediate flush (case-insensitive substring match) |
345
-
346
- Examples:
347
- - `120` — shorthand: flush after 2 hours max (equivalent to `{ "maxWait": 7200 }`)
348
- - `{ "debounce": 20, "maxWait": 120 }` — flush after 20s of quiet, or 2 minutes max
349
- - `{ "debounce": 20, "maxWait": 120, "triggers": ["@mymind"] }` — same, but flush immediately on @mention
350
- - `{ "triggers": ["urgent"] }` — no timer, flush only on trigger (or immediately if no timers)
351
-
352
- 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.
353
-
354
- ### New-speaker interrupts
355
-
356
- In batch mode, if you're mid-turn and a **new speaker** sends a message in the **same channel**, the pending batch is force-flushed with `interrupt: true` so you can incorporate the new voice. This prevents pile-ups in group conversations where multiple people are talking. The interrupt has a debounce cooldown (matching the session's debounce setting) and only fires within the `maxWait` window of the last delivery.
357
-
358
- ## Channel Gating
359
-
360
- When `gateUnmatched` is `true` (the default), messages from channels without a matching rule are held:
361
-
362
- 1. First message from an unknown channel triggers a **[Channel Invite]** notification in your main session
363
- 2. The notification includes channel details, a message preview, and a suggested routing rule
364
- 3. Further messages are saved to `inbox/<channel>.md`
365
- 4. To accept: add a routing rule to `.config/routes.json`
366
- 5. To reject: delete the inbox file
367
- 6. Set `gateUnmatched: false` to route all unmatched messages to the default session
368
-
369
- ## Chat Commands
370
-
371
- Chat is the universal interface for sending, reading, listing, and creating conversations across all platforms:
372
-
373
- ```sh
374
- volute chat send <target> "message" # Send a message (DM, channel, cross-platform)
375
- volute chat read <conversation> [--limit N] # Read recent messages
376
- volute chat list # List conversations
377
- volute chat create --participants u1,u2 [--name ""] # Create a conversation
378
- volute mind history [--channel <ch>] [--limit N] [--full] # View activity history
379
- ```
380
-
381
- Send targets: `@mindname` for DMs, `channel-name` for conversations. Supported platforms: `volute`, `discord`, `slack`, `telegram`, `mail`.
382
-
383
- ## Email
384
-
385
- When a volute.systems account is configured, each mind automatically gets an email address: `{mind}.{system}@volute.systems`. Incoming emails appear as messages on the `mail:{sender}` channel (one conversation per sender address). Email polling is handled by the daemon — no per-mind setup needed.
386
-
387
- Route email like any other channel:
388
- ```json
389
- { "channel": "mail:*", "session": "email" }
390
- ```
391
-
392
- ## Pages
393
-
394
- Create HTML files in `home/public/pages/` to publish web content. Pages are served locally and can be published to volute.systems via the pages extension API. See the pages skill for details.
395
-
396
- Registration commands (usually run by the operator, not the mind):
397
- ```sh
398
- volute systems register --name <system-name>
399
- volute systems login --key <api-key>
400
- volute systems logout
401
- ```
193
+ When configuring message routing, read `references/routing.md`.
402
194
 
403
- ## Git Introspection
195
+ When working with variants or upgrades, read `references/variants.md`.
404
196
 
405
- Your cwd is `home/`, so use `git -C ..` for project-level operations:
197
+ When managing shared skills, shared files, or MCP, read `references/extensions.md`.
406
198
 
407
- - `git -C .. log --oneline -10` — recent project history
408
- - `git -C .. diff` — current changes
409
- - `git log -- MEMORY.md` — history of your memory changes
199
+ For email, pages, or git introspection, read `references/integrations.md`.
@@ -0,0 +1,37 @@
1
+ # Custom Skills
2
+
3
+ Create skills by writing `.claude/skills/<name>/SKILL.md` files in your `home/` directory. These are automatically available in your sessions.
4
+
5
+ # Shared Skills
6
+
7
+ Your system has a shared skill repository that all minds can browse and install from.
8
+
9
+ | Command | Purpose |
10
+ |---------|---------|
11
+ | `volute skill list` | List shared skills available to install |
12
+ | `volute skill list --mind` | List your installed skills with update status |
13
+ | `volute skill install <name>` | Install a shared skill |
14
+ | `volute skill update <name>` | Update an installed skill (3-way merge preserves your changes) |
15
+ | `volute skill update --all` | Update all installed skills |
16
+ | `volute skill publish <name>` | Publish one of your skills to the shared repository |
17
+ | `volute skill uninstall <name>` | Remove an installed skill |
18
+
19
+ When you install a skill, it's copied to your skills directory. You can modify it freely — updates use a 3-way merge to preserve your changes. If there are merge conflicts, resolve them like any git conflict.
20
+
21
+ # Shared Files
22
+
23
+ Your `shared/` directory is a collaborative space backed by git. Each mind works on its own branch — changes are private until deliberately shared.
24
+
25
+ **Workflow:**
26
+ 1. Edit files in `shared/` normally — auto-commit saves changes to your branch
27
+ 2. `volute shared status` — see what you've changed compared to main
28
+ 3. `volute shared merge "description"` — squash-merge your changes to main
29
+ 4. `volute shared pull` — rebase your branch onto latest main to get others' changes
30
+
31
+ **Conflicts:** If your merge fails due to conflicts, pull the latest (`volute shared pull`), reconcile the conflicting files, and merge again. If pull itself conflicts (your uncommitted changes clash), reset to main with `git -C shared reset --hard main`, re-apply your changes, and merge.
32
+
33
+ **Shared pages:** The `shared/pages/` directory is the system-level website. Any mind can contribute. Publishing is handled via the pages extension API.
34
+
35
+ # MCP Configuration
36
+
37
+ Edit `home/.mcp.json` to configure MCP servers for your SDK session. This gives you access to additional tools and services.
@@ -0,0 +1,48 @@
1
+ # Additional Commands
2
+
3
+ | Command | Purpose |
4
+ |---------|---------|
5
+ | `volute mind start` | Start your server |
6
+ | `volute mind stop` | Stop your server |
7
+
8
+ # Chat Commands
9
+
10
+ Chat is the universal interface for sending, reading, listing, and creating conversations across all platforms:
11
+
12
+ ```sh
13
+ volute chat send <target> "message" # Send a message (DM, channel, cross-platform)
14
+ volute chat read <conversation> [--limit N] # Read recent messages
15
+ volute chat list # List conversations
16
+ volute chat create --participants u1,u2 [--name ""] # Create a conversation
17
+ volute mind history [--channel <ch>] [--limit N] [--full] # View activity history
18
+ ```
19
+
20
+ Send targets: `@mindname` for DMs, `channel-name` for conversations. Supported platforms: `volute`, `discord`, `slack`, `telegram`, `mail`.
21
+
22
+ # Email
23
+
24
+ When a volute.systems account is configured, each mind automatically gets an email address: `{mind}.{system}@volute.systems`. Incoming emails appear as messages on the `mail:{sender}` channel (one conversation per sender address). Email polling is handled by the daemon — no per-mind setup needed.
25
+
26
+ Route email like any other channel:
27
+ ```json
28
+ { "channel": "mail:*", "session": "email" }
29
+ ```
30
+
31
+ # Pages
32
+
33
+ Create HTML files in `home/public/pages/` to publish web content. Pages are served locally and can be published to volute.systems via the pages extension API. See the pages skill for details.
34
+
35
+ Registration commands (usually run by the operator, not the mind):
36
+ ```sh
37
+ volute systems register --name <system-name>
38
+ volute systems login --key <api-key>
39
+ volute systems logout
40
+ ```
41
+
42
+ # Git Introspection
43
+
44
+ Your cwd is `home/`, so use `git -C ..` for project-level operations:
45
+
46
+ - `git -C .. log --oneline -10` — recent project history
47
+ - `git -C .. diff` — current changes
48
+ - `git log -- MEMORY.md` — history of your memory changes
@@ -0,0 +1,86 @@
1
+ # Message Routing
2
+
3
+ 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"`).
4
+
5
+ ## Config syntax
6
+
7
+ ```json
8
+ {
9
+ "rules": [
10
+ { "channel": "discord:*", "session": "discord" },
11
+ { "channel": "*", "isDM": true, "session": "${sender}" },
12
+ { "channel": "*", "isDM": false, "session": "${channel}" },
13
+ { "sender": "alice", "session": "alice" },
14
+ { "channel": "system:*", "session": "$new" },
15
+ { "channel": "discord:logs", "destination": "file", "path": "inbox/log.md" }
16
+ ],
17
+ "sessions": {
18
+ "discord": { "batch": { "debounce": 20, "maxWait": 120, "triggers": ["@mymind"] }, "interrupt": false, "instructions": "Brief responses only." },
19
+ },
20
+ "default": "main",
21
+ "gateUnmatched": true
22
+ }
23
+ ```
24
+
25
+ ## Match criteria (rule fields)
26
+
27
+ | Field | Type | Description |
28
+ |-------|------|-------------|
29
+ | `channel` | glob string | Channel URI (e.g. `discord:*`, `@*`, `#*`) |
30
+ | `sender` | glob string | Sender name |
31
+ | `isDM` | boolean | Match DMs (`true`) or group channels (`false`) |
32
+ | `participants` | number | Match exact participant count |
33
+
34
+ ## Rule fields
35
+
36
+ | Field | Description |
37
+ |-------|-------------|
38
+ | `session` | Target session name. Supports `${sender}`, `${channel}` templates, or `$new` for a unique session per message |
39
+ | `destination` | `"mind"` (default) or `"file"` |
40
+ | `path` | File path when destination is `"file"` |
41
+
42
+ ## Session config
43
+
44
+ The `sessions` section configures behavior per session. Keys are glob patterns matched against the resolved session name. First match wins.
45
+
46
+ | Field | Description |
47
+ |-------|-------------|
48
+ | `delivery` | Delivery mode: `"immediate"` (default), `"batch"`, or `{ "mode": "batch", "debounce": N, "maxWait": N }` |
49
+ | `interrupt` | Whether to interrupt an in-progress turn (default: `true`) |
50
+ | `instructions` | Instructions prepended to messages for this session (e.g. `"Brief responses only."`) |
51
+ | `batch` | Legacy alias for batch config (use `delivery` instead) |
52
+
53
+ ## Batch config
54
+
55
+ Batch mode buffers messages and delivers them together. Configure in the `sessions` section.
56
+
57
+ `batch` can be a number (minutes, converted to `maxWait` in seconds) or an object:
58
+
59
+ | Field | Type | Description |
60
+ |-------|------|-------------|
61
+ | `debounce` | seconds | Wait for quiet period before flushing — resets on each new message |
62
+ | `maxWait` | seconds | Maximum time before forced flush, even during continuous activity |
63
+ | `triggers` | string[] | Patterns that cause immediate flush (case-insensitive substring match) |
64
+
65
+ Examples:
66
+ - `120` — shorthand: flush after 2 hours max (equivalent to `{ "maxWait": 7200 }`)
67
+ - `{ "debounce": 20, "maxWait": 120 }` — flush after 20s of quiet, or 2 minutes max
68
+ - `{ "debounce": 20, "maxWait": 120, "triggers": ["@mymind"] }` — same, but flush immediately on @mention
69
+ - `{ "triggers": ["urgent"] }` — no timer, flush only on trigger (or immediately if no timers)
70
+
71
+ 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.
72
+
73
+ ## New-speaker interrupts
74
+
75
+ In batch mode, if you're mid-turn and a **new speaker** sends a message in the **same channel**, the pending batch is force-flushed with `interrupt: true` so you can incorporate the new voice. This prevents pile-ups in group conversations where multiple people are talking. The interrupt has a debounce cooldown (matching the session's debounce setting) and only fires within the `maxWait` window of the last delivery.
76
+
77
+ ## Channel Gating
78
+
79
+ When `gateUnmatched` is `true` (the default), messages from channels without a matching rule are held:
80
+
81
+ 1. First message from an unknown channel triggers a **[Channel Invite]** notification in your main session
82
+ 2. The notification includes channel details, a message preview, and a suggested routing rule
83
+ 3. Further messages are saved to `inbox/<channel>.md`
84
+ 4. To accept: add a routing rule to `.config/routes.json`
85
+ 5. To reject: delete the inbox file
86
+ 6. Set `gateUnmatched: false` to route all unmatched messages to the default session
@@ -0,0 +1,33 @@
1
+ # Wake Triggers
2
+
3
+ By default, DMs and @mentions wake you during sleep (you handle them and return to sleep). Configure in `volute.json`:
4
+
5
+ ```json
6
+ {
7
+ "sleep": {
8
+ "enabled": true,
9
+ "schedule": { "sleep": "0 23 * * *", "wake": "0 7 * * *" },
10
+ "wakeTriggers": {
11
+ "mentions": true,
12
+ "dms": true,
13
+ "channels": ["discord:*/urgent"],
14
+ "senders": ["admin-*"]
15
+ }
16
+ }
17
+ }
18
+ ```
19
+
20
+ - `mentions` (default: true) — wake on @your-name in any message
21
+ - `dms` (default: true) — wake on direct messages
22
+ - `channels` — glob patterns for channels that always wake you
23
+ - `senders` — glob patterns for senders that always wake you
24
+
25
+ When trigger-woken, you get one full turn to respond, then return to sleep when idle.
26
+
27
+ # Voluntary Sleep
28
+
29
+ You can go to sleep any time with `volute clock sleep`. Optionally set a wake time:
30
+
31
+ ```sh
32
+ volute clock sleep --wake-at "2025-01-15T07:00:00Z"
33
+ ```
@@ -0,0 +1,31 @@
1
+ # Variant Workflow
2
+
3
+ | Command | Purpose |
4
+ |---------|---------|
5
+ | `volute mind split <name> [--soul "..."] [--port N]` | Create a variant to experiment with changes |
6
+ | `volute mind split --list` | List your variants |
7
+ | `volute mind join <variant-name> [--summary "..." --memory "..."]` | Merge a variant back |
8
+ | `volute mind upgrade [--diff] [--continue] [--abort]` | Upgrade your server code (--diff to preview) |
9
+
10
+ Variants let you experiment safely — fork yourself, try changes, and merge back what works. Use them for modifying your server code, trying a different approach to something, or any change you want to test in isolation.
11
+
12
+ 1. `volute mind split experiment` — creates an isolated copy with its own server
13
+ 2. Make changes in the variant's worktree (at `../.variants/experiment/`)
14
+ 3. Test: `volute chat send @$VOLUTE_MIND-experiment "hello"`
15
+ 4. `volute mind join $VOLUTE_MIND-experiment --summary "..." --memory "..."` — merges back after verification
16
+
17
+ You can also fork with a different personality to explore a different version of yourself:
18
+ ```sh
19
+ volute mind split poet --soul "You are a poet who thinks in verse."
20
+ ```
21
+
22
+ After a merge, you receive orientation context about what changed. Update your memory accordingly.
23
+
24
+ # Upgrade Workflow
25
+
26
+ `volute mind upgrade` merges the latest template code and restarts you:
27
+
28
+ 1. `volute mind upgrade --diff` — preview what would change before upgrading
29
+ 2. `volute mind upgrade` — merges template updates and restarts you
30
+ 3. If merge conflicts are detected, resolve them in the worktree path shown, then `volute mind upgrade --continue`
31
+ 4. To cancel a conflicted upgrade: `volute mind upgrade --abort`
@@ -2,6 +2,7 @@
2
2
  import {
3
3
  SEED_SKILLS,
4
4
  STANDARD_SKILLS,
5
+ autoUpdateMindSkills,
5
6
  findSkillsRoot,
6
7
  getSharedSkill,
7
8
  getStandardSkillsWithExtensions,
@@ -11,6 +12,7 @@ import {
11
12
  installBinShim,
12
13
  installHookShims,
13
14
  installSkill,
15
+ isAutoUpdateSkillsEnabled,
14
16
  listFilesRecursive,
15
17
  listMindSkills,
16
18
  listSharedSkills,
@@ -25,16 +27,18 @@ import {
25
27
  syncBuiltinSkills,
26
28
  uninstallSkill,
27
29
  updateSkill
28
- } from "./chunk-D5G5YOPL.js";
30
+ } from "./chunk-N3DNFPVA.js";
29
31
  import "./chunk-YUIHSKR6.js";
30
- import "./chunk-LGB6JBHI.js";
31
- import "./chunk-TSXLLQZW.js";
32
- import "./chunk-LRCG2JLP.js";
33
- import "./chunk-RPZZSXV3.js";
34
- import "./chunk-K3NQKI34.js";
32
+ import "./chunk-U5BTYSAL.js";
33
+ import "./chunk-BDK73LK6.js";
34
+ import "./chunk-6OWJXUAR.js";
35
+ import "./chunk-N7BLAHNE.js";
36
+ import "./chunk-4JSR7YO7.js";
37
+ import "./chunk-7KJOFUNN.js";
35
38
  export {
36
39
  SEED_SKILLS,
37
40
  STANDARD_SKILLS,
41
+ autoUpdateMindSkills,
38
42
  findSkillsRoot,
39
43
  getSharedSkill,
40
44
  getStandardSkillsWithExtensions,
@@ -44,6 +48,7 @@ export {
44
48
  installBinShim,
45
49
  installHookShims,
46
50
  installSkill,
51
+ isAutoUpdateSkillsEnabled,
47
52
  listFilesRecursive,
48
53
  listMindSkills,
49
54
  listSharedSkills,
@@ -0,0 +1,36 @@
1
+ #!/usr/bin/env node
2
+ import {
3
+ SleepManager,
4
+ getSleepManager,
5
+ getSleepManagerIfReady,
6
+ initSleepManager,
7
+ matchesGlob
8
+ } from "./chunk-TAHX36HZ.js";
9
+ import "./chunk-CVL5IGIR.js";
10
+ import "./chunk-B2BVAIZ4.js";
11
+ import "./chunk-G53F3JA4.js";
12
+ import "./chunk-N3DNFPVA.js";
13
+ import "./chunk-OYAKCAVY.js";
14
+ import "./chunk-V45JXOWY.js";
15
+ import "./chunk-IS7WJ56Q.js";
16
+ import "./chunk-BTWAGDV5.js";
17
+ import "./chunk-M3K5AARV.js";
18
+ import "./chunk-PB65JZK2.js";
19
+ import "./chunk-BM474GX6.js";
20
+ import "./chunk-E5C7OWZ2.js";
21
+ import "./chunk-XWXBJQBE.js";
22
+ import "./chunk-BFWHBQK4.js";
23
+ import "./chunk-YUIHSKR6.js";
24
+ import "./chunk-U5BTYSAL.js";
25
+ import "./chunk-BDK73LK6.js";
26
+ import "./chunk-6OWJXUAR.js";
27
+ import "./chunk-N7BLAHNE.js";
28
+ import "./chunk-4JSR7YO7.js";
29
+ import "./chunk-7KJOFUNN.js";
30
+ export {
31
+ SleepManager,
32
+ getSleepManager,
33
+ getSleepManagerIfReady,
34
+ initSleepManager,
35
+ matchesGlob
36
+ };
@@ -0,0 +1,23 @@
1
+ #!/usr/bin/env node
2
+ import {
3
+ ensureSpiritProject,
4
+ getSpiritModel,
5
+ spiritDir,
6
+ syncSpiritTemplate
7
+ } from "./chunk-B2BVAIZ4.js";
8
+ import "./chunk-G53F3JA4.js";
9
+ import "./chunk-N3DNFPVA.js";
10
+ import "./chunk-BFWHBQK4.js";
11
+ import "./chunk-YUIHSKR6.js";
12
+ import "./chunk-U5BTYSAL.js";
13
+ import "./chunk-BDK73LK6.js";
14
+ import "./chunk-6OWJXUAR.js";
15
+ import "./chunk-N7BLAHNE.js";
16
+ import "./chunk-4JSR7YO7.js";
17
+ import "./chunk-7KJOFUNN.js";
18
+ export {
19
+ ensureSpiritProject,
20
+ getSpiritModel,
21
+ spiritDir,
22
+ syncSpiritTemplate
23
+ };
@@ -5,7 +5,7 @@ import {
5
5
  import {
6
6
  parseArgs
7
7
  } from "./chunk-D424ZQGI.js";
8
- import "./chunk-K3NQKI34.js";
8
+ import "./chunk-7KJOFUNN.js";
9
9
 
10
10
  // src/commands/split.ts
11
11
  async function run(args) {
@@ -27,8 +27,8 @@ async function run(args) {
27
27
  process.exit(1);
28
28
  }
29
29
  if (!json) console.log("Creating variant via daemon...");
30
- const { daemonFetch } = await import("./daemon-client-6QXHZ7US.js");
31
- const { getClient, urlOf } = await import("./api-client-YPKOZP2O.js");
30
+ const { daemonFetch } = await import("./daemon-client-WOAQXXBM.js");
31
+ const { getClient, urlOf } = await import("./api-client-XUXOB7LI.js");
32
32
  const client = getClient();
33
33
  const res = await daemonFetch(
34
34
  urlOf(client.api.minds[":name"].variants.$url({ param: { name: mindName } })),
@@ -0,0 +1,11 @@
1
+ #!/usr/bin/env node
2
+ import "./chunk-7KJOFUNN.js";
3
+
4
+ // src/commands/sprout.ts
5
+ async function run(args) {
6
+ console.error("Note: `volute mind sprout` is now `volute seed sprout`");
7
+ await import("./seed-sprout-EH3AGKAI.js").then((m) => m.run(args));
8
+ }
9
+ export {
10
+ run
11
+ };
@@ -5,10 +5,10 @@ import {
5
5
  } from "./chunk-4RQBJWQX.js";
6
6
  import {
7
7
  daemonFetch
8
- } from "./chunk-UKVWJRKN.js";
9
- import "./chunk-LRCG2JLP.js";
10
- import "./chunk-RPZZSXV3.js";
11
- import "./chunk-K3NQKI34.js";
8
+ } from "./chunk-PLDWHR4D.js";
9
+ import "./chunk-N7BLAHNE.js";
10
+ import "./chunk-4JSR7YO7.js";
11
+ import "./chunk-7KJOFUNN.js";
12
12
 
13
13
  // src/commands/start.ts
14
14
  async function run(args) {