@eventmodelers/cli 1.0.36 → 1.0.38

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-validating-event-models-checklist/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: eventmodeling-validating-event-models-checklist
-description: "Validate event-sourced CQRS models against 17 architectural checks across 7 phases. Identifies anti-patterns and confirms compliance with event sourcing principles. Use when reviewing event models for production readiness or after completing event modeling steps. Do not use for: reviewing incomplete or in-progress models (use eventmodeling-validating-event-models), or for elaborating new scenarios (use eventmodeling-elaborating-scenarios)."
+description: "Validate an event model against 12 structural checks across 6 phases. Identifies notation anti-patterns and confirms the model is internally consistent. Use when reviewing an event model for readiness or after completing event modeling steps. Do not use for: reviewing incomplete or in-progress models (use eventmodeling-validating-event-models), or for elaborating new scenarios (use eventmodeling-elaborating-scenarios)."
 allowed-tools:
   - Write
   - Bash
@@ -10,25 +10,26 @@ allowed-tools:
 
 > **Before doing anything else**, invoke the `connect` skill — if not already connected — to resolve `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL`. Do not proceed until it has completed. Consult `learn-eventmodelers-api` only if you need to look up a specific endpoint or field this file doesn't cover — don't load it eagerly.
 
+This step applies the shared element rules in **`eventmodeling-core-rules`** — read it once per session if you haven't already; it defines what a COMMAND/EVENT/READMODEL/SCREEN/AUTOMATION is, how each is named, and the anti-patterns to reject, so this step doesn't restate them.
+
 Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected.
 
-**Purpose**: Validate any event-sourced CQRS event model against 17 architectural checks across 7 phases. Identifies anti-patterns and confirms compliance with event sourcing principles.
+**Purpose**: Validate any event model against 12 structural checks across 6 phases. Identifies notation anti-patterns and confirms the model is internally consistent.
 
 **Applies To**: Any domain - e-commerce, banking, SaaS, marketplace, healthcare, etc.
 
 **When to Use**:
-- After completing Step 2 (Event Plot) of the 11-step event modeling workflow, as an early structural check
-- Alongside Step 9 (Validate), as the optional production-readiness pass before declaring model complete
-- When reviewing an existing event model for production readiness
-- When suspicious of architectural issues in event design
+- After completing Step 2 (Event Plot) of the event modeling workflow, as an early structural check
+- Alongside Step 9 (Validate), as an optional second pass before declaring the model complete
+- When reviewing an existing event model
+- When suspicious of structural issues in the model
 
 **What It Does**:
 1. Reads current board state (EVENT, COMMAND, READMODEL nodes) as input
-2. Systematically applies 17 validation checks across 7 phases
-2. Identifies violations of event sourcing principles (domain-agnostic)
-3. Flags anti-patterns (calculations as events, non-entity streams, etc.)
+2. Systematically applies 12 validation checks across 6 phases
+3. Identifies notation anti-patterns (calculations modeled as events, events mixed into the wrong entity's timeline, etc.)
 4. Verifies read model/event distinction
-5. Confirms stream independence and business rule enforcement
+5. Confirms every event and command traces cleanly
 6. Returns pass/fail verdict with evidence
 
 ---
@@ -45,66 +46,53 @@ mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "COMMAND" }
 mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "READMODEL" }
 ```
 
-**Fallback (no MCP):**
-```bash
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=EVENT"
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=COMMAND"
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=READMODEL"
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Board Context".
+
+Also run `validate_model` (`{boardId, chapterId}`) once per chapter up front — several checklist items (Command With Multiple Issuers in Phase 1, backward-arrow / event-flow in Phase 6, read-model-source distinctions in Phase 3) have a purely structural half the tool answers directly, so start each of those from its `findings` and spend the manual effort on the semantic judgement the tool can't make.
 
 Use the board nodes as the model input. After the checklist, use `handle-comment` to post `TASK` comments on nodes that fail checks (that skill covers the MCP `add_comment`/curl choice for comment-posting itself).
 
 ## Validation Phases (Domain-Agnostic)
 
-### Phase 1: Event Stream & Command Handler State Validation (4 checks)
-- Check 1.1: Each event belongs to exactly one stream
-- Check 1.2: Each command handler owns its own [CommandHandler]State class
-- Check 1.3: No hard dependencies between command handlers (orchestrated via events only)
-- Check 1.4: Each command is issued by exactly one thing — no COMMAND node has more than one inbound SCREEN/AUTOMATION edge
+### Phase 1: Event & Command Ownership Validation (2 checks)
+- Check 1.1: Each event belongs to exactly one entity/timeline
+- Check 1.2: Each command is issued by exactly one thing — no COMMAND node has more than one inbound SCREEN/AUTOMATION edge
 
-**Anti-pattern to catch**: Sharing state across handlers or treating state as persistent aggregate; a command wired from two issuers — auto-connect itself now guards against this (see `learn-eventmodelers-api` §3), so a double-issuer command found on the board is most likely a manual `set_connection` call or an edge left over from before that guard existed, not a fresh auto-connect artifact
+**Anti-pattern to catch**: a command wired from two issuers — auto-connect itself now guards against this (see `learn-eventmodelers-api` §3), so a double-issuer command found on the board is most likely a manual `set_connection` call or an edge left over from before that guard existed, not a fresh auto-connect artifact
 
 ### Phase 2: Event Quality Validation (3 checks)
 - Check 2.1: Events represent domain facts, not calculations
 - Check 2.2: Event data is immutable after creation
 - Check 2.3: Event names use past tense (what actually happened)
 
-**Anti-pattern to catch**: Storing computed/aggregated data as events
+**Anti-pattern to catch**: storing computed/aggregated data as an event
 
 ### Phase 3: Read Model vs Event Distinction (2 checks)
-- Check 3.1: Each read model is NOT an event stream
-- Check 3.2: Read model has natural query pattern
+- Check 3.1: Each read model is NOT an event timeline
+- Check 3.2: Read model has a natural query pattern
 
-**Anti-pattern to catch**: Confusing projections/calculations with domain facts
+**Anti-pattern to catch**: confusing projections/calculations with domain facts
 
 ### Phase 4: Business Rules Validation (2 checks)
-- Check 4.1: Constraints enforced in command handler decision logic (encapsulated in [CommandHandler]State)
-- Check 4.2: Event preconditions are explicit (what state must exist before command is valid)
+- Check 4.1: Every command's preconditions are documented explicitly
+- Check 4.2: Event preconditions are explicit (what must already be true before a command is valid)
 
-**Anti-pattern to catch**: Business rules scattered across handlers or encoded in event stream structure
+**Anti-pattern to catch**: business rules scattered across the model or left implicit ("obviously can't ship an unconfirmed order")
 
 ### Phase 5: Data Traceability (1 check)
 - Check 5.1: Input → Event → Read Model traceability is complete
 
-**Anti-pattern to catch**: Command inputs that disappear or read model fields without source
-
-### Phase 6: Event Flow Validation (1 check)
-- Check 6.1: No impossible event sequences (state machine is sound)
+**Anti-pattern to catch**: command inputs that disappear, or read model fields without a source
 
-**Anti-pattern to catch**: Events that can occur in invalid state combinations
+### Phase 6: Event Flow Validation (2 checks)
+- Check 6.1: No impossible event sequences (the slice-transition flow is sound)
+- Check 6.2: No event belongs to more than one entity's timeline — an event that seems to span two entities usually means a naming or boundary mistake, not a shared fact
 
-### Phase 7: Stream Independence (1 check)
-- Check 7.1: Each stream can be versioned/restored independently
+**Anti-pattern to catch**: events that can occur in invalid combinations; a "shared" event quietly coupling two entities together
 
-**Anti-pattern to catch**: Hard dependencies between streams
-
-### Final Questions (3 checks)
-- Question 1: Could an architect unfamiliar with this domain understand the model in 15 minutes?
-- Question 2: Could you change your core algorithm/calculation without changing event history?
-- Question 3: Could this be implemented in your target technology stack (e.g., TypeScript + PostgreSQL)?
+### Final Questions (2 checks)
+- Question 1: Could a modeler unfamiliar with this domain understand the model in 15 minutes?
+- Question 2: Could the business rule/calculation behind a read model change without rewriting event history?
 
 ---
 
@@ -114,7 +102,7 @@ The skill returns a validation report with:
 
 ### For Each Check
 ```
- Check 1.2: Stream Root is Business Entity, Not Calculation
+ Check 1.2: Command Issued by Exactly One Thing
 Status: PASS
 Evidence: [Specific examples from your model]
 ```
@@ -122,7 +110,7 @@ Evidence: [Specific examples from your model]
 ### Anti-Patterns Identified (if any)
 ```
 CRITICAL: [Anti-pattern description]
-Problem: [Why it violates event sourcing]
+Problem: [Why it violates event modeling principles]
 Violates: [Which checks fail]
 Fix: [Recommended action]
 ```
@@ -130,7 +118,6 @@ Fix: [Recommended action]
 ### Final Verdict
 ```
 Status:  PASS (or  PASS WITH WARNINGS or  FAIL)
-Implementation Ready: YES (or NO - fix issues first)
 Confidence: [percentage]
 ```
 
@@ -151,124 +138,65 @@ CalculationPerformed {
 - ReadModel: MetricView (recalculated from events)
 ```
 
-**Why**: Calculations change multiple times as source data changes. Events are immutable.
+**Why**: Calculations change as source data changes. Events are immutable.
 
-### 2. Shared vs Handler-Owned State
-```
- ANTI-PATTERN:
-One shared "OrderAggregate" class used by all handlers
-- ConfirmOrderHandler shares OrderAggregate state
-- ShipOrderHandler modifies same OrderAggregate
-- Result: Tight coupling, hard to parallelize
+### 2. Command With Multiple Issuers
 
- CORRECT:
-Each handler owns its own [CommandHandler]State class
-- ConfirmOrderState (only ConfirmOrderHandler uses)
-- ShipOrderState (only ShipOrderHandler uses)
-- CancelOrderState (only CancelOrderHandler uses)
-- All reconstruct state from same events, but independently
-```
+A command is never issued by more than one thing — a COMMAND with 2+ inbound SCREEN/AUTOMATION edges hides which actor is actually responsible. See `place-element`'s Step 7c for the full check-and-fix mechanics (which edge to keep, how to remove the rest).
 
-**Why**: Each handler is a micro-slice. Separate state classes maintain isolation, enable parallel teams, prevent merge conflicts.
+**Why**: Each command represents one specific trigger's decision to act — collapsing two triggers onto one command node usually means either a naming/slice-boundary mistake or a stray manual/pre-existing edge (auto-connect itself now guards against fresh occurrences — see `learn-eventmodelers-api` §3).
 
-### 3. Circular Dependencies
+### 3. An Event Shared Across Entities
 ```
  ANTI-PATTERN:
-StreamA → EventA → affects
-StreamB → EventB → affects
-StreamA (circular!)
+EntityA → EventA → also placed on EntityB's timeline
 
  CORRECT:
-StreamA → EventA → Event Bus
-StreamB → EventB → Event Bus
-ReadModels ← consume (one-way only)
-No feedback loops
+EntityA → EventA (on EntityA's timeline only)
+EntityB reacts to EventA via a read model/automation, it doesn't own it
 ```
 
-**Why**: Circular dependencies make the system hard to reason about and test.
-
-### 4. Persistent State vs Ephemeral State
-```
- ANTI-PATTERN:
-Treat [CommandHandler]State as persistent entity
-- Save SubmitReviewState to database after command
-- Load it again next time
-- Result: Duplicates event sourcing, loses audit trail
-
- CORRECT:
-Reconstruct [CommandHandler]State on-demand
-- Load events from stream
-- Replay via evolve() to rebuild state
-- Process command, emit outcome events
-- Discard state (it's ephemeral, not persisted)
-```
-
-**Why**: State is derived from events, never stored. Events are source of truth. This enables consistent replay, audit trails, and time-travel debugging.
-
-### 5. Command With Multiple Issuers
-```
- ANTI-PATTERN:
-FlagLoanOverdue (COMMAND) has two inbound edges:
-- "Flag Overdue Loans" (AUTOMATION, same column)
-- "Adjust Due Date" (SCREEN, previous column)
-- Result: unclear who/what actually triggers the command; validation and UI-vs-automation
-  authority checks (e.g. Role & Actor Attribution) can no longer be answered
-
- CORRECT:
-FlagLoanOverdue (COMMAND) has exactly one inbound edge, from the AUTOMATION that owns it.
-If the SCREEN's user genuinely needs to trigger the same outcome, that's a second,
-distinctly-named command (or the SCREEN issuing it directly, with the automation removed) —
-not two issuers sharing one command.
-```
-
-**Why**: A command is never issued by more than one thing. Each command represents one specific trigger's decision to act — collapsing two triggers onto one command node hides which actor is actually responsible, and usually means either a naming/slice-boundary mistake or a stray manual/pre-existing edge (auto-connect itself now guards against this — see `learn-eventmodelers-api` §3). Fix by removing the extra edge via `set_connection` (`action: "remove"`), not by keeping both.
+**Why**: An event belongs to the story of exactly one entity. If a second entity needs to react to it, that's a read model or automation reading it — not the same event living on two timelines.
 
 ---
 
 ## Questions to Ask During Validation
 
-**For each event stream**:
-1. "Do all events in this stream share the same identity (streamId)?"
-2. "Could these events occur in any order, or is sequence important?"
-3. "Is every event in this stream an immutable fact that actually happened?"
+**For each entity's timeline**:
+1. "Do all events on this timeline belong to the same entity?"
+2. "Could these events occur in any order, or does sequence matter?"
+3. "Is every event on this timeline an immutable fact that actually happened?"
 
-**For each command handler**:
-1. "Does this handler own its own [CommandHandler]State class?"
-2. "Is the state ephemeral (reconstructed per command, not persisted)?"
-3. "Can I trace the state reconstruction: events → evolve() → decision?"
+**For each command**:
+1. "Are its preconditions written down, not just assumed?"
+2. "Does it produce an event, or document why it's rejected?"
 
 **For each read model**:
 1. "Is this calculated from events via a projection?"
 2. "Does it answer a specific query need?"
-3. "Could its data change due to new events or state changes?"
-
-**For system architecture**:
-1. "Does each command handler operate independently (communicate via events only)?"
-2. "Could I run two handlers' code in parallel without merge conflicts?"
-3. "Are the only shared artifacts the event definitions?"
+3. "Could its data change due to new events?"
 
 ---
 
 ## Success Criteria
 
  **Model is validated when**:
-- All 17 checks pass (or have documented workarounds)
+- All 12 checks pass (or have documented workarounds)
 - No critical anti-patterns identified
-- All 3 final questions answer YES
-- Event sourcing principles clearly upheld
-- Ready to proceed to code generation
+- Both final questions answer YES
+- Event modeling principles are clearly upheld
 
  **Model needs fixes when**:
 - Any check fails with clear evidence
 - Anti-patterns identified with specific violations
-- Final questions have NO answers
+- A final question has a NO answer
 - Fixes are straightforward and targeted
 
  **Model should be redesigned when**:
 - Multiple phases fail
-- Architectural assumptions are fundamentally flawed
+- Structural assumptions are fundamentally flawed
 - Anti-patterns are systemic and pervasive
-- Would require rewriting core event structure
+- Would require rewriting the core event timeline
 
 ---
 
@@ -278,25 +206,13 @@ not two issuers sharing one command.
 When you see something like "CalculationDone" or "ReviewRatingUpdated":
 - Ask: "Is this immutable and caused by a user/system action?"
 - If NO → It's a read model, not an event
-- Fix: Remove from events, create read model projection instead
-
-### Pattern: Shared vs Isolated State
-When you see "ReviewAggregate" used by multiple handlers:
-- Ask: "Could SubmitReviewHandler and ApproveReviewHandler work on separate files?"
-- If NO → State classes aren't properly isolated
-- Fix: Create SubmitReviewState and ApproveReviewState, each handler owns one
-
-### Pattern: Persistent vs Ephemeral State
-When state is saved to database after a command:
-- Ask: "Is this state only needed during command processing?"
-- If YES → It's ephemeral, reconstruct from events instead
-- Fix: Load events, replay via evolve(), process command, discard state
+- Fix: Remove from events, create a read model projection instead
 
 ### Pattern: Data That Doesn't Trace
 When a read model field appears without source:
 - Ask: "Where did this come from?"
-- If no event source → Add event or remove field
-- If sourced from calculation → Verify it's in projection, not event
+- If no event source → Add the event or remove the field
+- If sourced from a calculation → Verify it's in the read model, not the event
 
 ---
 
@@ -315,19 +231,19 @@ Step 3-8: Storyboard, Inputs, Outputs, Conway's Law, Scenarios, Completeness
   ↓
 Step 9: Validate (eventmodeling-validating-event-models)
   ↓
-→ RUN eventmodeling-validating-event-models-checklist again (production-readiness pass)
+→ RUN eventmodeling-validating-event-models-checklist again (final structural pass)
   ↓
-PASS → Step 10: Slice, Step 11: Document Reasoning → Code generation
+PASS → Step 10: Slice, Step 11: Document Reasoning
 FAIL → Fix identified issues
 ```
 
-Running the checklist after Step 2 prevents wasting time on later steps if core events are flawed.
+Running the checklist after Step 2 prevents wasting time on later steps if the core events are flawed.
 
 ---
 
 ## Checklist Questions by Domain
 
-The skill applies the same 17 checks regardless of domain. Here's how to think about it in different contexts:
+The skill applies the same 12 checks regardless of domain. Here's how to think about it in different contexts:
 
 **E-commerce domain**:
 - Events: OrderCreated, OrderConfirmed, PaymentAuthorized, OrderShipped
@@ -351,26 +267,26 @@ The principle is the same across all domains: **immutable facts as events, calcu
 
 ## Tips for Best Results
 
-1. **Be specific**: List actual event names, command handler names, and state classes from your model
-2. **Reference your documentation**: Link to or quote from your step 1-7 documents and micro-slice plans
-3. **Provide context**: Explain what your domain is and how handlers will be parallelized
-4. **Ask follow-ups**: If a check flags an issue, ask "How do I fix this specifically?" or "Can this handler be isolated?"
-5. **Iterate**: Run again after making fixes to confirm all checks pass and handlers are properly isolated
+1. **Be specific**: List actual event and command names from your model
+2. **Reference your documentation**: Link to or quote from your step 1-7 documents
+3. **Provide context**: Explain what your domain is
+4. **Ask follow-ups**: If a check flags an issue, ask "How do I fix this specifically?"
+5. **Iterate**: Run again after making fixes to confirm all checks pass
 
 ## Quality Checklist
 
-- [ ] All 17 checks evaluated — no check skipped without documented justification
-- [ ] Every FAIL result includes the specific event, handler, or stream that violated the check
+- [ ] All 12 checks evaluated — no check skipped without documented justification
+- [ ] Every FAIL result includes the specific event, command, or entity that violated the check
 - [ ] Anti-patterns identified by name with the exact model element that triggered the flag
 - [ ] Final verdict is one of: PASS / PASS WITH WARNINGS / FAIL — no ambiguous outcomes
-- [ ] All 3 final architectural questions answered YES before declaring model ready for implementation
+- [ ] Both final questions answered YES before declaring the model ready
 - [ ] Any FAIL result has a recommended fix, not just a problem statement
 
 ---
 
 ## Related Skills
 
-- **eventmodeling-orchestrating-event-modeling**: Main skill coordinating the 11-step event modeling process
+- **eventmodeling-orchestrating-event-modeling**: Main skill coordinating the full event modeling process
 - **eventmodeling-brainstorming-events**: Extract events from requirements (Step 1)
 - **eventmodeling-plotting-events**: Sequence events chronologically (Step 2)
 - **eventmodeling-designing-event-models**: Design your complete event model
@@ -380,6 +296,5 @@ The principle is the same across all domains: **immutable facts as events, calcu
 
 ## Validation Checklist Reference
 
-The 17-point checklist is defined in the **Validation Phases** section above.
+The 12-point checklist is defined in the **Validation Phases** section above.
 Each check includes the anti-pattern to catch and questions to ask when evaluating your model.
-

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-validating-event-models-checklist/references/api-fallback.md

@@ -0,0 +1,14 @@
+# Event Model Validation Checklist Skill — curl Fallback Calls
+
+Only needed when MCP is not connected. Every call below has an MCP equivalent in the main SKILL.md — always prefer that.
+
+## Board Context
+
+```bash
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=EVENT"
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=COMMAND"
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=READMODEL"
+```

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

@@ -45,93 +45,11 @@ mcp__eventmodelers__add_field_examples { "boardId": "$BOARD_ID", "cellName": "<t
 
 If this succeeds, skip straight to Step 6 (report back), describing the fields the tool reports as changed. Use the manual fallback flow below (Steps 2–5) only if MCP isn't connected.
 
-### Fallback (no MCP) — Step 2: Resolve the element
-
-Try the resolution strategies in order until one succeeds.
-
-### 2a — UUID
-If `target` looks like a UUID (pattern `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`), fetch it directly:
-
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$target" \
-  -H "x-user-id: examples-skill"
-```
-
-### 2b — Name search
-If `target` is not a UUID, search by name:
-
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/events/search?name=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' "$target")" \
-  -H "x-user-id: examples-skill"
-```
-
-Pick the best match (exact title match preferred; case-insensitive). If multiple matches exist, list them and ask the user to pick one.
-
-### 2c — Cell name (spreadsheet-style, e.g. "B3")
-If `target` matches the pattern `[A-Z]+[0-9]+`:
-
-1. Fetch all chapters on the board to find the relevant timeline:
-
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER" \
-  -H "x-user-id: examples-skill"
-```
-
-If multiple chapters exist, ask the user which one to use.
-
-2. Fetch the chapter **fresh** to decode the grid — never use cached chapter data, as cells are updated frequently:
-
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$CHAPTER_ID" \
-  -H "x-user-id: examples-skill"
-```
-
-From `meta.timelineData`, decode the cell name into a `cellId`:
-- Column letter(s) → 0-based column index (A=0, B=1, … Z=25, AA=26, …)
-- Row digit → 0-based row index (1→0, 2→1, …)
-- Find the matching column in `columns` and the matching row in `rows`.
-- Compute: **`CELL_ID = row.id + "-" + column.id`** (cell IDs are always `<rowId>-<columnId>`).
-
-3. **Always fetch the cell live** to get the current node list — do not rely on the `nodeId` in the chapter's cell data, as it may be stale. No MCP equivalent: `get_nodes` only filters by `type`, not `cellId`:
-
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?cellId=$CELL_ID" \
-  -H "x-user-id: examples-skill"
-```
-
-Use the first non-CHAPTER result (filter out CHAPTER type).
-
-If no element is found after all strategies, stop and tell the user what was tried.
-
-Save the resolved node as `TARGET_NODE` (full JSON including `id`, `meta`, `edges`).
+**Fallback (no MCP):** see `references/api-fallback.md` — "Step 2 — Resolve the element".
 
 ---
 
-### Fallback (no MCP) — Step 3: Load linked elements for context
-
-Collect nearby elements to understand the domain context and generate consistent examples. **Never fetch all board nodes.** Only fetch specific nodes you already have IDs for.
-
-### 3a — Nodes from edges
-If `TARGET_NODE.edges` is non-empty, fetch each connected node individually by its ID:
-
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/<EDGE_NODE_ID>" \
-  -H "x-user-id: examples-skill"
-```
-
-Fetch all edge-connected nodes in parallel (one request per node ID).
-
-### 3b — Nodes from the same column (cell-based resolution only)
-If you resolved `TARGET_NODE` via a cell name (Step 2c), you already have the full chapter `cells` array in memory. Use it — **no extra API call needed**:
-
-- Find all cells that share the same `colId` as `TARGET_NODE`'s cell.
-- Collect their `nodeId` values (skip the target itself and any cell without a `nodeId`).
-- Fetch each of those nodes individually by ID (in parallel):
-
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/<NODE_ID>" \
-  -H "x-user-id: examples-skill"
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Step 3 — Load linked elements for context".
 
 ### 3c — Read neighbour fields
 For each neighbour element collected above (COMMAND, EVENT, READMODEL), extract its `meta.fields` and their existing `example` values. This gives you a pool of consistent values to reuse — e.g. if a COMMAND already has `email: "jane@example.com"`, use the same email in the linked EVENT.
@@ -183,32 +101,7 @@ mcp__eventmodelers__submit_node_events {
 }
 ```
 
-**Fallback (no MCP at all)** — build the payload with Python to avoid shell JSON-escaping issues, then POST it:
-
-```bash
-python3 - <<EOF > /tmp/examples_payload.json
-import json, time, uuid
-payload = [{
-  "id": str(uuid.uuid4()),
-  "eventType": "node:changed",
-  "nodeId": "<TARGET_NODE.id>",
-  "boardId": "<BOARD_ID>",
-  "timestamp": int(time.time() * 1000),
-  "changedAttributes": ["meta.fields"],
-  "meta": {
-    "fields": <updated-fields-array as Python list>
-  }
-}]
-print(json.dumps(payload))
-EOF
-
-curl -s -w "\n%{http_code}" -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
-  -H "Content-Type: application/json" \
-  -H "x-token: $TOKEN" \
-  -H "x-board-id: $BOARD_ID" \
-  -H "x-user-id: examples-skill" \
-  --data-binary @/tmp/examples_payload.json
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Step 5 — Write the update".
 
 Verify the response is HTTP 200. If it fails, report the error and stop.