@eventmodelers/cli 1.0.45 → 1.0.47

package/README.md

@@ -19,6 +19,9 @@ npx @eventmodelers/cli init --stack node            # Node.js / TypeScript
 npx @eventmodelers/cli init --stack supabase         # Supabase
 npx @eventmodelers/cli init --stack axon             # Axon Framework (Java/Kotlin)
 npx @eventmodelers/cli init --stack cratis-csharp    # Cratis (.NET/C#)
+npx @eventmodelers/cli init --stack opencqrs         # OpenCQRS (Java, EventSourcingDB)
+npx @eventmodelers/cli init --stack umadb            # UmaDB (Java)
+npx @eventmodelers/cli init --stack kurrent          # Kurrent (Java, KurrentDB)
 ```
 
 The installer prompts for your API token, Organization ID, and Board ID from [app.eventmodelers.ai/account](https://app.eventmodelers.ai/account), scaffolds the stack into your project, and writes `.eventmodelers/config.json` with your credentials.
@@ -73,7 +76,7 @@ your-project/
 └── CLAUDE.md                      ← agent instructions
 ```
 
-The four backend stacks (`node`, `supabase`, `axon`, `cratis-csharp`) also scaffold a real project skeleton into your project root (`templates/root/`) — source layout, build files, migrations, etc.
+The seven backend stacks (`node`, `supabase`, `axon`, `cratis-csharp`, `opencqrs`, `umadb`, `kurrent`) also scaffold a real project skeleton into your project root (`templates/root/`) — source layout, build files, migrations, etc.
 
 ## Skills
 
@@ -94,7 +97,7 @@ Use skills in Claude Code with `/skill-name`:
 | `/update-slice-status` | Update slice status on the board |
 | `/load-slice` | Persist board slices to disk (backend stacks) |
 | `/build-state-change`, `/build-state-view`, `/build-automation`, `/build-webhook` | Implement a slice's command/view/automation/webhook (backend stacks) |
-| `/request-feedback` | Post a QUESTION comment and mark a slice `Blocked` when it's genuinely ambiguous (backend stacks) |
+| `/request-feedback` | Post a comment and mark a slice `Blocked` when it's genuinely ambiguous (backend stacks) |
 
 Which skills install depends on the chosen stack — see `stacks/<name>/templates/.claude/skills/`. `/connect`, `/learn-eventmodelers-api`, `/update-slice-status`, and `/request-feedback` have no stack-specific content and install into every stack from `shared/skills/` instead.
 

package/cli.js

@@ -70,6 +70,27 @@ const STACKS = {
     useShared: true,
     needsBoardId: true,
   },
+  opencqrs: {
+    label: 'OpenCQRS (Java, EventSourcingDB)',
+    kitSubdir: 'build-kit',
+    kitDirName: '.build-kit',
+    useShared: true,
+    needsBoardId: true,
+  },
+  umadb: {
+    label: 'UmaDB (Java)',
+    kitSubdir: 'build-kit',
+    kitDirName: '.build-kit',
+    useShared: true,
+    needsBoardId: true,
+  },
+  kurrent: {
+    label: 'Kurrent (Java, KurrentDB)',
+    kitSubdir: 'build-kit',
+    kitDirName: '.build-kit',
+    useShared: true,
+    needsBoardId: true,
+  },
 };
 
 // Not a stack — no backend scaffold, just skills + the agent loop. Installed via
@@ -774,7 +795,10 @@ async function installStack(stackKey, stackCfg, options = {}) {
       // first-installed kit added (e.g. node_modules/.idea from a build-kit install).
       const gitignoreDest = join(targetDir, '.gitignore');
       const priorGitignore = existsSync(gitignoreDest) ? readFileSync(gitignoreDest, 'utf-8') : null;
-      copyDirContents(rootSrc, targetDir, { skip: ['CLAUDE.md'] });
+      // .githooks/ (the slice commit-scope guard) is opt-in via `init --hooks` — skipped
+      // here and handled explicitly below so a plain `init` never silently changes the
+      // project's git hook wiring.
+      copyDirContents(rootSrc, targetDir, { skip: ['CLAUDE.md', '.githooks'] });
       if (priorGitignore !== null && existsSync(gitignoreDest)) {
         const incoming = readFileSync(gitignoreDest, 'utf-8');
         const merged = mergeGitignoreLines(priorGitignore, incoming);
@@ -888,6 +912,31 @@ async function installStack(stackKey, stackCfg, options = {}) {
       }
     }
 
+    // --- 3b. Opt-in slice commit-scope guard (`init --hooks`) ---
+    // Skipped from the generic root copy above so a plain `init` never touches git's
+    // hook wiring; installed explicitly here only when requested.
+    if (options.hooks) {
+      const hooksSrc = join(rootSrc, '.githooks');
+      if (existsSync(hooksSrc)) {
+        copyDirContents(hooksSrc, join(targetDir, '.githooks'));
+        const preCommitHook = join(targetDir, '.githooks', 'pre-commit');
+        if (existsSync(preCommitHook)) {
+          // cpSync doesn't reliably carry over the executable bit across platforms,
+          // and git silently skips a non-executable hook.
+          try { execSync(`chmod +x "${preCommitHook}"`); } catch {}
+        }
+        try {
+          execSync('git rev-parse --git-dir', { cwd: targetDir, stdio: 'ignore' });
+          execSync('git config core.hooksPath .githooks', { cwd: targetDir });
+          console.log('  ✓ Installed .githooks/ and set core.hooksPath — commits touching src/slices/ are now scope-guarded');
+        } catch {
+          console.log('  ✓ Installed .githooks/ — run `git config core.hooksPath .githooks` once this directory is a git repo to activate it');
+        }
+      } else {
+        console.log('  ℹ️  --hooks was given but this stack ships no .githooks/ template — nothing to install');
+      }
+    }
+
     // --- 4. Install kit dependencies ---
     if (existsSync(join(kitDir, 'package.json'))) {
       console.log('📦 Installing kit dependencies...');
@@ -1539,6 +1588,7 @@ credentialFlags(program
   .option('--target <name>', `Bridge target framework (${Object.keys(BRIDGE_TARGETS).join(', ')}) — only meaningful with --bridge`)
   .option('--hook <command>', 'Persist a default shell command hook for `bridge` to run per batch of slice changes instead of Claude/Ollama (e.g. commit + push .slices/ for a CI pipeline to pick up) — only meaningful with --bridge. Can also be set per-run with `bridge --hook`.')
   .option('--build-kit', 'Install a blank build-kit scaffold (.build-kit/ + .claude/skills/build-*/SKILL.md placeholders, all TODO-marked) for a stack not built into this CLI yet — no fixed backend. Mutually exclusive with --stack/--modeling/--bridge.')
+  .option('--hooks', 'Install the slice commit-scope guard (.githooks/pre-commit, running .build-kit/lib/check-commit-scope.cjs) and wire it up via `git config core.hooksPath .githooks` — only meaningful with --stack (build-kit stacks). Off by default.')
   .option('--global', 'Install skills into ~/.claude/skills/ instead of the project — available in every project')
   .option('-f, --force', 'Re-prompt for credentials even if a config already has everything required — overwrites the existing config.json'))
   .action(async (opts, command) => {
@@ -1628,6 +1678,7 @@ credentialFlags(program
         force: opts.force,
         credentialOverrides: credentialOverridesFromOpts(opts),
         templatesSource: join(clonedDir, 'templates'),
+        hooks: opts.hooks,
       });
       return;
     }
@@ -1639,6 +1690,7 @@ credentialFlags(program
       global: opts.global,
       force: opts.force,
       credentialOverrides: credentialOverridesFromOpts(opts),
+      hooks: opts.hooks,
     });
   });
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.45",
-  "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, Cratis, or modeling-only)",
+  "version": "1.0.47",
+  "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, Cratis, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
   "type": "module",
   "bin": {
     "eventmodelers": "cli.js"

package/shared/build-kit/lib/checks/README.md

@@ -0,0 +1,59 @@
+# Commit-scope guard checks
+
+Every `*.cjs` file in this folder is loaded and run automatically by
+`../check-commit-scope.cjs` against the staged changeset of a slice commit
+(a commit that touches `src/slices/{context}/{slice}/**`). Files run in
+filename sort order — that's why they're numbered.
+
+## Adding a check
+
+Create a new file here, e.g. `60-my-check.cjs`, exporting:
+
+```js
+'use strict';
+
+module.exports = {
+  name: 'my-check',            // short id, prefixed onto any violation it reports
+  skipIfAlreadyFailing: false, // optional: true = skip this check once an earlier
+                                // one already found a violation (use for slow checks,
+                                // e.g. a build/typecheck — no point running it if the
+                                // commit is already going to be rejected)
+  run(ctx) {
+    // Inspect ctx and return an array of violations. No violations → return
+    // [] (or undefined/null).
+    return [
+      { path: 'src/slices/cart/AddItem/AddItemCommand.ts', reason: 'why this is a problem' },
+    ];
+  },
+};
+```
+
+### `ctx` passed to every check
+
+| field           | type            | meaning                                                              |
+|-----------------|-----------------|-----------------------------------------------------------------------|
+| `changes`       | `{status, path}[]` | staged files — `status` is git's single-letter code (`A`/`M`/`D`/...) |
+| `touchesSlice`  | `boolean`       | always `true` — the runner only loads checks once this is true        |
+| `repoRoot`      | `string`        | absolute path to the repo root (`git rev-parse --show-toplevel`)       |
+| `SLICE_PATTERN` | `RegExp`        | matches a path inside a slice's own folder: `src/slices/{ctx}/{slice}/`|
+
+### Return value
+
+An array of `{ path, reason }` objects — one per violation. `path` should be
+the offending file (or a synthetic label like `'(slice.json)'` if the problem
+isn't tied to one staged file). `reason` is a short, human-readable sentence
+explaining what's wrong; the runner prefixes it with `[<check name>]`.
+
+Return `[]`, `undefined`, or `null` when there's nothing to report. Throwing
+is treated as a violation too (`[<check name>] threw: <message>`), so a check
+doesn't need its own top-level try/catch.
+
+### Conventions used by the existing checks
+
+- Prefer **not blocking** over a false positive when a check can't determine
+  the answer confidently (e.g. slice.json isn't found, or a file's shape isn't
+  recognized) — these are heuristics layered on top of the hard path-scope
+  rules, not a full compiler/schema validator.
+- If two checks would flag the *same file*, only the first one to run reports
+  it (the runner dedupes by path) — so keep genuinely distinct concerns in
+  separate files rather than trying to avoid overlap yourself.

package/shared/build-kit/lib/ralph.js

@@ -201,14 +201,28 @@ async function fetchAndPersistSlices(cfg, kitDir) {
     writeFileSync(ctxPath, JSON.stringify({ name: activeCtx }, null, 2), 'utf-8');
   }
 
-  // Write per-context index.json and per-slice slice.json
+  // Write per-context index.json and per-slice slice.json.
+  //
+  // This endpoint (`/slicedata/slices`) is the CHEAP summary one — `{ id, title, status }`
+  // only, no commands/events/specifications/codeGen prompts. Its whole job here is to keep
+  // `status` fresh so hasPendingTasks/getFirstPlannedSliceTitle see live transitions; it must
+  // NEVER clobber the richer slice.json a full fetch (`/load-slice`, `eventmodelers fetch`,
+  // `eventmodelers listen`) already wrote for the same slice. So every write below merges
+  // onto whatever's already on disk — spreading the existing object first, the fresh summary
+  // fields second — instead of replacing it wholesale.
   for (const [contextSlug, { slices: ctxSlices }] of Object.entries(contexts)) {
     const contextDir = join(slicesDir, contextSlug);
     mkdirSync(contextDir, { recursive: true });
 
+    const indexPath = join(contextDir, 'index.json');
+    const existingIndex = existsSync(indexPath) ? JSON.parse(readFileSync(indexPath, 'utf-8')) : { slices: [] };
+    const existingById = new Map((existingIndex.slices ?? []).map((e) => [e.id, e]));
+
     const indexSlices = ctxSlices.map((s, i) => {
       const folder = (s.title ?? s.id).replaceAll(' ', '').toLowerCase();
+      const existing = existingById.get(s.id);
       return {
+        ...existing,
         id: s.id,
         slice: s.title,
         index: i,
@@ -216,16 +230,18 @@ async function fetchAndPersistSlices(cfg, kitDir) {
         contextSlug,
         folder,
         status: s.status,
-        definition: { id: s.id, title: s.title, status: s.status },
+        definition: { ...existing?.definition, id: s.id, title: s.title, status: s.status },
       };
     });
-    writeFileSync(join(contextDir, 'index.json'), JSON.stringify({ slices: indexSlices }, null, 2), 'utf-8');
+    writeFileSync(indexPath, JSON.stringify({ slices: indexSlices }, null, 2), 'utf-8');
 
     for (const slice of ctxSlices) {
       const folder = (slice.title ?? slice.id).replaceAll(' ', '').toLowerCase();
       const sliceDir = join(contextDir, folder);
       mkdirSync(sliceDir, { recursive: true });
-      writeFileSync(join(sliceDir, 'slice.json'), JSON.stringify(slice, null, 2), 'utf-8');
+      const sliceJsonPath = join(sliceDir, 'slice.json');
+      const existingSlice = existsSync(sliceJsonPath) ? JSON.parse(readFileSync(sliceJsonPath, 'utf-8')) : {};
+      writeFileSync(sliceJsonPath, JSON.stringify({ ...existingSlice, ...slice }, null, 2), 'utf-8');
     }
   }
 
@@ -265,30 +281,83 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
 
   const channelName = `board:${cfg.boardId}-slicechanged`;
   const realtime = await createRealtimeAdapter(cfg, realtimeToken);
-  realtime.subscribe(
-    channelName,
-    {
-      message: (payload) => {
-        if (payload === 'Exit') {
-          console.log('[agent] Received "Exit" — shutting down');
-          process.exit(0);
+
+  // Shared by the scheduled timer, a CHANNEL_ERROR/TIMED_OUT subscribe status, and a
+  // 401 from the alive-ping — whichever notices the token is bad first wins; the rest
+  // just await the same in-flight refresh instead of firing duplicate mint requests.
+  const ts = () => new Date().toISOString();
+  let refreshing = null;
+  const refreshToken = (reason) => {
+    if (!refreshing) {
+      const startedAt = Date.now();
+      console.log(`[agent] ${ts()} Refreshing realtime token (reason: ${reason})...`);
+      refreshing = (async () => {
+        try {
+          realtimeToken = await retryOn401('getRealtimeToken (refresh)', () => getRealtimeToken(cfg));
+          await realtime.setAuth(realtimeToken);
+          console.log(`[agent] ${ts()} Token refreshed (reason: ${reason}, took ${Date.now() - startedAt}ms)`);
+        } catch (err) {
+          console.error(`[agent] ${ts()} Token refresh FAILED (reason: ${reason}):`, err);
+          throw err;
+        } finally {
+          refreshing = null;
         }
+      })();
+    }
+    return refreshing;
+  };
+
+  // A subscribe that errors on a stale token needs a fresh token AND a new join
+  // attempt — setAuth alone doesn't re-join a channel that already errored out.
+  // Capped so a non-expiry auth failure (e.g. genuinely revoked access) can't turn
+  // into a tight resubscribe loop hammering the platform forever.
+  let channelErrorStreak = 0;
+  const subscribeChannel = () => {
+    realtime.subscribe(
+      channelName,
+      {
+        message: (payload) => {
+          if (payload === 'Exit') {
+            console.log(`[agent] ${ts()} Received "Exit" — shutting down`);
+            process.exit(0);
+          }
+        },
+        'slice:changed': (payload) => handleSliceChanged(payload, cfg, kitDir, queueAllStatuses),
       },
-      'slice:changed': (payload) => handleSliceChanged(payload, cfg, kitDir, queueAllStatuses),
-    },
-    (status) => console.log(`[agent] Channel "${channelName}": ${status}`),
-  );
+      async (status) => {
+        if (status !== 'CHANNEL_ERROR' && status !== 'TIMED_OUT') {
+          if (channelErrorStreak > 0) {
+            console.log(`[agent] ${ts()} Channel "${channelName}": ${status} — recovered after ${channelErrorStreak} failed attempt(s)`);
+          } else {
+            console.log(`[agent] ${ts()} Channel "${channelName}": ${status}`);
+          }
+          channelErrorStreak = 0;
+          return;
+        }
+        channelErrorStreak += 1;
+        console.warn(`[agent] ${ts()} Channel "${channelName}": ${status} (attempt ${channelErrorStreak}/5)`);
+        if (channelErrorStreak > 5) {
+          console.error(`[agent] ${ts()} Channel "${channelName}" failed ${channelErrorStreak} times in a row — giving up until the next scheduled token refresh (every 10min)`);
+          return;
+        }
+        try {
+          await refreshToken(`channel ${status}`);
+          await new Promise((r) => setTimeout(r, 2_000));
+          console.log(`[agent] ${ts()} Resubscribing to channel "${channelName}" (attempt ${channelErrorStreak}/5)...`);
+          subscribeChannel();
+        } catch (err) {
+          console.error(`[agent] ${ts()} Token refresh after channel error failed, will not resubscribe this round:`, err);
+        }
+      },
+    );
+  };
+  subscribeChannel();
 
-  setInterval(async () => {
-    try {
-      realtimeToken = await retryOn401('getRealtimeToken (refresh)', () => getRealtimeToken(cfg));
-      await realtime.setAuth(realtimeToken);
-      console.log('[agent] Token refreshed');
-    } catch (err) {
-      console.error('[agent] Token refresh failed:', err);
-    }
+  setInterval(() => {
+    refreshToken('scheduled 10min refresh').catch((err) => console.error(`[agent] ${ts()} Scheduled token refresh failed:`, err));
   }, 10 * 60 * 1000);
 
+  let lastPingFailed = false;
   const ping = async () => {
     try {
       const res = await fetch(`${cfg.baseUrl}/api/agent-alive`, {
@@ -297,9 +366,19 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
         body: JSON.stringify({ token: cfg.token, board_id: cfg.boardId, agent_type: agentType, agent_id: cfg.agentId }),
         signal: AbortSignal.timeout(10_000),
       });
-      if (!res.ok) console.error(`[agent] Ping failed: ${res.status} ${await res.text().catch(() => '')}`);
+      if (!res.ok) {
+        console.error(`[agent] ${ts()} Ping failed: ${res.status} ${await res.text().catch(() => '')}`);
+        lastPingFailed = true;
+        if (res.status === 401) {
+          await refreshToken('ping-401').catch((err) => console.error(`[agent] ${ts()} Token refresh after 401 ping failed:`, err));
+        }
+        return;
+      }
+      if (lastPingFailed) console.log(`[agent] ${ts()} Ping recovered`);
+      lastPingFailed = false;
     } catch (err) {
-      console.error('[agent] Ping error:', err);
+      console.error(`[agent] ${ts()} Ping error:`, err);
+      lastPingFailed = true;
     }
   };
   await ping();
@@ -354,10 +433,13 @@ async function runWithRetry(label, fn) {
   }
 }
 
-async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice) {
+async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false) {
   const promptFile = join(kitDir, 'lib', 'prompt.md');
   const backendPromptFile = join(kitDir, 'lib', 'backend-prompt.md');
-  const credentialed = hasCredentials(cfg);
+  // --local must mean zero board contact even when .eventmodelers/config.json
+  // happens to hold valid credentials — never let a locally-present token flip
+  // this back on.
+  const credentialed = !localOnly && hasCredentials(cfg);
   let lastIdleCtx;
 
   while (true) {
@@ -410,7 +492,7 @@ export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice, a
   // reaches out to the platform at all.
   if (localOnly || !hasCredentials(local)) {
     console.log(`         mode: local-only (no platform sync)${localOnly ? ' — forced by --local' : ''}\n`);
-    await ralphLoop(kitDir, local, onTask, onPlannedSlice);
+    await ralphLoop(kitDir, local, onTask, onPlannedSlice, localOnly);
     return;
   }
 

package/shared/build-kit/lib/util/find-slice.cjs

@@ -0,0 +1,59 @@
+'use strict';
+
+// Shared by checks that need to cross-reference code against the slice's own
+// definition. Not a check itself — no `run(ctx)` interface here.
+
+const fs = require('fs');
+const path = require('path');
+
+function normalize(s) {
+  return String(s || '').toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+// Given the {context}/{SliceName} folder names used under src/slices/, find the
+// matching slice.json under .build-kit/.slices/<contextSlug>/<sliceFolder>/. The
+// two sides are slugified differently (see shared/skills/load-slice/SKILL.md —
+// contextSlug is hyphenated, sliceFolder strips all spaces), so this matches on
+// a normalized (lowercase, alphanumeric-only) form instead of exact equality.
+// Returns null — never throws — when zero or more than one candidate matches;
+// callers should treat that as "can't verify" and skip rather than block.
+function findSliceJson(repoRoot, context, sliceName) {
+  const root = path.join(repoRoot, '.build-kit', '.slices');
+  if (!fs.existsSync(root)) return null;
+
+  const wantSlice = normalize(sliceName);
+  const candidates = [];
+
+  let contextDirs;
+  try {
+    contextDirs = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  for (const contextDir of contextDirs) {
+    if (!contextDir.isDirectory()) continue;
+    const contextPath = path.join(root, contextDir.name);
+    let sliceDirs;
+    try {
+      sliceDirs = fs.readdirSync(contextPath, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const sliceDir of sliceDirs) {
+      if (!sliceDir.isDirectory()) continue;
+      if (normalize(sliceDir.name) !== wantSlice) continue;
+      const slicePath = path.join(contextPath, sliceDir.name, 'slice.json');
+      if (fs.existsSync(slicePath)) candidates.push(slicePath);
+    }
+  }
+
+  if (candidates.length !== 1) return null;
+  try {
+    return JSON.parse(fs.readFileSync(candidates[0], 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { findSliceJson, normalize };

package/shared/build-kit/ralph-claude.js

@@ -11,7 +11,11 @@ const kitDir = dirname(fileURLToPath(import.meta.url));
 const projectDir = process.argv[2] ? resolve(process.argv[2]) : resolve(kitDir, '..');
 
 const cfg = loadLocalConfig(kitDir);
-const inlineHeader = cfg.boardId
+const localOnly = process.env.RALPH_LOCAL === '1';
+// --local must mean zero board contact — never hand Claude live board
+// credentials via the inline header, even if config.json has them, or it'll
+// treat them as already-connected and skip straight to board sync.
+const inlineHeader = !localOnly && cfg.boardId
   ? `board=${cfg.boardId} token=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n`
   : '';
 
@@ -96,7 +100,7 @@ startRalph({
   projectDir,
   onTask: runClaude,
   onPlannedSlice: runClaude,
-  localOnly: process.env.RALPH_LOCAL === '1',
+  localOnly,
 }).catch((err) => {
   console.error('[ralph] Fatal:', err);
   process.exit(1);

package/shared/skills/learn-eventmodelers-api/SKILL.md

@@ -54,7 +54,7 @@ Server name: `eventmodelers`. Every tool takes `boardId` explicitly; none need `
 | `set_connection` | `boardId`, `source`, `target`, `action` (`'connect'\|'remove'`) | Add or remove a type-checked directed edge. Batch form `set_connections` takes `connections[]` (applied in order) plus `compact?` — `compact: true` returns a `{connected, existed, removed, notFound, failed, errors}` tally instead of one row per edge | — (via `edges` on §3 events) |
 | `auto_connect_node` | `boardId`, `nodeId` | Re-run auto-connect for a node | §3 `POST .../nodes/:nodeId/auto-connect` |
 | `link_element` | `boardId`, `nodeId`, `targetNodeId` | Link two existing same-type nodes: `targetNodeId` is replaced with a full copy of `nodeId`'s meta plus `meta.linkedTo`. Linking means first create, then link | §3 `POST .../nodes/:nodeId/link` |
-| `add_comment` | `boardId`, `nodeId`, `text`, `type?` (`'COMMENT'\|'TASK'\|'QUESTION'`), `author?` | Add a comment — `QUESTION` flags gaps/edge cases during review | — (via comment events) |
+| `add_comment` | `boardId`, `nodeId`, `text`, `type?` (`'COMMENT'\|'TASK'`), `author?` | Add a comment — word the `text` as a question to flag gaps/edge cases during review; there is no separate `QUESTION` type | — (via comment events) |
 | `update_comment` | `boardId`, `nodeId`, `commentId`, `action` (`'resolve'\|'delete'`) | Resolve or delete a comment | — (via comment events) |
 | `create_screen` | `boardId`, `contentType` (`'image'\|'sketch'\|'html'`), `nodeId?`, `chapterId`, `cellId?`/`cellName?`, plus content fields (`imageBase64`/`mimeType`, `elements[]`, or `pages[]`/`backgroundColor`), `description?`, `fields?`, `autoConnect?` | Create + place a new screen node (SCREEN or HTML_SCREEN) atomically, in one call. Batch form `create_screens` takes `screens[]` (HTML only) + `autoConnect?`. `autoConnect: false` places without wiring to timeline neighbors | §4 `POST .../images/:id/sketch` + `image-nodes` |
 | `render_screen` | `boardId`, `nodeId`, `elements[]?` (SCREEN) or `pages[]?`+`backgroundColor?` (HTML_SCREEN), `description?` | Update an existing screen's content — exactly one of `elements`/`pages` | §4 `POST .../images/:id/sketch` + `image-nodes` |
@@ -66,7 +66,7 @@ Server name: `eventmodelers`. Every tool takes `boardId` explicitly; none need `
 | `commit_board_to_git` | `boardId` | Force a git-extension commit/push, bypassing the autoCommit gate | — (MCP-only; git extension) |
 | `update_prompt_status` | `promptId`, `newStatus`, `comment?` | Update a prompt's lifecycle status (`ADDED`/`CLAIMED`/`IN_PROGRESS`/`DONE`), optionally with a progress comment. Not board-scoped — no `boardId` arg; the prompt's board is resolved server-side. | §14 `POST .../prompts/:id/status` |
 
-**Not exposed via MCP at all** — always use REST/curl for these: §7 Config Import, §10 Snapshots, §11–12 User Management, §13 Utility (`/api/user`, swagger), and the rest of §14 Prompts (submission, claiming, deletion, realtime-token) — only the status-update endpoint has an MCP tool (`update_prompt_status`, used by the `update-prompt-status` skill); everything else in Prompts is an intentionally separate lifecycle the board-content MCP server doesn't otherwise own.
+**Not exposed via MCP at all** — always use REST/curl for these: §7 Config Import, §10 Snapshots, §11–12 Invitations, §13 Utility (`/api/user`, swagger), and the rest of §14 Prompts (submission, claiming, deletion, realtime-token) — only the status-update endpoint has an MCP tool (`update_prompt_status`, used by the `update-prompt-status` skill); everything else in Prompts is an intentionally separate lifecycle the board-content MCP server doesn't otherwise own.
 
 **Capabilities with no direct MCP filter** — e.g. REST's `GET .../nodes?cellId=<id>&timelineId=<id>` and `?colId=<id>&timelineId=<id>` (§3) have no equivalent params on `get_nodes`. Either call the REST endpoint directly, or get the same answer by calling `get_node` on the CHAPTER and reading `meta.timelineData.cells` (sparse array; a cell absent from it is empty) instead of asking the server to filter by cell/column.
 
@@ -736,58 +736,48 @@ Delete a snapshot.
 
 ---
 
-## 11. User Management — Commands (Event Sourced)
+## 11. Invitations (Organization Membership) — Commands
 
-All commands respond with:
-```typescript
-{
-  ok: true
-  next_expected_stream_version: number
-  last_event_global_position: number
-}
-```
-
-Optional headers on all: `correlation_id`, `causation_id`
+**Files**: `src/slices/organization/InviteUser/routes.ts`, `src/slices/organization/ConfirmInvitation/routes.ts`, `src/slices/organization/DeleteInvitation/routes.ts`
 
-### POST `/api/creategroup`
-**Body**: `{ groupId: string, name: string }`  
-**Event emitted**: `GroupCreated`
+There is no generic "group"/"role-assignment" API — an organization *is* the group, and a
+member's role is set once, at invite time (there is no separate call to change an existing
+member's role afterward). All of these require a Supabase JWT (`Authorization: Bearer`), never
+a bot `x-token`.
 
----
+### POST `/api/org/:orga_id/invitations`
+Invite a user to join an organization with a given role. Caller must already be an `admin` of `orga_id`.
 
-### POST `/api/inviteuser`
-**Body**: `{ groupId: string, email: string, invitationId: string }`  
-**Event emitted**: `UserInvited`
+**Body**: `{ role: string, email: string, description?: string }`
+**Response**: `201` — invitation created
+**Errors**: `400` role/email missing · `403` caller is not an org admin · `409` user already invited or already a member
 
 ---
 
-### POST `/api/acceptinvite`
-**Body**: `{ userId: string, groupId: string, invitationId: string }`  
-**Event emitted**: `InvitationAccepted`
-
----
+### POST `/api/invitations/:token/confirm`
+Accept an invitation — `token` is the invitation's own token (from the invite email link), not an API token. The confirming user's own account email must match the invited email.
 
-### POST `/api/assignrole`
-**Body**: `{ userId: string, groupId: string, role: string }`  
-**Event emitted**: `RoleAssigned`
+**Response**: `200` — invitation confirmed, membership created
+**Errors**: `404` invitation not found
 
 ---
 
-## 12. User Management — Read Models (Projections)
+### DELETE `/api/org/:orga_id/invitations/:invitation_id`
+Cancel a pending invitation.
 
-All require authentication. Optional query param `_id` to filter by ID.
+**Response**: `200`/`204` on success
+
+---
 
-### GET `/api/query/group-details-lookup`
-Group details. Filter: `?_id=groupId`
+## 12. Invitations (Organization Membership) — Read Models
 
-### GET `/api/query/open-invites`
-Pending invitations. Filter: `?_id=invitationId`
+All require a Supabase JWT (`Authorization: Bearer`).
 
-### GET `/api/query/user-group-assignments`
-User-to-group mappings. Filter: `?_id=groupId`
+### GET `/api/user-organizations`
+Organizations (and the caller's role in each) that the authenticated user belongs to.
 
-### GET `/api/query/users-to-assign-to-groups`
-Users available for group assignment. Filter: `?_id=userId`
+### GET `/api/client/org/:orgId/invitations`
+Pending invitations for an organization (client-facing list — used by the org settings UI).
 
 ---
 
@@ -883,6 +873,22 @@ Exchange an `x-token` for a short-lived Supabase-compatible JWT, used to subscri
 
 ---
 
+### POST `/api/agent-alive`
+Record a heartbeat ping for a running modeling/build agent. Auth: Supabase JWT (`Authorization: Bearer`) — exchange the `x-token` for one first via `GET /api/org/:orgId/prompts/realtime-token` above; a raw `x-token` alone is not accepted here.
+
+**Body**: `{ token: string, board_id?: string, agent_type: 'MODELING' | 'BUILD', agent_id: string }`
+**Response**: `200` — `{ ok: true }`
+**Errors**: `400` `agent_id`/`agent_type` missing · `404` token not found
+
+---
+
+### GET `/api/org/:orgId/boards/:boardId/agent-alive`
+Check whether an agent has pinged for a board within the last 45s. Auth: `x-token` (bot) or a Supabase JWT (`Authorization: Bearer`) — either works.
+
+**Response**: `200` — `{ alive: boolean, agentTypes: string[] }`
+
+---
+
 ## Domain Events
 
 ### Snapshot Events (`src/events/SnapshotsEvents.ts`)
@@ -896,14 +902,14 @@ SnapshotShared          // { id }
 SnapshotPublished       // { id, payloadId, bucket, path }
 ```
 
-### User Management Events (`src/events/UserManagementEvents.ts`)
+### Invitation Events (`src/slices/organization/OrganizationEvent.ts`)
 
 ```typescript
-GroupCreated          // { groupId, owner, name }
-UserAssignedToGroup   // { groupId, userId }
-UserInvited           // { groupId, invitationId, email }
-InvitationAccepted    // { invitationId, groupId, userId }
-RoleAssigned          // { groupId, userId, role }
+UserInvited                  // { orgaId, userId, role, invitationId, token, description?, boardId?, email? }
+InvitationConfirmed          // { orgaId, userId, invitationId, token?, email? }
+InvitationDeleted            // { invitationId }
+UserAssignedToOrganization   // { id, userId, orgaId, role?, boardId?, email? }
+UserRemovedFromOrganization  // { orgaId, userId }
 ```
 
 All events support optional metadata: `user_id`, `correlation_id`, `causation_id`
@@ -928,7 +934,7 @@ All events support optional metadata: `user_id`, `correlation_id`, `causation_id
 | `src/slices/slicedata/routes.ts` | Slice data read models |
 | `src/slices/extensions/routes.ts` | Extension management |
 | `src/slices/Snapshots/routes.ts` | Snapshot CRUD |
-| `src/slices/usermanagement/*/routes*.ts` | User management commands + projections |
+| `src/slices/organization/InviteUser/routes.ts`, `ConfirmInvitation/routes.ts`, `DeleteInvitation/routes.ts` | Organization invitation commands |
 | `src/events/SnapshotsEvents.ts` | Snapshot domain events |
-| `src/events/UserManagementEvents.ts` | User management domain events |
+| `src/slices/organization/OrganizationEvent.ts` | Organization/invitation domain events |
 | `backend/src/server.ts` | Route wiring, CORS, `/api/user` |