From ab059f08197472dee6cf2ca6029ffa7d243294b8 Mon Sep 17 00:00:00 2001
From: Patrick Roza <contact@patrickroza.com>
Date: Sun, 5 Jul 2026 07:51:37 +0200
Subject: [PATCH 1/2] document mutation command atom guidance

Co-authored-by: Patrick Roza <42661+patroza@users.noreply.github.com>
---
 packages/vue/docs/mutation-command-atoms.md | 40 +++++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 packages/vue/docs/mutation-command-atoms.md

diff --git a/packages/vue/docs/mutation-command-atoms.md b/packages/vue/docs/mutation-command-atoms.md
new file mode 100644
index 000000000..3bbaf71b2
--- /dev/null
+++ b/packages/vue/docs/mutation-command-atoms.md
@@ -0,0 +1,40 @@
+# Mutation and command atoms
+
+Keep query and cache state atom-native. Keep ordinary mutations Effect-based and wrap them in `Command` when they need UI state. Use an atom-backed mutation only when its state is itself shared application state.
+
+## Why
+
+Query state is durable, keyed by handler and input, shared across components, and refreshed by invalidation. Command state usually belongs to one invocation: `waiting`, `blocked`, progress, errors, toasts, and follow-up Effects.
+
+`makeMutation` already records invalidation keys and data-dependency writes, then awaits affected atom queries. A mutation does not need to be an atom for cache coherence.
+
+`Command.fn` and mutation `.wrap()` add action identity, local reactive state, error handling, confirmation, toasts, and stream progress around an Effect.
+
+## Prefer `Command`
+
+Use the existing Effect-based mutation path when:
+
+- The mutation returns `void` or a small value.
+- Its shared effect is query invalidation.
+- Only the initiating surface needs `waiting`, `blocked`, progress, or errors.
+- The result is immediately composed with validation, navigation, emitted events, or other Effects.
+- Nothing must observe the invocation after that surface unmounts.
+
+## Prefer an atom
+
+Use atom-backed mutation state when:
+
+- Distant components observe the same invocation.
+- State is keyed per entity and instances must be tracked independently.
+- Other atoms derive from the mutation state.
+- Long-running progress must survive component remounts.
+- Optimistic state belongs in the same graph as the canonical entity state.
+
+Effect provides `Atom.fn`, `AtomRuntime.fn`, and mutation helpers in `AtomRpc` and `AtomHttpApi`. These expose one `AsyncResult` state cell. Before using one as an application command, define its keying, lifetime, reset behavior, concurrency, and how individual callers receive results.
+
+## Recommended split
+
+1. Queries, entities, caches, and live projections: atoms.
+2. Cache invalidation: the existing atom-query invalidation path.
+3. Ordinary user actions: Effect-based mutations wrapped with `Command` as needed.
+4. Shared, keyed, or long-lived action state: an atom-backed command abstraction with explicit concurrency semantics.

From 650077c406d40822f0a9be67c15113d7bf223ce2 Mon Sep 17 00:00:00 2001
From: "omegent-app[bot]" <306514130+omegent-app[bot]@users.noreply.github.com>
Date: Wed, 2 Sep 2026 11:04:50 +0000
Subject: [PATCH 2/2] ci: pin Node 24

Node latest advanced to 26, where the cluster SQLite workflow tests never start. Match the Node 24 version used by the development shell and release workflow.

Co-authored-by: Patrick Roza <42661+patroza@users.noreply.github.com>
---
 .github/workflows/ci.yml               | 6 +++---
 .github/workflows/publish-snapshot.yml | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c5e12f117..6161e56f7 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -36,7 +36,7 @@ jobs:
       - name: Install Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: latest
+          node-version: 24
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -79,7 +79,7 @@ jobs:
       - name: Install Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: latest
+          node-version: 24
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -130,7 +130,7 @@ jobs:
       - name: Install Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: latest
+          node-version: 24
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
diff --git a/.github/workflows/publish-snapshot.yml b/.github/workflows/publish-snapshot.yml
index 2f81c5bb3..33852f531 100644
--- a/.github/workflows/publish-snapshot.yml
+++ b/.github/workflows/publish-snapshot.yml
@@ -22,7 +22,7 @@ jobs:
       - name: Install Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: latest
+          node-version: 24
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4