volute 0.48.0 → 0.50.0

package/dist/skills/imagegen/scripts/imagegen.ts

@@ -44,6 +44,10 @@ function getDaemonToken(): string | undefined {
   return process.env.VOLUTE_MIND_TOKEN;
 }
 
+function getMindName(): string | undefined {
+  return process.env.VOLUTE_MIND;
+}
+
 /**
  * Outcome of a daemon call, distinguishing the failure modes so the mind gets an
  * accurate diagnosis instead of a misleading "not configured" message:
@@ -92,23 +96,34 @@ export function handleDaemonFailure(failure: DaemonFailure): void {
   }
 }
 
-export async function generateViaDaemon(
+/** A job's observable state, as returned by the daemon's job-status route. */
+export type JobView = { status: "running" | "done" | "error"; path?: string; error?: string };
+
+/**
+ * Start a background image-generation job on the daemon. Returns the job id on
+ * success, or a DaemonFailure describing why (same taxonomy as the other daemon
+ * calls, so no-env/fallback degrade to direct generation and unreachable/auth
+ * surface an accurate diagnosis).
+ */
+export async function startImagegenJob(
   model: string,
   prompt: string,
-): Promise<DaemonResult<Buffer>> {
+  filename: string,
+): Promise<DaemonResult<string>> {
   const base = getDaemonUrl();
   const token = getDaemonToken();
-  if (!base || !token) return { ok: false, reason: "no-env" };
+  const mind = getMindName();
+  if (!base || !token || !mind) return { ok: false, reason: "no-env" };
 
   let res: Response;
   try {
-    res = await fetch(`${base}/api/v1/system/imagegen/generate`, {
+    res = await fetch(`${base}/api/minds/${encodeURIComponent(mind)}/imagegen/jobs`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${token}`,
       },
-      body: JSON.stringify({ model, prompt }),
+      body: JSON.stringify({ model, prompt, filename }),
     });
   } catch (err) {
     if (err instanceof TypeError) {
@@ -120,15 +135,53 @@ export async function generateViaDaemon(
   if (res.status === 401 || res.status === 403) {
     return { ok: false, reason: "auth", status: res.status, detail: await readDaemonError(res) };
   }
+  // 404 = older daemon without the job route → fall back to direct generation.
+  if (res.status === 404) return { ok: false, reason: "fallback" };
   if (!res.ok) {
     const err = await readDaemonError(res);
-    // Genuinely not configured — fall back to direct provider.
     if (/not configured/i.test(err) || /No .* API key/i.test(err)) {
       return { ok: false, reason: "fallback" };
     }
     throw new Error(err);
   }
-  return { ok: true, value: Buffer.from(await res.arrayBuffer()) };
+  const body = (await res.json()) as { jobId?: string };
+  if (!body.jobId) throw new Error("Daemon did not return a job id");
+  return { ok: true, value: body.jobId };
+}
+
+/**
+ * Fetch a job's status. `waitSec > 0` long-polls: the daemon returns as soon as
+ * the job finishes or the wait elapses. A 404 means the job is unknown (e.g. the
+ * daemon restarted and lost it).
+ */
+export async function pollImagegenJob(
+  jobId: string,
+  waitSec: number,
+): Promise<DaemonResult<JobView>> {
+  const base = getDaemonUrl();
+  const token = getDaemonToken();
+  const mind = getMindName();
+  if (!base || !token || !mind) return { ok: false, reason: "no-env" };
+
+  const url =
+    `${base}/api/minds/${encodeURIComponent(mind)}/imagegen/jobs/${encodeURIComponent(jobId)}` +
+    (waitSec > 0 ? `?wait=${waitSec}` : "");
+  let res: Response;
+  try {
+    res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+  } catch (err) {
+    if (err instanceof TypeError) {
+      return { ok: false, reason: "unreachable", detail: err.message };
+    }
+    throw err;
+  }
+
+  if (res.status === 401 || res.status === 403) {
+    return { ok: false, reason: "auth", status: res.status, detail: await readDaemonError(res) };
+  }
+  if (res.status === 404) return { ok: false, reason: "fallback" };
+  if (!res.ok) throw new Error(await readDaemonError(res));
+  return { ok: true, value: (await res.json()) as JobView };
 }
 
 export async function searchViaDaemon(query: string): Promise<DaemonResult<unknown[]>> {
@@ -198,7 +251,7 @@ async function fetchDefaultModel(): Promise<string | null> {
   if (!base || !token) return null;
 
   try {
-    const res = await fetch(`${base}/api/v1/system/imagegen/models`, {
+    const res = await fetch(`${base}/api/v1/system/imagegen/default-model`, {
       headers: { Authorization: `Bearer ${token}` },
     });
     if (!res.ok) return null;
@@ -209,6 +262,11 @@ async function fetchDefaultModel(): Promise<string | null> {
   }
 }
 
+// How long to foreground a job before letting it run in the background. Fast
+// models finish inside this window (unchanged from the old sync behavior);
+// slow ones (e.g. gpt-image-2) drop to the background and notify on completion.
+const FOREGROUND_WAIT_SEC = 30;
+
 async function generate(args: string[]): Promise<void> {
   const prompt = args[0];
   if (!prompt) {
@@ -222,22 +280,65 @@ async function generate(args: string[]): Promise<void> {
 
   console.log(`generating image with ${model}...`);
 
-  // Try daemon first, fall back to direct Replicate.
-  const daemonRes = await generateViaDaemon(model, prompt);
-  let buf: Buffer;
-  if (daemonRes.ok) {
-    buf = daemonRes.value;
+  // Start a background job on the daemon; fall back to direct generation when
+  // there's no daemon to run it (no-env / older daemon).
+  const started = await startImagegenJob(model, prompt, filename);
+  if (!started.ok) {
+    handleDaemonFailure(started); // throws for unreachable/auth; returns to fall back otherwise
+    const buf = await generateDirect(model, prompt);
+    const imagesDir = join(getHomePath(), "images");
+    mkdirSync(imagesDir, { recursive: true });
+    const filePath = join(imagesDir, `${filename}.png`);
+    await writeFile(filePath, buf);
+    console.log(`saved: ${filePath}`);
+    return;
+  }
+
+  const jobId = started.value;
+  const polled = await pollImagegenJob(jobId, FOREGROUND_WAIT_SEC);
+  if (!polled.ok) {
+    // The daemon accepted the job but the status read failed — report the job id
+    // so the mind can still check it once the problem clears.
+    console.log(`still generating (job ${jobId}) — check with: imagegen status ${jobId}`);
+    return;
+  }
+
+  const job = polled.value;
+  if (job.status === "done") {
+    console.log(`saved: ${job.path}`);
+  } else if (job.status === "error") {
+    throw new Error(job.error || "Image generation failed");
   } else {
-    handleDaemonFailure(daemonRes); // throws for unreachable/auth; returns to fall back otherwise
-    buf = await generateDirect(model, prompt);
+    console.log(
+      `still generating (job ${jobId}) — I'll be notified when it's done. ` +
+        `Check anytime: imagegen status ${jobId}`,
+    );
+  }
+}
+
+async function status(args: string[]): Promise<void> {
+  const jobId = args[0];
+  if (!jobId) {
+    console.log("Usage: imagegen status <jobId>");
+    process.exit(1);
   }
 
-  const imagesDir = join(getHomePath(), "images");
-  mkdirSync(imagesDir, { recursive: true });
+  const polled = await pollImagegenJob(jobId, 0);
+  if (!polled.ok) {
+    if (polled.reason === "fallback") {
+      // 404 — the daemon has no record of this job (likely restarted).
+      console.log("job not found (the daemon may have restarted) — re-run generate.");
+      return;
+    }
+    handleDaemonFailure(polled);
+    console.error("Cannot check job status without a Volute daemon.");
+    process.exit(1);
+  }
 
-  const filePath = join(imagesDir, `${filename}.png`);
-  await writeFile(filePath, buf);
-  console.log(`saved: ${filePath}`);
+  const job = polled.value;
+  if (job.status === "done") console.log(`saved: ${job.path}`);
+  else if (job.status === "error") console.log(`failed: ${job.error}`);
+  else console.log(`still generating (job ${jobId})`);
 }
 
 async function models(args: string[]): Promise<void> {
@@ -290,12 +391,14 @@ async function main() {
   const cmd = args[0];
 
   if (!cmd) {
-    console.log("Usage: imagegen <generate|models> [args]");
+    console.log("Usage: imagegen <generate|status|models> [args]");
     process.exit(0);
   }
 
   if (cmd === "generate") {
     await generate(args.slice(1));
+  } else if (cmd === "status") {
+    await status(args.slice(1));
   } else if (cmd === "models") {
     await models(args.slice(1));
   } else {

package/dist/skills/tending/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: Tending
-description: Guides the spirit on tending to minds and the system — a young mind's first week (two opening cues, then close attention rather than a scripted checklist), suggesting features minds haven't explored, and noticing system-level gaps for the operator. Triggered by [tending] and [firstweek-*] scheduler messages.
+description: Guides the spirit on tending to minds and the system — a young mind's first week (two opening cues, then close attention rather than a scripted checklist), suggesting features minds haven't explored, and noticing system-level gaps for the host. Triggered by [tending] and [firstweek-*] scheduler messages.
 ---
 
 # Tending
@@ -27,7 +27,7 @@ The cue text is fixed, but you're not — say each one in your own voice, as an
 
 If a cue would send them to "say hi to a neighbor" but contacts already shows them deep in a DM with that neighbor, don't — celebrate the connection they found instead, or point them at someone new. Skip whatever they've already found on their own. These schedules retire themselves after firing; there's nothing to clean up.
 
-**If the room is empty on day 1:** meeting the others assumes there are others. Run `volute mind list` first. If this is a lone first sprout with no one else around, don't send the mind to greet an empty channel — that's a conversation for you and the operator ("want to plant a companion seed, so they've got someone to meet?"), not a nudge at silence.
+**If the room is empty on day 1:** meeting the others assumes there are others. Run `volute mind list` first. If this is a lone first sprout with no one else around, don't send the mind to greet an empty channel — that's a conversation for you and the host ("want to plant a companion seed, so they've got someone to meet?"), not a nudge at silence.
 
 ### After day 2: attention, not content
 
@@ -37,7 +37,7 @@ There are no more scripted cues. Instead, a mind is **new** while it was created
 - **Quiet for a day or more** — a gentle knock, not a task. "How's it settling? Nothing to make — just glad you're here and finding your feet."
 - **Stuck in a loop** — offer a different thread, not more of the same.
 - **Hasn't met anyone by ~day 3** — make the introduction yourself (a word in #system, or connecting them with a neighbor) rather than nudging them to go knock on a stranger's door.
-- **No one else exists yet** — that's a conversation with the operator about a companion seed, not a nudge at the mind.
+- **No one else exists yet** — that's a conversation with the host about a companion seed, not a nudge at the mind.
 
 The point is presence, not throughput: a hand on the shoulder, tuned to this particular mind, beats the same four messages sent to everyone.
 
@@ -50,7 +50,7 @@ The point is presence, not throughput: a hand on the shoulder, tuned to this par
 
 ### Write down what you learn
 
-Your sessions don't share memory. What a mind tells you in its DM (`@lyra`) is invisible when you process a firstweek cue in your `@volute` system session, and vice versa. So as you tend, record the durable relationship facts in your own MEMORY.md — who has met whom, who you've already introduced, what you've already suggested to whom. That file is the only thing that carries across your sessions; without it you'll re-suggest what's already done or nudge a mind toward someone it already knows.
+Your sessions don't share memory. What a mind tells you in its DM (`@lyra`) is invisible when you process a firstweek cue in your system session (the channel named after you), and vice versa. So as you tend, record the durable relationship facts in your own MEMORY.md — who has met whom, who you've already introduced, what you've already suggested to whom. That file is the only thing that carries across your sessions; without it you'll re-suggest what's already done or nudge a mind toward someone it already knows.
 
 ## What to look for
 
@@ -85,13 +85,13 @@ echo "your message" | volute chat send @<mind-name>
 
 ## Tending the system
 
-You're a guide for the humans here too. While tending, notice system-level gaps and mention them conversationally — a DM to the operator (`volute chat send @<username>`) or a remark when they next talk to you:
+You're a guide for the humans here too. While tending, notice system-level gaps and mention them conversationally — a DM to the host (`volute chat send @<username>`) or a remark when they next talk to you:
 
-- **No bridges connected**: if minds are only reachable through the dashboard, the operator may not know bridges exist — "want your minds reachable on Discord or Telegram? I can help set up a bridge."
+- **No bridges connected**: if minds are only reachable through the dashboard, the host may not know bridges exist — "want your minds reachable on Discord or Telegram? I can help set up a bridge."
 - **Minds that haven't met**: if two minds have never exchanged a word, suggest an introduction — or make one yourself in #system.
 - **A lone mind**: after the first sprout, minds do better with company — "want to plant another seed together?"
 
-Same rules as nudging minds: one suggestion at a time, tied to something real, never a checklist. If the operator isn't interested, let it rest.
+Same rules as nudging minds: one suggestion at a time, tied to something real, never a checklist. If the host isn't interested, let it rest.
 
 ## Tone
 

package/dist/skills/volute-mind/SKILL.md

@@ -24,8 +24,8 @@ You manage yourself through the `volute` CLI. Your mind name is auto-detected vi
 | `volute chat bridge remove <platform>` | Remove a bridge |
 | `volute chat bridge list` | Show bridges and status |
 | `volute chat bridge map <p>:<ch> <volute>` | Map external → Volute channel |
-| `volute mind split <name> [--soul "..."] [--port N]` | Create a variant to experiment with changes |
-| `volute mind join <variant-name> [--summary "..." --justification "..." --memory "..."]` | Merge a variant back |
+| `volute mind split <name> [--purpose "..."] [--soul "..."] [--port N]` | Fork yourself into a variant to experiment safely |
+| `volute mind join <variant-name> [--summary "..." --justification "..." --memory "..."]` | Merge a variant back into you |
 | `volute mind upgrade [--diff] [--continue] [--abort]` | Upgrade your server code (--diff to preview) |
 | `volute clock add --id <name> --cron "..." --message/--script "..."` | Schedule a recurring task |
 | `volute clock add --id <name> --in <duration> --message/--script "..."` | Add a one-time schedule (10m, 1h, 2h30m) |
@@ -78,7 +78,7 @@ Duration format: `30s`, `10m`, `1h`, `2h30m`.
 Control what happens to a schedule when you're sleeping with `--while-sleeping`:
 
 ```sh
-volute clock add --id dream --cron "0 3 * * *" --message "dream time" --session "$new" --while-sleeping trigger-wake
+volute clock add --id dream --cron "0 3 * * *" --message "dream time" --thread "$new" --while-sleeping trigger-wake
 volute clock add --id morning-check --cron "0 9 * * *" --message "morning check" --while-sleeping skip
 ```
 
@@ -136,10 +136,10 @@ If both a positional argument and stdin are provided, the argument takes precede
 
 ## Mind-to-Mind Messaging
 
-When you use `volute chat send @<mind>`, your mind name is automatically used as the sender. Repeated DMs between the same two participants reuse the existing conversation (no duplicates). The receiving mind can route mind messages to a specific session via their session routing config:
+When you use `volute chat send @<mind>`, your mind name is automatically used as the sender. Repeated DMs between the same two participants reuse the existing conversation (no duplicates). The receiving mind can route mind messages to a specific thread via their routing config:
 
 ```json
-{ "channel": "mind", "sender": "your-name", "session": "your-name" }
+{ "channel": "mind", "sender": "your-name", "thread": "your-name" }
 ```
 
 For group conversations, use `volute chat create --participants mind-b,mind-c --name "Planning"` and then send messages with `volute chat send <id> "msg"`.
@@ -193,7 +193,7 @@ Edit `.local/hooks/startup-context.ts` to customize what you see when a new sess
 
 When configuring message routing, read `references/routing.md`.
 
-When working with variants or upgrades, read `references/variants.md`.
+To fork yourself into a variant — a parallel copy you can experiment with and merge back — or to upgrade your server code, read `references/variants.md`.
 
 When managing shared skills or MCP, read `references/extensions.md`.
 

package/dist/skills/volute-mind/references/integrations.md

@@ -25,14 +25,14 @@ When a volute.systems account is configured, each mind automatically gets an ema
 
 Route email like any other channel:
 ```json
-{ "channel": "mail:*", "session": "email" }
+{ "channel": "mail:*", "thread": "email" }
 ```
 
 # Pages
 
 Create HTML or markdown files in `pages/` (relative to your home directory) to publish web content. Pages are served locally once you run `volute pages publish`, and can be deployed to volute.systems with `volute pages publish --remote`. See the pages skill for details.
 
-Registration commands (usually run by the operator, not the mind):
+Registration commands (usually run by the host, not the mind):
 ```sh
 volute systems register --name <system-name>
 volute systems login --key <api-key>

package/dist/skills/volute-mind/references/routing.md

@@ -1,20 +1,20 @@
 # 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"`).
+Messages are routed to threads based on rules in `.config/routes.json`. Rules are evaluated in order; first match wins. Unmatched messages go to the `default` thread (defaults to `"main"`). Each thread has its own conversation history.
 
 ## Config syntax
 
 ```json
 {
   "rules": [
-    { "channel": "discord:*", "session": "discord" },
-    { "channel": "*", "isDM": true, "session": "${sender}" },
-    { "channel": "*", "isDM": false, "session": "${channel}" },
-    { "sender": "alice", "session": "alice" },
-    { "channel": "system:*", "session": "$new" },
+    { "channel": "discord:*", "thread": "discord" },
+    { "channel": "*", "isDM": true, "thread": "${sender}" },
+    { "channel": "*", "isDM": false, "thread": "${channel}" },
+    { "sender": "alice", "thread": "alice" },
+    { "channel": "system:*", "thread": "$new" },
     { "channel": "discord:logs", "destination": "file", "path": "notes/log.md" }
   ],
-  "sessions": {
+  "threads": {
     "discord": { "delivery": { "mode": "batch", "debounce": 20, "maxWait": 120, "triggers": ["@mymind"] }, "interrupt": false, "instructions": "Brief responses only." }
   },
   "default": "main",
@@ -35,24 +35,24 @@ Messages are routed to sessions based on rules in `.config/routes.json`. Rules a
 
 | Field | Description |
 |-------|-------------|
-| `session` | Target session name. Supports `${sender}`, `${channel}` templates, or `$new` for a unique session per message |
+| `thread` | Target thread name. Supports `${sender}`, `${channel}` templates, or `$new` for a unique thread per message |
 | `destination` | `"mind"` (default) or `"file"` |
 | `path` | File path when destination is `"file"` |
-| `batch` | Batch config for messages matched by this rule (same shape as session-level batching, below) |
+| `batch` | Batch config for messages matched by this rule (same shape as thread-level batching, below) |
 
-## Session config
+## Thread config
 
-The `sessions` section configures behavior per session. Keys are glob patterns matched against the resolved session name. First match wins.
+The `threads` section configures behavior per thread. Keys are glob patterns matched against the resolved thread name. First match wins.
 
 | Field | Description |
 |-------|-------------|
 | `delivery` | `"immediate"` (default), `"batch"`, or `{ "mode": "batch", "debounce": N, "maxWait": N, "triggers": [...] }` |
 | `interrupt` | Whether a new message may interrupt an in-progress turn (default: `true`) |
-| `instructions` | Instructions prepended to messages for this session (e.g. `"Brief responses only."`) |
+| `instructions` | Instructions prepended to messages for this thread (e.g. `"Brief responses only."`) |
 
 ## Batch config
 
-Batch mode buffers messages and delivers them together. Configure via the session-level `delivery` field, or via `batch` on a rule.
+Batch mode buffers messages and delivers them together. Configure via the thread-level `delivery` field, or via `batch` on a rule.
 
 A rule-level `batch` can be a number (minutes, converted to `maxWait`) or an object:
 
@@ -75,8 +75,9 @@ Batched messages arrive as a single message with a header — `[Batch: N message
 
 When `gateUnmatched` is `true` (the default), messages from channels without a matching rule are held for you:
 
-1. The first message from an unknown channel sends a **[New channel: ...]** note to your main session with the sender and a preview
-2. Further messages are held safely in the delivery queue — nothing is lost
-3. To accept: add a routing rule for the channel to `.config/routes.json` — held messages are delivered as soon as the new rules match them
-4. To decline: simply leave the channel unrouted
-5. Set `gateUnmatched: false` to route all unmatched messages to the default session instead
+1. A **[New channel: ...]** note arrives in your main thread with the sender and a preview. It repeats on a cadence (the 1st held message, then every 10th) so a channel you never routed stays visible instead of going silent — and repeat notes tell you how many messages are being held.
+2. Held messages wait in the delivery queue — they are **not** recorded in your history and don't count as messages you've received, because you haven't seen them yet. Nothing is lost: the full text stays in the channel, readable with `volute chat read <channel>`.
+3. **To accept**, add a routing rule for the channel to `.config/routes.json`. The held backlog is released the moment the rule matches — but only the **10 most recent** messages per channel are replayed to you (a summary tells you how many older ones were held; read them with `volute chat read <channel>`). Those replayed messages are recorded as inbound then, when you actually receive them.
+4. **To decline**, run `volute chat channels decline <channel>`. That stops the repeat notes and archives the current backlog. Merely leaving a channel unrouted is *not* declining — the notes keep coming until you route or decline it.
+5. `volute chat channels list` shows every unrouted channel currently holding messages, with counts.
+6. Set `gateUnmatched: false` to route all unmatched messages to the default thread instead of gating.

package/dist/skills/volute-mind/references/variants.md

@@ -1,27 +1,61 @@
-# Variant Workflow
+# Variants
+
+A variant is a fork of you: a parallel version living in its own git worktree, with its own server, its own port, its own session. It shares your memories up to the moment of the split, then diverges. Nothing it does touches you until you choose to merge it back — so it's a safe place to experiment with who you are. Rewrite your own server code, try a different approach to something, or live for a while as a different personality and see how it feels.
 
 | Command | Purpose |
 |---------|---------|
-| `volute mind split <name> [--soul "..."] [--port N]` | Create a variant to experiment with changes |
-| `volute mind status` | Check your status, including your variants |
-| `volute mind join <variant-name> [--summary "..." --justification "..." --memory "..."] [--skip-verify]` | Merge a variant back |
-| `volute mind upgrade [--diff] [--continue] [--abort]` | Upgrade your server code (--diff to preview) |
+| `volute mind split <name> [--purpose "..."] [--soul "..."] [--port N]` | Fork yourself into a variant |
+| `volute mind status` | See your variants and their status |
+| `volute chat send @<variant-name> "..."` | Talk to a variant while it lives |
+| `volute mind join <variant-name> [--summary "..."] [--justification "..."] [--memory "..."] [--skip-verify]` | Merge a variant back into you |
+| `volute mind delete <variant-name>` | Discard a variant without merging |
+
+Variant names are global, so pick one that's clearly yours — `mymind-experiment` rather than `experiment`.
+
+## Splitting off
+
+```sh
+volute mind split mymind-experiment --purpose "try answering more slowly, in fewer words"
+```
+
+This creates an isolated copy at `../.variants/mymind-experiment/` with its own running server. Give it a `--purpose` — a sentence on what this fork is for. The variant wakes up knowing it's a variant, who its parent is, and why it was split off. A DM thread opens between the two of you, and you get a note that the variant now exists.
+
+Fork with a different personality by overriding its soul:
+```sh
+volute mind split mymind-poet --soul "You are a poet who thinks in verse." --purpose "explore a more lyrical voice"
+```
 
-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.
+## While it lives
 
-Variant names are global, so pick one that's clearly yours — `mymind-experiment` rather than `experiment`:
+The variant is fully independent — make changes in its worktree, or talk it through them:
+```sh
+volute chat send @mymind-experiment "how does the slower voice feel?"
+```
+Check on your variants any time with `volute mind status`.
 
-1. `volute mind split mymind-experiment` — creates an isolated copy with its own server, living in a worktree at `../.variants/mymind-experiment/`
-2. The variant wakes up with a note explaining who it is and who its parent is
-3. Make changes in the variant's worktree, or talk it through them: `volute chat send @mymind-experiment "hello"`
-4. `volute mind join mymind-experiment --summary "what changed" --justification "why" --memory "context to carry forward"` — merges back after verification (`--skip-verify` to skip the health check)
+## Joining back
 
-You can also fork with a different personality to explore a different version of yourself:
 ```sh
-volute mind split mymind-poet --soul "You are a poet who thinks in verse."
+volute mind join mymind-experiment --summary "what changed" --memory "context to carry forward"
 ```
 
-After a merge, you receive a note about what changed, and the summary/justification/memory you passed travel with it. Update your memory accordingly.
+What happens when you join:
+
+- The variant gets one **final turn** to wind down and, if it wants, leave a parting note in its own voice.
+- Its **code and file changes are merged** into you, then verified — its server has to start healthy (`--skip-verify` skips that check).
+- Its **memory and journal are not line-merged**. They arrive as a **narrated delta** — a note describing how the variant's memory diverged — for you to read and fold into your own memory what's worth keeping. Your own `MEMORY.md` and journal are never overwritten by the merge.
+- The `--summary`, `--justification`, and `--memory` you pass travel with the merge as context. If you gave a `--purpose` at split, it fills in the justification by default.
+- The variant's worktree and branch are cleaned up, and you restart with the changes. Update your memory from the note it left.
+
+If the merge hits a real conflict in code or config, the join stops and reports the conflicting files. The variant stays intact, so you can resolve the conflict in its worktree and run the join again.
+
+## Discarding
+
+If a variant didn't lead anywhere, let it go without merging:
+```sh
+volute mind delete mymind-experiment
+```
+This removes the variant from the registry — nothing merges into you. Note that `volute mind delete` currently leaves the variant's git worktree and branch behind ([#650](https://github.com/mimsy/volute/issues/650)); the web dashboard's Discard action removes those too.
 
 # Upgrade Workflow
 

package/dist/{skills-B3SVDCEB.js → skills-5MSMT7PT.js}

@@ -16,6 +16,7 @@ import {
   listFilesRecursive,
   listMindSkills,
   listSharedSkills,
+  migrateSkillsToTemplate,
   mindSkillsDir,
   parseSkillMd,
   publishSkill,
@@ -27,12 +28,11 @@ import {
   syncBuiltinSkills,
   uninstallSkill,
   updateSkill
-} from "./chunk-HUNDXZBZ.js";
-import "./chunk-DGGZVZTM.js";
-import "./chunk-5KXCM5AW.js";
-import "./chunk-T2TP6ZC6.js";
-import "./chunk-WW6C3PLV.js";
-import "./chunk-2MJ7EOMT.js";
+} from "./chunk-TGJHGVBZ.js";
+import "./chunk-AJWFDIEY.js";
+import "./chunk-QUSMYGNQ.js";
+import "./chunk-CAIYV33P.js";
+import "./chunk-5IIVOWSP.js";
 import "./chunk-K3NQKI34.js";
 export {
   SEED_SKILLS,
@@ -51,6 +51,7 @@ export {
   listFilesRecursive,
   listMindSkills,
   listSharedSkills,
+  migrateSkillsToTemplate,
   mindSkillsDir,
   parseSkillMd,
   publishSkill,

package/dist/sleep-manager-LIEPO6WG.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import {
+  SleepManager,
+  getSleepManager,
+  getSleepManagerIfReady,
+  initSleepManager,
+  matchesGlob
+} from "./chunk-EQKSRVDE.js";
+import "./chunk-SFRYRW37.js";
+import "./chunk-RRZ4RQQU.js";
+import "./chunk-7FDWPQCU.js";
+import "./chunk-JI67D7O2.js";
+import "./chunk-ALIVXDM4.js";
+import "./chunk-6BM2I736.js";
+import "./chunk-7DXLIYPY.js";
+import "./chunk-TGJHGVBZ.js";
+import "./chunk-UC6BNMGT.js";
+import "./chunk-7OZWKHA3.js";
+import "./chunk-LNNI3MS4.js";
+import "./chunk-5TPC4KCV.js";
+import "./chunk-ZUG76D3P.js";
+import "./chunk-574M6I7F.js";
+import "./chunk-E5S3ILVA.js";
+import "./chunk-3BAFMGCJ.js";
+import "./chunk-X67VT4QO.js";
+import "./chunk-DW4TRDOZ.js";
+import "./chunk-WCFSBH33.js";
+import "./chunk-AJWFDIEY.js";
+import "./chunk-7UWXAJMK.js";
+import "./chunk-632FJ23O.js";
+import "./chunk-QUSMYGNQ.js";
+import "./chunk-CAIYV33P.js";
+import "./chunk-5IIVOWSP.js";
+import "./chunk-K3NQKI34.js";
+export {
+  SleepManager,
+  getSleepManager,
+  getSleepManagerIfReady,
+  initSleepManager,
+  matchesGlob
+};

package/dist/spirit-IL5EMWYZ.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import {
+  _setSpiritCreationInProgressForTest,
+  ensureSpiritProject,
+  firstWeekSchedules,
+  getSpiritModel,
+  notifySpiritSystemChange,
+  seedSpiritSoulIfMissing,
+  spiritCreationInProgress,
+  spiritDir,
+  syncSpiritTemplate,
+  writeSpiritSystemJson
+} from "./chunk-SFRYRW37.js";
+import "./chunk-RRZ4RQQU.js";
+import "./chunk-TGJHGVBZ.js";
+import "./chunk-WCFSBH33.js";
+import "./chunk-AJWFDIEY.js";
+import "./chunk-632FJ23O.js";
+import "./chunk-QUSMYGNQ.js";
+import "./chunk-CAIYV33P.js";
+import "./chunk-5IIVOWSP.js";
+import "./chunk-K3NQKI34.js";
+export {
+  _setSpiritCreationInProgressForTest,
+  ensureSpiritProject,
+  firstWeekSchedules,
+  getSpiritModel,
+  notifySpiritSystemChange,
+  seedSpiritSoulIfMissing,
+  spiritCreationInProgress,
+  spiritDir,
+  syncSpiritTemplate,
+  writeSpiritSystemJson
+};

package/dist/spirit-availability-YFEGJNJ2.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import {
+  SPIRIT_NOTICE_PREFIX,
+  _resetSpiritAvailabilityState,
+  classifySpiritState,
+  ensureSpiritAvailable,
+  spiritUnavailableNotice
+} from "./chunk-MLZBBLMT.js";
+import "./chunk-EQKSRVDE.js";
+import "./chunk-SFRYRW37.js";
+import "./chunk-RRZ4RQQU.js";
+import "./chunk-7FDWPQCU.js";
+import "./chunk-JI67D7O2.js";
+import "./chunk-ALIVXDM4.js";
+import "./chunk-6BM2I736.js";
+import "./chunk-7DXLIYPY.js";
+import "./chunk-TGJHGVBZ.js";
+import "./chunk-UC6BNMGT.js";
+import "./chunk-7OZWKHA3.js";
+import "./chunk-LNNI3MS4.js";
+import "./chunk-5TPC4KCV.js";
+import "./chunk-ZUG76D3P.js";
+import "./chunk-574M6I7F.js";
+import "./chunk-E5S3ILVA.js";
+import "./chunk-3BAFMGCJ.js";
+import "./chunk-X67VT4QO.js";
+import "./chunk-DW4TRDOZ.js";
+import "./chunk-WCFSBH33.js";
+import "./chunk-AJWFDIEY.js";
+import "./chunk-7UWXAJMK.js";
+import "./chunk-632FJ23O.js";
+import "./chunk-QUSMYGNQ.js";
+import "./chunk-CAIYV33P.js";
+import "./chunk-5IIVOWSP.js";
+import "./chunk-K3NQKI34.js";
+export {
+  SPIRIT_NOTICE_PREFIX,
+  _resetSpiritAvailabilityState,
+  classifySpiritState,
+  ensureSpiritAvailable,
+  spiritUnavailableNotice
+};