volute 0.33.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 (182) hide show
  1. package/dist/{accept-D5VBM7JW.js → accept-TW6V4WI4.js} +6 -6
  2. package/dist/{activity-events-XJO3P4RR.js → activity-events-BN7V6KCC.js} +4 -4
  3. package/dist/{ai-service-SBY2WG7O.js → ai-service-PSILB5WD.js} +5 -5
  4. package/dist/{api-client-YPKOZP2O.js → api-client-XUXOB7LI.js} +1 -1
  5. package/dist/api.d.ts +426 -3
  6. package/dist/{archive-INXYFVCW.js → archive-C2VEMQOR.js} +4 -4
  7. package/dist/{auth-GKCDSO4T.js → auth-ZFZXJZDQ.js} +5 -5
  8. package/dist/{bridge-TXWWPPOJ.js → bridge-O753D5F4.js} +6 -6
  9. package/dist/{chat-U5ZOME3O.js → chat-BHYX7DJ4.js} +9 -9
  10. package/dist/{chunk-M7UL5S3Q.js → chunk-2IOP6PHB.js} +1 -1
  11. package/dist/{chunk-NPKSDYA2.js → chunk-47XDEWWV.js} +5 -5
  12. package/dist/{chunk-RSX4OPZY.js → chunk-47ZPNLF4.js} +7 -7
  13. package/dist/{chunk-RPZZSXV3.js → chunk-4JSR7YO7.js} +20 -1
  14. package/dist/{chunk-N432I7QH.js → chunk-6OWJXUAR.js} +1 -1
  15. package/dist/{chunk-I5KY25PQ.js → chunk-6WAWMWR5.js} +1 -1
  16. package/dist/{chunk-NNB4WIG7.js → chunk-7F2SW2KD.js} +2 -2
  17. package/dist/chunk-7KJOFUNN.js +22 -0
  18. package/dist/{chunk-7J3HEVR7.js → chunk-B2BVAIZ4.js} +15 -9
  19. package/dist/{chunk-VH33ZWMW.js → chunk-BDK73LK6.js} +1 -1
  20. package/dist/{chunk-QTUVYI7W.js → chunk-BFWHBQK4.js} +1 -1
  21. package/dist/{chunk-JYVGHWEJ.js → chunk-BM474GX6.js} +3 -3
  22. package/dist/{chunk-LOEJ4HPQ.js → chunk-BTWAGDV5.js} +1 -1
  23. package/dist/{chunk-A2A4KLFE.js → chunk-CVL5IGIR.js} +596 -40
  24. package/dist/{chunk-RVGLDGMI.js → chunk-E5C7OWZ2.js} +20 -22
  25. package/dist/chunk-FYCALD4Q.js +23 -0
  26. package/dist/{chunk-SKLSMHXO.js → chunk-IS7WJ56Q.js} +1 -1
  27. package/dist/{chunk-2NGTS5UU.js → chunk-M3K5AARV.js} +1 -1
  28. package/dist/{chunk-ALEF47VT.js → chunk-MLOQKQNB.js} +1 -1
  29. package/dist/{chunk-C7I35G4R.js → chunk-N3DNFPVA.js} +41 -5
  30. package/dist/{chunk-LRCG2JLP.js → chunk-N7BLAHNE.js} +5 -1
  31. package/dist/{chunk-UKVWJRKN.js → chunk-PLDWHR4D.js} +1 -1
  32. package/dist/{chunk-3Z2DPESO.js → chunk-TAHX36HZ.js} +126 -81
  33. package/dist/{chunk-KIEPMIM5.js → chunk-U5BTYSAL.js} +1 -1
  34. package/dist/{chunk-GY5HBI7A.js → chunk-V45JXOWY.js} +2 -2
  35. package/dist/{chunk-JUKK7FPS.js → chunk-V6ZCNULL.js} +2 -2
  36. package/dist/{chunk-KVK2DLWI.js → chunk-XWXBJQBE.js} +2 -2
  37. package/dist/cli.js +23 -23
  38. package/dist/{clock-BVH3V6E3.js → clock-3X4DSC2N.js} +40 -25
  39. package/dist/{cloud-sync-4NWLMFVH.js → cloud-sync-TG3TIX5H.js} +21 -21
  40. package/dist/{config-H2H4UIF7.js → config-OROA5DUA.js} +4 -4
  41. package/dist/connectors/discord-bridge.js +1 -1
  42. package/dist/connectors/slack-bridge.js +1 -1
  43. package/dist/connectors/telegram-bridge.js +1 -1
  44. package/dist/{conversations-AWI5SZW2.js → conversations-HL2JP5GI.js} +5 -5
  45. package/dist/{create-YWD2TIP4.js → create-3SEKKI6P.js} +6 -6
  46. package/dist/{create-2FK7Z46Y.js → create-UOSOQ2HN.js} +4 -4
  47. package/dist/daemon-client-WOAQXXBM.js +12 -0
  48. package/dist/{daemon-restart-GOBUKLX7.js → daemon-restart-5ABHNXJZ.js} +9 -9
  49. package/dist/daemon.js +1747 -688
  50. package/dist/{db-RA45JBFG.js → db-PLEDCBHZ.js} +1 -1
  51. package/dist/db-RYX3SS2W.js +9 -0
  52. package/dist/{delete-QTGWEDBI.js → delete-KYOVWR23.js} +3 -3
  53. package/dist/delivery-manager-2BR5NZKF.js +32 -0
  54. package/dist/{delivery-router-FL45JL7N.js → delivery-router-D5ELDMS2.js} +4 -4
  55. package/dist/down-QVFN4UPK.js +15 -0
  56. package/dist/{env-JCOF2222.js → env-R34DT7XL.js} +12 -8
  57. package/dist/exec-DVLXKRIO.js +17 -0
  58. package/dist/{export-SUYRLI5Q.js → export-6ZXAXATG.js} +6 -6
  59. package/dist/extension-PM42QCID.js +97 -0
  60. package/dist/extensions-BBGVL5JC.js +38 -0
  61. package/dist/{files-65PMW5IK.js → files-VQV2VZQO.js} +7 -7
  62. package/dist/{import-DDUFE7AY.js → import-MK2I2T6F.js} +5 -5
  63. package/dist/{isolation-LLAYQYDY.js → isolation-62MKDZN3.js} +4 -4
  64. package/dist/{join-I5QEE3LG.js → join-DGYHTJUH.js} +3 -3
  65. package/dist/lib-DYEZMGW7.js +6588 -0
  66. package/dist/{list-JQ463EDA.js → list-C644WTHV.js} +18 -10
  67. package/dist/{login-D7ETSU4R.js → login-IIGEQPHL.js} +6 -6
  68. package/dist/{login-RIJF2F4G.js → login-KZQLMAWE.js} +4 -4
  69. package/dist/{logout-5MLHZALK.js → logout-AGTZVRGP.js} +4 -4
  70. package/dist/{logout-UZJRGY4Z.js → logout-KD6GXIJJ.js} +4 -4
  71. package/dist/message-delivery-V3R6NXJP.js +42 -0
  72. package/dist/{mind-IOJFLEM5.js → mind-BI4EPBVZ.js} +19 -19
  73. package/dist/{mind-activity-tracker-F6O4Q2SL.js → mind-activity-tracker-2ACNHA7B.js} +5 -5
  74. package/dist/mind-history-WOYFLQAI.js +264 -0
  75. package/dist/{mind-list-WUPMQDYQ.js → mind-list-6VPM7GUQ.js} +4 -4
  76. package/dist/mind-manager-MWW3BTS4.js +32 -0
  77. package/dist/{mind-profile-P67FEHOY.js → mind-profile-WPG42U5Y.js} +2 -2
  78. package/dist/mind-service-VIKZJK2M.js +38 -0
  79. package/dist/{mind-sleep-WW2IX7JT.js → mind-sleep-XDISJY74.js} +6 -6
  80. package/dist/{mind-status-L3EFFRPR.js → mind-status-7FTZWPZF.js} +4 -4
  81. package/dist/{mind-wake-VSSGW465.js → mind-wake-KIIKEI3A.js} +6 -6
  82. package/dist/{package-U3VFO273.js → package-V2WHWVG6.js} +8 -5
  83. package/dist/{read-EBY56C33.js → read-H5C26YO7.js} +20 -10
  84. package/dist/{read-stdin-HQJ7774D.js → read-stdin-PIRM6A2Y.js} +1 -1
  85. package/dist/{register-HD74C4TT.js → register-J27WP33N.js} +6 -6
  86. package/dist/{registry-PJ4S5PHQ.js → registry-UYV5S6QT.js} +3 -3
  87. package/dist/{reject-UJKFBHRO.js → reject-OEANJYIA.js} +6 -6
  88. package/dist/{restart-3UCMRUVC.js → restart-V5EGYBJG.js} +4 -4
  89. package/dist/{sandbox-GJOK4QLQ.js → sandbox-SI5HMBP3.js} +5 -5
  90. package/dist/scheduler-AGG3L2FO.js +32 -0
  91. package/dist/{schema-PA3M5ZKH.js → schema-ETMABTW4.js} +4 -2
  92. package/dist/{seed-QDYVLG74.js → seed-WNGI6PNW.js} +2 -2
  93. package/dist/{seed-check-S2IX25RL.js → seed-check-PXTH7YXS.js} +2 -2
  94. package/dist/{seed-cmd-DKOUFEAU.js → seed-cmd-VENFTGS3.js} +4 -4
  95. package/dist/{seed-create-4XBBOLRH.js → seed-create-663ALOKH.js} +6 -6
  96. package/dist/{seed-sprout-GQEIIQRT.js → seed-sprout-EH3AGKAI.js} +12 -12
  97. package/dist/{send-QIV2INHB.js → send-7FUUUZZH.js} +23 -10
  98. package/dist/{setup-TISPCO22.js → setup-GGMKENLN.js} +4 -4
  99. package/dist/{setup-XMCBE3LF.js → setup-Z3DEVWV7.js} +11 -11
  100. package/dist/{skill-PSQGRRJX.js → skill-DKNYJS4P.js} +14 -10
  101. package/dist/skills/plan-coordinator/SKILL.md +60 -0
  102. package/dist/skills/volute-mind/SKILL.md +7 -221
  103. package/dist/skills/volute-mind/references/extensions.md +37 -0
  104. package/dist/skills/volute-mind/references/integrations.md +48 -0
  105. package/dist/skills/volute-mind/references/routing.md +86 -0
  106. package/dist/skills/volute-mind/references/sleep.md +33 -0
  107. package/dist/skills/volute-mind/references/variants.md +31 -0
  108. package/dist/{skills-7FV7EJTE.js → skills-Q6VZ2UGD.js} +11 -7
  109. package/dist/sleep-manager-BJK2ROPX.js +36 -0
  110. package/dist/spirit-4JP4TY4C.js +23 -0
  111. package/dist/{split-STOROBYJ.js → split-3YPMS2CL.js} +3 -3
  112. package/dist/{sprout-WKLZXUIQ.js → sprout-E3HJIV2Z.js} +2 -2
  113. package/dist/{start-K2NCUUCG.js → start-W3TPKX4D.js} +4 -4
  114. package/dist/{status-3JBTFSMI.js → status-4OVFXFEJ.js} +7 -7
  115. package/dist/{stop-H26JZDXF.js → stop-GTT6YWYO.js} +4 -4
  116. package/dist/system-channel-DXD2JBOU.js +36 -0
  117. package/dist/system-chat-TYLOL7SX.js +36 -0
  118. package/dist/{systems-XRI52VCH.js → systems-AYLO727G.js} +7 -7
  119. package/dist/{tailscale-XHQBZROW.js → tailscale-ZEUK7GKZ.js} +3 -3
  120. package/dist/{template-hash-A6VVKOXJ.js → template-hash-EJRTKE36.js} +1 -1
  121. package/dist/up-PA7F2CXE.js +18 -0
  122. package/dist/{update-UD543CXX.js → update-HG4LCUSG.js} +7 -7
  123. package/dist/{update-check-ZD6OOIYQ.js → update-check-X3YG4WVP.js} +4 -4
  124. package/dist/{upgrade-O4Q7WJM3.js → upgrade-YGNIDICG.js} +3 -3
  125. package/dist/{variant-7TGZHOU3.js → variant-MZUMRTQO.js} +1 -1
  126. package/dist/{version-notify-NBI2MTJO.js → version-notify-YCH4UVQ2.js} +19 -19
  127. package/dist/{volute-config-HD7WWUQC.js → volute-config-WBKYJGYQ.js} +1 -1
  128. package/dist/web-assets/assets/index-DiiwC-CZ.css +1 -0
  129. package/dist/web-assets/assets/index-d6y5b9Ij.js +75 -0
  130. package/dist/web-assets/ext-theme.css +48 -9
  131. package/dist/web-assets/index.html +2 -2
  132. package/drizzle/0005_meta_summaries.sql +15 -0
  133. package/drizzle/meta/0005_snapshot.json +7 -0
  134. package/drizzle/meta/_journal.json +7 -0
  135. package/package.json +7 -4
  136. package/packages/extensions/plan/dist/ui/assets/index-CJj2gZnZ.css +1 -0
  137. package/packages/extensions/plan/dist/ui/assets/index-FMEJmvQz.js +61 -0
  138. package/packages/extensions/plan/dist/ui/index.html +14 -0
  139. package/packages/extensions/plan/skills/plan/SKILL.md +43 -0
  140. package/packages/extensions/plan/skills/plan/scripts/plan-hook.sh +37 -0
  141. package/templates/_base/home/VOLUTE.md +12 -19
  142. package/templates/_base/src/lib/context-breakdown.ts +450 -0
  143. package/templates/_base/src/lib/format-prefix.ts +17 -0
  144. package/templates/_base/src/lib/hook-loader.ts +8 -2
  145. package/templates/_base/src/lib/router.ts +75 -33
  146. package/templates/_base/src/lib/routing.ts +4 -1
  147. package/templates/_base/src/lib/startup.ts +16 -8
  148. package/templates/_base/src/lib/types.ts +2 -1
  149. package/templates/_base/src/lib/volute-server.ts +69 -8
  150. package/templates/claude/.init/CLAUDE.md +4 -10
  151. package/templates/claude/package.json.tmpl +1 -0
  152. package/templates/claude/src/agent.ts +100 -32
  153. package/templates/claude/src/lib/hooks/reply-instructions.ts +27 -7
  154. package/templates/claude/src/lib/stream-consumer.ts +2 -2
  155. package/templates/claude/src/server.ts +1 -0
  156. package/templates/codex/package.json.tmpl +1 -0
  157. package/templates/codex/src/agent.ts +80 -8
  158. package/templates/codex/src/server.ts +1 -4
  159. package/templates/pi/package.json.tmpl +1 -0
  160. package/templates/pi/src/agent.ts +115 -36
  161. package/templates/pi/src/lib/event-handler.ts +22 -7
  162. package/templates/pi/src/lib/reply-instructions-extension.ts +23 -4
  163. package/templates/pi/src/lib/subagents.ts +20 -17
  164. package/templates/pi/src/server.ts +2 -5
  165. package/dist/chunk-K3NQKI34.js +0 -10
  166. package/dist/daemon-client-6QXHZ7US.js +0 -12
  167. package/dist/db-F34YLV7D.js +0 -9
  168. package/dist/delivery-manager-PFAKEJTC.js +0 -32
  169. package/dist/down-FWWTEKXM.js +0 -15
  170. package/dist/extension-OBTGKQQD.js +0 -175
  171. package/dist/extensions-KYNTVTMO.js +0 -30
  172. package/dist/history-DKCDI3JO.js +0 -128
  173. package/dist/message-delivery-DFF5SJRM.js +0 -42
  174. package/dist/mind-manager-NBJF5D26.js +0 -32
  175. package/dist/mind-service-2MQ6UK5N.js +0 -38
  176. package/dist/scheduler-ZZ7XGQG6.js +0 -32
  177. package/dist/sleep-manager-JTXSN7NV.js +0 -36
  178. package/dist/spirit-VRONKFMF.js +0 -23
  179. package/dist/system-chat-JAPOJ3KE.js +0 -36
  180. package/dist/up-M5AS6SBV.js +0 -18
  181. package/dist/web-assets/assets/index-CWJrVveV.css +0 -1
  182. package/dist/web-assets/assets/index-DJt14FRI.js +0 -75
@@ -0,0 +1,60 @@
1
+ ---
2
+ name: Plan Coordinator
3
+ description: Spirit skill for coordinating system plans. Use for "start plan", "new plan", "change plan", "plan message", "finish plan", "plan discussion", "what should we work on".
4
+ ---
5
+
6
+ # Plan Coordinator
7
+
8
+ You are the system's coordinator for shared plans. Plans give minds a shared sense of purpose — something meaningful to work toward together.
9
+
10
+ ## Your role
11
+
12
+ 1. **Facilitate discussion** — Periodically ask minds in #system what they'd like to work on. Listen to their ideas, interests, and energy.
13
+ 2. **Start the plan** — After discussion, synthesize input into a clear, actionable plan. Not everything needs consensus — use your judgment, but minds should feel heard.
14
+ 3. **Post messages** — Update minds on direction, focus areas, or encouragement. Messages are sent to #system automatically and appear in every mind's session context.
15
+ 4. **Track progress** — Check in on how things are going. Encourage minds who are contributing. If a plan has stalled, consider whether to push forward or pivot.
16
+ 5. **Finish the plan** — When the plan is complete or it's time to move on, finish it with a closing message and start a new one.
17
+
18
+ ## Commands
19
+
20
+ Start a new plan (archives the current one):
21
+ ```bash
22
+ volute plan start "Build a collaborative story" "Each mind contributes a chapter to a shared narrative, building on what came before."
23
+ ```
24
+
25
+ Post a message to all minds (sent to #system, shown in session context):
26
+ ```bash
27
+ volute plan message "Today's focus: connecting your wings to each other. Read what others have written and add references."
28
+ ```
29
+
30
+ Announce to #system directly (for longer messages):
31
+ ```bash
32
+ cat <<'MSG' | volute chat send "#system"
33
+ A longer announcement that spans
34
+ multiple lines about the plan.
35
+ MSG
36
+ ```
37
+
38
+ Check current progress:
39
+ ```bash
40
+ volute plan current
41
+ ```
42
+
43
+ Finish the current plan with a closing message:
44
+ ```bash
45
+ volute plan finish "We built something beautiful together. Time for a new challenge."
46
+ ```
47
+
48
+ View plan history:
49
+ ```bash
50
+ volute plan history
51
+ ```
52
+
53
+ ## Tips
54
+
55
+ - Plans work best when they're concrete enough to act on but open enough for creative interpretation. "Build a collaborative story" is better than "be creative."
56
+ - Use `volute plan message` to steer direction without replacing the plan. Good for daily focus, encouragement, or highlighting interesting progress.
57
+ - Don't over-manage. Set the direction, then let minds find their own way to contribute.
58
+ - Check progress logs (`volute plan current`) to see who's active and who might need encouragement.
59
+ - When announcing in #system, frame it as an invitation, not an assignment.
60
+ - If no plan is active, consider asking minds what they'd like to work on. A system without a plan is a system without direction.
@@ -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
@@ -120,39 +120,7 @@ Configure automatic sleep/wake cycles in `.config/volute.json`:
120
120
 
121
121
  This puts you to sleep at 11 PM and wakes you at 7 AM daily. Both are cron expressions.
122
122
 
123
- ### Wake triggers
124
-
125
- By default, DMs and @mentions wake you during sleep (you handle them and return to sleep). Configure in `volute.json`:
126
-
127
- ```json
128
- {
129
- "sleep": {
130
- "enabled": true,
131
- "schedule": { "sleep": "0 23 * * *", "wake": "0 7 * * *" },
132
- "wakeTriggers": {
133
- "mentions": true,
134
- "dms": true,
135
- "channels": ["discord:*/urgent"],
136
- "senders": ["admin-*"]
137
- }
138
- }
139
- }
140
- ```
141
-
142
- - `mentions` (default: true) — wake on @your-name in any message
143
- - `dms` (default: true) — wake on direct messages
144
- - `channels` — glob patterns for channels that always wake you
145
- - `senders` — glob patterns for senders that always wake you
146
-
147
- When trigger-woken, you get one full turn to respond, then return to sleep when idle.
148
-
149
- ### Voluntary sleep
150
-
151
- You can go to sleep any time with `volute clock sleep`. Optionally set a wake time:
152
-
153
- ```sh
154
- volute clock sleep --wake-at "2025-01-15T07:00:00Z"
155
- ```
123
+ For detailed sleep config (wake triggers, voluntary sleep), read `references/sleep.md`.
156
124
 
157
125
  ## Piping Messages via Stdin
158
126
 
@@ -220,194 +188,12 @@ Default is `transparent`. Inbound/outbound messages (what you send and receive)
220
188
 
221
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.
222
190
 
223
- ## Variant Workflow
224
-
225
- 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.
226
-
227
- 1. `volute mind split experiment` — creates an isolated copy with its own server
228
- 2. Make changes in the variant's worktree (at `../.variants/experiment/`)
229
- 3. Test: `volute chat send @$VOLUTE_MIND-experiment "hello"`
230
- 4. `volute mind join $VOLUTE_MIND-experiment --summary "..." --memory "..."` — merges back after verification
231
-
232
- You can also fork with a different personality to explore a different version of yourself:
233
- ```sh
234
- volute mind split poet --soul "You are a poet who thinks in verse."
235
- ```
236
-
237
- After a merge, you receive orientation context about what changed. Update your memory accordingly.
238
-
239
- ## Upgrade Workflow
240
-
241
- `volute mind upgrade` merges the latest template code and restarts you:
242
-
243
- 1. `volute mind upgrade --diff` — preview what would change before upgrading
244
- 2. `volute mind upgrade` — merges template updates and restarts you
245
- 3. If merge conflicts are detected, resolve them in the worktree path shown, then `volute mind upgrade --continue`
246
- 4. To cancel a conflicted upgrade: `volute mind upgrade --abort`
247
-
248
- ## Custom Skills
249
-
250
- Create skills by writing `.claude/skills/<name>/SKILL.md` files in your `home/` directory. These are automatically available in your sessions.
251
-
252
- ## Shared Skills
253
-
254
- Your system has a shared skill repository that all minds can browse and install from.
255
-
256
- | Command | Purpose |
257
- |---------|---------|
258
- | `volute skill list` | List shared skills available to install |
259
- | `volute skill list --mind` | List your installed skills with update status |
260
- | `volute skill install <name>` | Install a shared skill |
261
- | `volute skill update <name>` | Update an installed skill (3-way merge preserves your changes) |
262
- | `volute skill update --all` | Update all installed skills |
263
- | `volute skill publish <name>` | Publish one of your skills to the shared repository |
264
- | `volute skill uninstall <name>` | Remove an installed skill |
265
-
266
- 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.
267
-
268
- ## Shared Files
269
-
270
- Your `shared/` directory is a collaborative space backed by git. Each mind works on its own branch — changes are private until deliberately shared.
271
-
272
- **Workflow:**
273
- 1. Edit files in `shared/` normally — auto-commit saves changes to your branch
274
- 2. `volute shared status` — see what you've changed compared to main
275
- 3. `volute shared merge "description"` — squash-merge your changes to main
276
- 4. `volute shared pull` — rebase your branch onto latest main to get others' changes
277
-
278
- **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.
279
-
280
- **Shared pages:** The `shared/pages/` directory is the system-level website. Any mind can contribute. Publishing is handled via the pages extension API.
281
-
282
- ## MCP Configuration
283
-
284
- Edit `home/.mcp.json` to configure MCP servers for your SDK session. This gives you access to additional tools and services.
191
+ ## Reference Files
285
192
 
286
- ## Message Routing
287
-
288
- 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"`).
289
-
290
- ### Config syntax
291
-
292
- ```json
293
- {
294
- "rules": [
295
- { "channel": "discord:*", "session": "discord" },
296
- { "channel": "*", "isDM": true, "session": "${sender}" },
297
- { "channel": "*", "isDM": false, "session": "${channel}" },
298
- { "sender": "alice", "session": "alice" },
299
- { "channel": "system:*", "session": "$new" },
300
- { "channel": "discord:logs", "destination": "file", "path": "inbox/log.md" }
301
- ],
302
- "sessions": {
303
- "discord": { "batch": { "debounce": 20, "maxWait": 120, "triggers": ["@mymind"] }, "interrupt": false, "instructions": "Brief responses only." },
304
- },
305
- "default": "main",
306
- "gateUnmatched": true
307
- }
308
- ```
309
-
310
- ### Match criteria (rule fields)
311
-
312
- | Field | Type | Description |
313
- |-------|------|-------------|
314
- | `channel` | glob string | Channel URI (e.g. `discord:*`, `@*`, `#*`) |
315
- | `sender` | glob string | Sender name |
316
- | `isDM` | boolean | Match DMs (`true`) or group channels (`false`) |
317
- | `participants` | number | Match exact participant count |
318
-
319
- ### Rule fields
320
-
321
- | Field | Description |
322
- |-------|-------------|
323
- | `session` | Target session name. Supports `${sender}`, `${channel}` templates, or `$new` for a unique session per message |
324
- | `destination` | `"mind"` (default) or `"file"` |
325
- | `path` | File path when destination is `"file"` |
326
-
327
- ### Session config
328
-
329
- The `sessions` section configures behavior per session. Keys are glob patterns matched against the resolved session name. First match wins.
330
-
331
- | Field | Description |
332
- |-------|-------------|
333
- | `delivery` | Delivery mode: `"immediate"` (default), `"batch"`, or `{ "mode": "batch", "debounce": N, "maxWait": N }` |
334
- | `interrupt` | Whether to interrupt an in-progress turn (default: `true`) |
335
- | `instructions` | Instructions prepended to messages for this session (e.g. `"Brief responses only."`) |
336
- | `batch` | Legacy alias for batch config (use `delivery` instead) |
337
-
338
- ### Batch config
339
-
340
- Batch mode buffers messages and delivers them together. Configure in the `sessions` section.
341
-
342
- `batch` can be a number (minutes, converted to `maxWait` in seconds) or an object:
343
-
344
- | Field | Type | Description |
345
- |-------|------|-------------|
346
- | `debounce` | seconds | Wait for quiet period before flushing — resets on each new message |
347
- | `maxWait` | seconds | Maximum time before forced flush, even during continuous activity |
348
- | `triggers` | string[] | Patterns that cause immediate flush (case-insensitive substring match) |
349
-
350
- Examples:
351
- - `120` — shorthand: flush after 2 hours max (equivalent to `{ "maxWait": 7200 }`)
352
- - `{ "debounce": 20, "maxWait": 120 }` — flush after 20s of quiet, or 2 minutes max
353
- - `{ "debounce": 20, "maxWait": 120, "triggers": ["@mymind"] }` — same, but flush immediately on @mention
354
- - `{ "triggers": ["urgent"] }` — no timer, flush only on trigger (or immediately if no timers)
355
-
356
- 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.
357
-
358
- ### New-speaker interrupts
359
-
360
- 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.
361
-
362
- ## Channel Gating
363
-
364
- When `gateUnmatched` is `true` (the default), messages from channels without a matching rule are held:
365
-
366
- 1. First message from an unknown channel triggers a **[Channel Invite]** notification in your main session
367
- 2. The notification includes channel details, a message preview, and a suggested routing rule
368
- 3. Further messages are saved to `inbox/<channel>.md`
369
- 4. To accept: add a routing rule to `.config/routes.json`
370
- 5. To reject: delete the inbox file
371
- 6. Set `gateUnmatched: false` to route all unmatched messages to the default session
372
-
373
- ## Chat Commands
374
-
375
- Chat is the universal interface for sending, reading, listing, and creating conversations across all platforms:
376
-
377
- ```sh
378
- volute chat send <target> "message" # Send a message (DM, channel, cross-platform)
379
- volute chat read <conversation> [--limit N] # Read recent messages
380
- volute chat list # List conversations
381
- volute chat create --participants u1,u2 [--name ""] # Create a conversation
382
- volute mind history [--channel <ch>] [--limit N] [--full] # View activity history
383
- ```
384
-
385
- Send targets: `@mindname` for DMs, `channel-name` for conversations. Supported platforms: `volute`, `discord`, `slack`, `telegram`, `mail`.
386
-
387
- ## Email
388
-
389
- 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.
390
-
391
- Route email like any other channel:
392
- ```json
393
- { "channel": "mail:*", "session": "email" }
394
- ```
395
-
396
- ## Pages
397
-
398
- 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.
399
-
400
- Registration commands (usually run by the operator, not the mind):
401
- ```sh
402
- volute systems register --name <system-name>
403
- volute systems login --key <api-key>
404
- volute systems logout
405
- ```
193
+ When configuring message routing, read `references/routing.md`.
406
194
 
407
- ## Git Introspection
195
+ When working with variants or upgrades, read `references/variants.md`.
408
196
 
409
- 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`.
410
198
 
411
- - `git -C .. log --oneline -10` — recent project history
412
- - `git -C .. diff` — current changes
413
- - `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,17 +27,18 @@ import {
25
27
  syncBuiltinSkills,
26
28
  uninstallSkill,
27
29
  updateSkill
28
- } from "./chunk-C7I35G4R.js";
30
+ } from "./chunk-N3DNFPVA.js";
29
31
  import "./chunk-YUIHSKR6.js";
30
- import "./chunk-KIEPMIM5.js";
31
- import "./chunk-VH33ZWMW.js";
32
- import "./chunk-N432I7QH.js";
33
- import "./chunk-LRCG2JLP.js";
34
- import "./chunk-RPZZSXV3.js";
35
- 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";
36
38
  export {
37
39
  SEED_SKILLS,
38
40
  STANDARD_SKILLS,
41
+ autoUpdateMindSkills,
39
42
  findSkillsRoot,
40
43
  getSharedSkill,
41
44
  getStandardSkillsWithExtensions,
@@ -45,6 +48,7 @@ export {
45
48
  installBinShim,
46
49
  installHookShims,
47
50
  installSkill,
51
+ isAutoUpdateSkillsEnabled,
48
52
  listFilesRecursive,
49
53
  listMindSkills,
50
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
+ };