@eventmodelers/cli 1.0.13 → 1.0.17

package/README.md

@@ -105,6 +105,7 @@ npx @eventmodelers/cli re-init                      # refresh an already-install
 npx @eventmodelers/cli run                          # start the agent loop (ralph-claude.js) from the installed kit dir
 npx @eventmodelers/cli run --ollama                 # same, via local Ollama (ralph-ollama.js)
 npx @eventmodelers/cli run --bash                   # bash-only loop, no realtime (ralph.sh)
+npx @eventmodelers/cli run --local                  # skip platform config/credential lookup entirely — local-only, no board sync
 npx @eventmodelers/cli fetch --context <name>                     # pull full slice detail for one context on the board into <kit-dir>/.slices/
 npx @eventmodelers/cli fetch --context <name> --slice-id <id>     # same, then print just that slice
 npx @eventmodelers/cli fetch --context <name> --slice-title <title> # same, then print just the slice matching this title

package/cli.js

@@ -1772,6 +1772,7 @@ program
   .option('--ollama', 'Use ralph-ollama.js instead of the default Claude runner (build-kit stacks only)')
   .option('--bash', 'Use the bash-only ralph.sh loop (build-kit stacks only, no realtime)')
   .option('--modeling', 'Keep one Claude process warm across prompts instead of spawning a fresh one per task, for low-latency voice/live use. Modeling-kit installs only — there is no cold-spawn/tasks.json loop for modeling-kit. Built into the CLI, not a per-project file.')
+  .option('--local', 'Skip platform config/credential lookup entirely and run the local-only loop (no board sync, no realtime agent) — even if .eventmodelers/config.json has credentials (build-kit stacks only)')
   .option('--verbose', 'Log every tool call\'s full input (commands, skill args, file paths) and assistant reasoning text. Default is condensed, high-level per-step logging only.')
   .action(async (opts) => {
     const cwd = process.cwd();
@@ -1799,6 +1800,10 @@ program
         console.error('❌ --modeling is mutually exclusive with --bash/--ollama — those select a build-kit runner, which --modeling has no use for.');
         process.exit(1);
       }
+      if (opts.local) {
+        console.error('❌ --modeling has no local-only mode — it is always driven by the org-wide realtime prompt queue, so --local has no use for it.');
+        process.exit(1);
+      }
       if (!modelingKitDir) {
         console.error(`❌ --modeling only supports a modeling-kit install (${MODELING_KIT.kitDirName}/) — it subscribes to the org-wide prompt queue, which build-kit stacks don't have. Use \`eventmodelers run\` (optionally with --ollama/--bash) for build-kit's slice-status loop instead.`);
         process.exit(1);
@@ -1850,9 +1855,11 @@ program
     console.log(`▶ Starting ${relative(cwd, runnerPath)}...\n`);
     const cmd = runner.endsWith('.sh') ? `"${runnerPath}"` : `node "${runnerPath}"`;
     try {
-      // Only ralph-claude.js reads this — the bash loop and the ollama executor have
-      // their own separate output paths with no stream-json parsing to gate.
-      execSync(cmd, { cwd: kitDir, stdio: 'inherit', env: { ...process.env, RALPH_VERBOSE: opts.verbose ? '1' : '' } });
+      // Only ralph-claude.js reads RALPH_VERBOSE — the bash loop and the ollama executor have
+      // their own separate output paths with no stream-json parsing to gate. RALPH_LOCAL is
+      // read by all three runners (ralph.js's startRalph, and ralph.sh directly) to force the
+      // local-only branch even when .eventmodelers/config.json has valid credentials.
+      execSync(cmd, { cwd: kitDir, stdio: 'inherit', env: { ...process.env, RALPH_VERBOSE: opts.verbose ? '1' : '', RALPH_LOCAL: opts.local ? '1' : '' } });
     } catch (err) {
       process.exit(err.status || 1);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.13",
+  "version": "1.0.17",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, Cratis, or modeling-only)",
   "type": "module",
   "bin": {

package/shared/build-kit/lib/adapters/supabase-realtime-adapter.js

@@ -10,7 +10,7 @@ export async function createSupabaseRealtimeAdapter(cfg, initialToken) {
   await supabase.realtime.setAuth(initialToken);
 
   return {
-    subscribe(topic, handlers, onStatus) {
+    async subscribe(topic, handlers, onStatus) {
       let channel = supabase.channel(topic, { config: { private: true } });
       for (const [event, handler] of Object.entries(handlers)) {
         channel = channel.on('broadcast', { event }, (msg) => handler(msg.payload));

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

@@ -397,15 +397,19 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice) {
 
 export { loadLocalConfig, fetchPlatformConfig, retryOn401, startRealtimeAgent };
 
-export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice, agentType = 'BUILD', queueAllStatuses = false }) {
+export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice, agentType = 'BUILD', queueAllStatuses = false, localOnly = false }) {
   const local = loadLocalConfig(kitDir);
   local.agentId = ensureAgentId(kitDir, agentType);
 
   console.log(`Ralph — kit: ${kitDir}`);
   console.log(`         project: ${projectDir}`);
 
-  if (!hasCredentials(local)) {
-    console.log(`         mode: local-only (no platform sync)\n`);
+  // localOnly (set via `eventmodelers run --local`) forces this branch even when
+  // credentials are present — it skips fetchPlatformConfig's network call to
+  // ${baseUrl}/api/config and startRealtimeAgent entirely, so the loop never
+  // 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);
     return;
   }

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

@@ -96,6 +96,7 @@ startRalph({
   projectDir,
   onTask: runClaude,
   onPlannedSlice: runClaude,
+  localOnly: process.env.RALPH_LOCAL === '1',
 }).catch((err) => {
   console.error('[ralph] Fatal:', err);
   process.exit(1);

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

@@ -33,6 +33,7 @@ startRalph({
   projectDir,
   onTask: runOllama,
   // onPlannedSlice omitted — ollama-agent manages its own task queue
+  localOnly: process.env.RALPH_LOCAL === '1',
 }).catch((err) => {
   console.error('[ralph] Fatal:', err);
   process.exit(1);

package/shared/build-kit/ralph.sh

@@ -21,7 +21,10 @@ BACKEND_PROMPT_FILE="$KIT_DIR/lib/backend-prompt.md"
 AGENT_SCRIPT="$KIT_DIR/lib/agent.sh"
 
 HAS_CREDENTIALS=true
-if [[ ! -f "$KIT_DIR/.eventmodelers/config.json" ]]; then
+if [[ "${RALPH_LOCAL:-}" == "1" ]]; then
+  echo "[ralph] --local — platform sync disabled." >&2
+  HAS_CREDENTIALS=false
+elif [[ ! -f "$KIT_DIR/.eventmodelers/config.json" ]]; then
   echo "[ralph] Note: no .eventmodelers/config.json found — platform sync disabled." >&2
   echo "        To enable board sync, follow: https://app.eventmodelers.ai/documentation#build" >&2
   echo "        Code generation from local slice definitions will still run." >&2

package/stacks/axon/templates/.claude/skills/build-automation/SKILL.md

@@ -38,6 +38,10 @@ Read the target project's `.build-kit/CLAUDE.md` and explore existing slices. Lo
 - Feature flag patterns (Step 4 — optional)
 - Spring Boot test annotation: check if the project defines a meta-annotation over `@SpringBootTest`
 
+**Determine `{basePackage}`** — every path below is rooted at
+`{basePackage}.slices.{context}.automation.{slicename}`. Resolve `{basePackage}` as documented in
+`.build-kit/CLAUDE.md`'s Structure section.
+
 ## Step 1: Understand the Input
 
 Extract these elements regardless of input format:
@@ -131,7 +135,7 @@ If a command fails, the event handler fails and the event processor retries.
 ### Stateless Automation
 
 New automation slices live under
-`src/main/java/de/eventmodelers/slices/{context}/automation/{slicename}/`.
+`src/main/java/.../slices/{context}/automation/{slicename}/`.
 
 #### Strategy interface (if needed)
 
@@ -280,7 +284,7 @@ Add to ALL config files when using `@ConditionalOnProperty`:
 **For stateless automations** — pure unit tests with a mocked `CommandDispatcher`:
 
 ```java
-// File: src/test/java/de/eventmodelers/slices/{context}/automation/{slicename}/{AutomationName}Test.java
+// File: src/test/java/.../slices/{context}/automation/{slicename}/{AutomationName}Test.java
 class {AutomationName}ProcessorTest {
 
     private {AutomationName}Processor processor;

package/stacks/axon/templates/.claude/skills/build-automation-workflow/SKILL.md

@@ -19,7 +19,8 @@ description: >
 > **Preview feature** — AF5 Workflow APIs may change without notice and are not yet for production.
 
 New workflow slices live under
-`src/main/java/de/eventmodelers/slices/{context}/automation/{slicename}/`.
+`src/main/java/.../slices/{context}/automation/{slicename}/` — see Step 0 below for how to resolve the
+`{basePackage}` this path is rooted at.
 
 ---
 
@@ -32,6 +33,11 @@ Read `.build-kit/CLAUDE.md` and check whether the project already uses AF5 Workf
 - A `WorkflowModule` bean in any `@Configuration` class
 - Classes annotated with `@Workflow`
 - Existing `*Workflow.java` files under any slice package
+
+**Determine `{basePackage}`** — every path in this skill is rooted at
+`{basePackage}.slices.{context}.automation.{slicename}`. Resolve `{basePackage}` as documented in
+`.build-kit/CLAUDE.md`'s Structure section.
+
 - The `WorkflowModule` dependency in `pom.xml`:
 
 ```xml
@@ -92,7 +98,7 @@ The simplest way to define a workflow using `@Workflow`:
 
 ```java
 // File: {slicename}/{SliceName}Workflow.java
-package de.eventmodelers.slices.{context}.automation.{slicename};
+package {basePackage}.slices.{context}.automation.{slicename};
 
 import org.axonframework.workflow.annotation.Workflow;
 import org.axonframework.workflow.SimpleWorkflowContext;
@@ -100,7 +106,7 @@ import org.axonframework.workflow.SimpleWorkflowContext;
 @Workflow(
     idProperty       = "{triggerEventIdField}",    // field name on the trigger event that becomes the workflow ID
     startOnEventClass = {TriggerEvent}.class,       // event that starts a new workflow instance
-    workflowNamespace = "de.eventmodelers.slices.{context}"
+    workflowNamespace = "{basePackage}.slices.{context}"
 )
 public class {SliceName}Workflow {
 
@@ -333,7 +339,7 @@ public void execute(SimpleWorkflowContext ctx) {
 
 ```java
 @Workflow(idProperty = "id", startOnEventClass = OrderPlaced.class,
-          workflowNamespace = "de.eventmodelers.slices.{context}")
+          workflowNamespace = "{basePackage}.slices.{context}")
 public class {SliceName}Workflow {
 
     public void execute(SimpleWorkflowContext ctx) { /* ... */ }
@@ -476,14 +482,14 @@ class {SliceName}WorkflowIntegrationTest extends AbstractDeclarativeTestBase {
 ## Files to Create / Modify
 
 ```
-src/main/java/de/eventmodelers/slices/{context}/automation/{slicename}/
+src/main/java/.../slices/{context}/automation/{slicename}/
 ├── {SliceName}Workflow.java              ← @Workflow class (execute method + lifecycle listeners)
 └── {SliceName}WorkflowServices.java      ← @Component step handlers (Spring beans)
 
-src/main/java/de/eventmodelers/slices/{context}/
+src/main/java/.../slices/{context}/
 └── WorkflowConfiguration.java            ← WorkflowModule bean (one per context, create if missing)
 
-src/test/java/de/eventmodelers/slices/{context}/automation/{slicename}/
+src/test/java/.../slices/{context}/automation/{slicename}/
 └── {SliceName}WorkflowTest.java          ← unit tests with mocked context + services
 ```
 

package/stacks/axon/templates/.claude/skills/build-state-change/SKILL.md

@@ -35,12 +35,18 @@ Read `.build-kit/.slices/{context}/{slicename}/slice.json`. Extract, and use **o
 
 Never invent a field, business rule, or event that isn't in slice.json.
 
+## Step 0a: Determine `{basePackage}`
+
+Every code example below is rooted at `{basePackage}.slices.{context}.{slicename}`. Resolve
+`{basePackage}` as documented in `.build-kit/CLAUDE.md`'s Structure section — never hardcode
+`io.axoniq.quickstart` (the shipped quickstart scaffold's package) or any other specific package.
+
 ## Step 1: Command
 
 **Exactly one field has `idAttribute: true` in slice.json** — annotate it directly:
 
 ```java
-package io.axoniq.quickstart.slices.{context}.{slicename};
+package {basePackage}.slices.{context}.{slicename};
 
 import org.axonframework.messaging.commandhandling.annotation.Command;
 import org.axonframework.modelling.annotation.TargetEntityId;
@@ -61,13 +67,13 @@ one field directly.** Instead build a compound id record and put `@TargetEntityI
 verified against the `SubscribeToCourse` slice (`email` + `courseId` both `idAttribute: true`):
 
 ```java
-package io.axoniq.quickstart.slices.{context}.{slicename};
+package {basePackage}.slices.{context}.{slicename};
 
 public record {SliceName}Id(String field1, String field2) {}
 ```
 
 ```java
-package io.axoniq.quickstart.slices.{context}.{slicename};
+package {basePackage}.slices.{context}.{slicename};
 
 import org.axonframework.messaging.commandhandling.annotation.Command;
 import org.axonframework.modelling.annotation.TargetEntityId;
@@ -93,7 +99,7 @@ Check `src/main/java/.../{context}/events/` first; add to the existing sealed/ma
 than creating a duplicate.
 
 ```java
-package io.axoniq.quickstart.slices.{context}.events;
+package {basePackage}.slices.{context}.events;
 
 import org.axonframework.eventsourcing.annotation.EventTag;
 import org.axonframework.messaging.eventhandling.annotation.Event;
@@ -119,10 +125,10 @@ Package-private, mutable field(s) — **not** an immutable `State` record with f
 check needs, nothing else.
 
 ```java
-package io.axoniq.quickstart.slices.{context}.{slicename};
+package {basePackage}.slices.{context}.{slicename};
 
-import io.axoniq.quickstart.slices.{context}.events.{EventName};
-import io.axoniq.quickstart.slices.{context}.events.EventTags;
+import {basePackage}.slices.{context}.events.{EventName};
+import {basePackage}.slices.{context}.events.EventTags;
 import org.axonframework.eventsourcing.annotation.EventCriteriaBuilder;
 import org.axonframework.eventsourcing.annotation.EventSourcingHandler;
 import org.axonframework.eventsourcing.annotation.reflection.EntityCreator;
@@ -164,7 +170,7 @@ resolved automatically from `Configuration` — pass it plus the event class str
 tempting to think `andBeingOneOfTypes(new QualifiedName({EventName}.class))` should work without it,
 since `QualifiedName` has a `Class<?>` constructor. Verified experimentally that it does NOT:
 `QualifiedName(Class<?>)`'s only job is `clazz.getName()` — the raw Java class name
-(`io.axoniq.quickstart.slices.foo.events.CustomerRegistered`) — not the `@Event(namespace, name)` value
+(`{basePackage}.slices.foo.events.CustomerRegistered`) — not the `@Event(namespace, name)` value
 the event was actually appended under (`Foo.CustomerRegistered`). Swapping to it in
 `SubscribeToCourseDecisionModel` as a test made 2 of 3 passing tests fail immediately, silently, with
 no exception pointing at the real cause — the criteria just stopped matching anything, identical in
@@ -220,9 +226,9 @@ itself.
 ## Step 4: Command handler
 
 ```java
-package io.axoniq.quickstart.slices.{context}.{slicename};
+package {basePackage}.slices.{context}.{slicename};
 
-import io.axoniq.quickstart.slices.{context}.events.{EventName};
+import {basePackage}.slices.{context}.events.{EventName};
 import org.axonframework.messaging.commandhandling.annotation.CommandHandler;
 import org.axonframework.messaging.core.Metadata;
 import org.axonframework.messaging.eventhandling.gateway.EventAppender;
@@ -255,7 +261,7 @@ exist as a type in this version.
 ## Step 5: REST endpoint — only if slice.json shows an inbound `SCREEN` dependency on the command
 
 ```java
-package io.axoniq.quickstart.slices.{context}.{slicename};
+package {basePackage}.slices.{context}.{slicename};
 
 import org.axonframework.messaging.commandhandling.gateway.CommandGateway;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
@@ -323,9 +329,9 @@ One-time `pom.xml` addition (no version needed — resolved via the project's ex
 ```
 
 ```java
-package io.axoniq.quickstart.slices.{context}.{slicename};
+package {basePackage}.slices.{context}.{slicename};
 
-import io.axoniq.quickstart.slices.{context}.events.{EventName};
+import {basePackage}.slices.{context}.events.{EventName};
 import org.axonframework.eventsourcing.configuration.EventSourcedEntityModule;
 import org.axonframework.eventsourcing.configuration.EventSourcingConfigurer;
 import org.axonframework.messaging.commandhandling.configuration.CommandHandlingModule;

package/stacks/axon/templates/.claude/skills/build-state-change/references/rest-api-patterns.md

@@ -9,7 +9,7 @@ directly, and tests use `WebTestClient`, not `MockMvc`.
 ## Controller
 
 ```java
-package io.axoniq.quickstart.slices.{context}.{slicename};
+package {basePackage}.slices.{context}.{slicename};
 
 import org.axonframework.messaging.commandhandling.gateway.CommandGateway;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
@@ -59,7 +59,7 @@ shape for the first one, matching the project's WebFlux stack and the `@Conditio
 feature-flag convention (tests disable all slices by default; opt in per test class):
 
 ```java
-package io.axoniq.quickstart.slices.{context}.{slicename};
+package {basePackage}.slices.{context}.{slicename};
 
 import org.axonframework.messaging.commandhandling.gateway.CommandGateway;
 import org.junit.jupiter.api.Test;

package/stacks/axon/templates/.claude/skills/build-state-view/SKILL.md

@@ -21,6 +21,10 @@ description: >
 
 Before writing any code, read the target project's `.build-kit/CLAUDE.md`
 
+**Determine `{basePackage}`** — every code example below is rooted at
+`{basePackage}.slices.{context}.{slicename}`. Resolve `{basePackage}` as documented in
+`.build-kit/CLAUDE.md`'s Structure section.
+
 ## Step 1: Ensure Events Exist
 
 Before implementing the read slice, verify that all events the projector handles exist in the
@@ -70,7 +74,7 @@ comments** — those are only for write slices.
 ### Slice package structure
 
 ```
-de/<package>/{context}/slices/{slicename}/
+.../slices/{context}/{slicename}/     (i.e. {basePackage}.slices.{context}.{slicename} — see Step 0)
 ├── Get{SliceName}.java       ← query record + nested Result
 ├── {SliceName}Summary.java   ← read model (projection output shape)
 ├── {SliceName}Projector.java ← @Component with @EventHandler + @QueryHandler
@@ -252,7 +256,7 @@ Pure unit tests — instantiate the projector directly, no Spring context needed
 Fast, no container startup.
 
 ```java
-// File: src/test/java/de/<package>/{context}/slices/{slicename}/{SliceName}ProjectorTest.java
+// File: src/test/java/.../slices/{context}/{slicename}/{SliceName}ProjectorTest.java
 class {SliceName}ProjectorTest {
 
     private {SliceName}Projector projector;

package/stacks/axon/templates/build-kit/CLAUDE.md

@@ -2,6 +2,13 @@
 
 Read Events in src/events to understand the global structure.
 
+`<basePackage>` in this project's Java code (`src/main/java/<basePackage>/slices/...`) is this
+project's own Java package prefix, not a fixed value — resolve it, in order: (1) the package of the
+project's `@SpringBootApplication` class, (2) the package of any existing slice already under
+`.../slices/{context}/{slicename}/`, (3) only if no code exists yet, Maven's `<groupId>` in `pom.xml`
+or Gradle's `group` property in `build.gradle`/`build.gradle.kts`. Never hardcode
+`io.axoniq.quickstart` (the shipped quickstart scaffold's package) or any other specific package.
+
 ## File Structure Constraints
 
 - **Strict Path Limitation**: if not instructed otherwise, only check `src/slices/{slicename}/*.ts`

package/stacks/modeling-kit/templates/.claude/skills/html-screen/SKILL.md

@@ -68,12 +68,14 @@ Guidelines:
 
 ### Marks — only when the user explicitly asks for one
 
-The canvas has a native "Marks" feature (outline highlight, optional blur-outside spotlight) for calling out part of a screen. **Do not add marks by default.** Only apply one of the two effects below when the request explicitly asks to highlight/mark/call out/circle/spotlight or blur/obscure part of the screen (e.g. "highlight the submit button", "blur everything except the email field"). An ordinary "design a screen" request gets no marks.
+The canvas has a native "Marks" feature (outline highlight, plus an optional "blur outside" or "white outside" spotlight) for calling out part of a screen — see `HtmlEditorModal.tsx`'s Highlight tool and `markBlur.ts`/`markStyles.ts` in the main app. **Do not add marks by default.** Only apply the effects below when the request explicitly asks to highlight/mark/call out/circle/spotlight, or blur/obscure/white-out part of the screen (e.g. "highlight the submit button", "blur everything except the email field", "white out everything but the header"). An ordinary "design a screen" request gets no marks.
 
-Since this skill only has a `pages`/`backgroundColor` field to send (no separate marks API), reproduce the same visual language directly as inline CSS on the target element(s) — self-contained in the page HTML, same as any other styling in Step 3:
+This skill only has a `pages`/`backgroundColor` field to send (no separate marks API — the native feature persists marks as board metadata, not through this render call), so reproduce the same visual language directly as inline CSS on the target element(s), self-contained in the page HTML same as any other styling in Step 3. No `<script>`/`<style>` tags are needed (and `<script>` is stripped anyway) — inline `style="..."` reproduces the same CSS the native feature injects:
 
-- **Mark / highlight an area** — add to the target element's `style`: `outline:4px solid <color> !important;outline-offset:1px;`. Default color `#e74c3c` (red) unless the user names one; other options mirror the app's mark picker: `#1e293b` (dark slate), `#2ecc71` (green), `#3b82f6` (blue), `#f1c40f` (yellow), `#ffffff` (white).
-- **Blur outside / spotlight an area** — add `style="filter:blur(6px) !important;"` to every other top-level sibling/section on the page so only the called-out element stays sharp. Combine with the outline above if the user asked to both mark and blur.
+- **Mark / highlight an area** — add to the target element's `style`: `outline:4px solid <color> !important;outline-offset:1px;`. Default color `#e74c3c` (red) unless the user names one; other options mirror the app's mark picker (`ColorPicker.tsx`): `#1e293b` (dark slate), `#2ecc71` (green), `#3b82f6` (blue), `#f1c40f` (yellow), `#ffffff` (white).
+- **Blur outside / spotlight an area** — add `style="filter:blur(6px) !important;"` to every other top-level sibling/section on the page so only the called-out element stays sharp.
+- **White outside / spotlight an area** — same idea, but instead add `style="filter:brightness(0) invert(1) !important;"` to every other top-level sibling/section (collapses them to solid white — works uniformly across text, shapes, and images, unlike a plain background-color override). Use this only when the user says "white out" / "whiteout" rather than "blur" — the two are mutually exclusive per mark in the native tool, so never apply both blur and white filters to the same sibling.
+- Combine the outline rule with either spotlight rule if the user asked to both mark *and* blur/white-out.
 
 Apply these only to the specific element(s) the request describes — don't guess at additional areas to call out.