@eventmodelers/cli 1.0.36 → 1.0.38

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-identifying-outputs/references/api-fallback.md

@@ -0,0 +1,67 @@
+# Identifying Outputs — 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.
+
+## Step 5f — Placing a READMODEL node (full manual sequence)
+
+1. Find the column where the consumer SCREEN or AUTOMATION lives. For an AUTOMATION, the read model's target column is always the one immediately **before** it (skip straight to inserting that column — its interaction row is guaranteed occupied by the automation's own COMMAND). For a SCREEN, target the screen's own column. Fetch the timeline to get the interaction row ID:
+   ```bash
+   curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+     "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$CHAPTER_ID"
+   # → timelineData.rows — find the row where type === "interaction"
+   ```
+2. Check if the target interaction cell is already occupied (existing COMMAND):
+   ```bash
+   curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?cellId=<interactionRowId>-<columnId>" \
+     -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID"
+   ```
+   If a COMMAND occupies that cell, insert a new column immediately **before** it (`{"index": currentIndex}` — this shifts the consumer's column, and everything after it, one to the right) and use that new column's ID instead. The read model must end up upstream of (to the left of) its consumer, never downstream of it.
+3. `cellId = interactionRow.id + "-" + columnId`
+4. Create the READMODEL:
+   ```bash
+   curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
+     -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: identifying-outputs" \
+     -H "Content-Type: application/json" \
+     -d '[{
+       "id": "<event-uuid>",
+       "eventType": "node:created",
+       "nodeId": "<node-uuid>",
+       "boardId": "<BOARD_ID>",
+       "timestamp": 1234567890,
+       "chapterId": "<CHAPTER_ID>",
+       "cellId": "<interactionRowId>-<columnId>",
+       "meta": {"type": "READMODEL", "title": "ActiveReservationView", "fields": [...]}
+     }]'
+   ```
+
+## Step 5h.1 — Wire EVENT → READMODEL
+
+```bash
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?cellId=<swimlaneRowId>-<columnId>" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: eventmodeling-identifying-outputs"
+```
+Connect it:
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/connections" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: eventmodeling-identifying-outputs" \
+  -H "Content-Type: application/json" \
+  -d '{"source":"<eventNodeId>","target":"<readmodelNodeId>"}'
+```
+
+## Step 5h.2 — Wire READMODEL → SCREEN
+
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/connections" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: eventmodeling-identifying-outputs" \
+  -H "Content-Type: application/json" \
+  -d '{"source":"<readmodelNodeId>","target":"<screenNodeId>"}'
+```
+
+## Step 5h.3 — Wire READMODEL → AUTOMATION
+
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/connections" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: eventmodeling-identifying-outputs" \
+  -H "Content-Type: application/json" \
+  -d '{"source":"<readmodelNodeId>","target":"<automationNodeId>"}'
+```

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-identifying-outputs/references/examples.md

@@ -0,0 +1,273 @@
+# Identifying Outputs — Worked Examples
+
+These are conceptual worked examples of the read-model design thinking this step applies — useful for understanding the reasoning, but the actual mechanics live in the numbered Step 5a–5i sections of the main SKILL.md (placing nodes on the board via the API), not in writing a document like this.
+
+## Conceptual walkthrough — mapping events to a read model (Order domain)
+
+### 1. Map Event Data to UI Screens
+
+```
+Screen: Order Status View
+Displays data from events:
+  orderId ← OrderCreated event
+  customerId ← OrderCreated event
+  items ← OrderCreated event
+  total ← OrderCreated event
+  status ← OrderConfirmed event (or OrderCancelled)
+  confirmedAt ← OrderConfirmed event
+  paymentId ← PaymentAuthorized event
+  shipmentId ← OrderShipped event
+  shippedAt ← OrderShipped event
+
+This screen is a projection of these events:
+  - OrderCreated
+  - OrderConfirmed
+  - PaymentAuthorized
+  - OrderShipped
+```
+
+### 2. Define Read Models
+
+```
+ReadModel: OrderStatusView
+Purpose: UI displays current order status
+Events subscribed: OrderCreated, OrderConfirmed, PaymentAuthorized, OrderShipped, OrderCancelled
+Data:
+{
+  orderId: string (from OrderCreated)
+  customerId: string (from OrderCreated)
+  status: enum (from events: Draft → Confirmed → Authorized → Shipped → Delivered)
+  createdAt: Date (from OrderCreated)
+  confirmedAt: Date (from OrderConfirmed)
+  paymentId: string (from PaymentAuthorized)
+  shipmentId: string (from OrderShipped)
+  shippedAt: Date (from OrderShipped)
+}
+```
+
+### 3. Document Event → Data Mapping
+
+```
+Event: OrderCreated
+Provides to UI/Processors:
+  orderId
+  customerId
+  items[]
+  total
+  shippingAddress
+  createdAt
+
+Event: OrderConfirmed
+Provides to UI/Processors:
+  orderId (link to stream)
+  paymentMethod (user selected method)
+  confirmedAt (timestamp)
+  paymentId (payment system reference)
+
+Event: PaymentAuthorized
+Provides to UI/Processors:
+  orderId (link to stream)
+  paymentId
+  authCode
+  authorizedAt (timestamp)
+  amount (verified amount)
+
+Event: OrderShipped
+Provides to UI/Processors:
+  orderId (link to stream)
+  shipmentId
+  shippedAt (timestamp)
+  carrier (shipping company)
+  trackingNumber (for delivery tracking)
+```
+
+### 4. Create Output Catalog
+
+```
+ReadModel Catalog: Order System
+
+1. OrderStatusReadModel
+   Purpose: UI shows current order status
+   Events: OrderCreated, OrderConfirmed, PaymentAuthorized, OrderShipped, OrderCancelled
+   Data: orderId, status, createdAt, confirmedAt, paymentId, shipmentId
+   Consumed by:
+     - Order Status screen (UI)
+     - Customer Dashboard (UI)
+     - Order Processing Processor (decides if can ship)
+
+2. OrderListReadModel
+   Purpose: UI lists all orders for a customer
+   Events: OrderCreated, OrderConfirmed, OrderCancelled
+   Data: orderId, customerId, total, status, createdAt
+   Consumed by:
+     - Customer Order History (UI)
+     - Order Search/Filter (UI)
+
+3. PaymentStatusReadModel
+   Purpose: UI shows payment status
+   Events: OrderConfirmed, PaymentAuthorized, PaymentFailed
+   Data: orderId, paymentId, status, authCode, failureReason, timestamp
+   Consumed by:
+     - Payment Status screen (UI)
+     - Accounting Processor (reconciliation)
+
+4. ShipmentTrackingReadModel
+   Purpose: UI shows tracking information
+   Events: OrderShipped, DeliveryConfirmed
+   Data: orderId, shipmentId, trackingNumber, carrier, shippedAt, estimatedDelivery
+   Consumed by:
+     - Order Tracking screen (UI)
+     - Customer notifications (Processor)
+```
+
+### 5. Identify Missing Data
+
+```
+Question: What if UI needs "estimated delivery date"?
+Event: OrderShipped has carrier + trackingNumber
+Action needed: Add estimatedDelivery to OrderShipped event
+  (or compute from carrier info)
+
+Question: What if UI needs to show "payment method" on status?
+Event: OrderConfirmed has paymentMethod
+Action needed: Include paymentMethod in relevant read models
+
+Question: What if UI needs "item descriptions"?
+Event: OrderCreated has items[]
+But: items[] only has productId
+Action needed: Enrich with product descriptions from catalog
+  (via join with product service)
+```
+
+### 6. Processor Outputs
+
+```
+Processor: Inventory System
+Consumes from read models:
+  - Orders in "PaymentAuthorized" status
+  - Items and quantities needed
+Produces commands:
+  - ReserveInventory
+
+Processor: Fulfillment System
+Consumes from read models:
+  - Orders in "InventoryReserved" status
+  - Items and quantities
+  - Shipping address
+Produces commands:
+  - CreateShipment
+
+Processor: Notification System
+Consumes from read models:
+  - OrderCreated (sends confirmation)
+  - OrderConfirmed (sends receipt)
+  - OrderShipped (sends tracking)
+  - DeliveryConfirmed (sends thank you)
+Does not produce commands (info-only)
+```
+
+## Legacy markdown-document format (superseded — kept for reference only)
+
+Older versions of this skill wrote the read model catalog as a markdown document instead of placing nodes on the board. The actual mechanism today is the board API (Step 5a–5i in the main SKILL.md) — this template is kept only so the shape of the information (what a complete read-model catalog covers) stays documented somewhere.
+
+```markdown
+# Outputs: [Domain Name]
+
+## Read Models Summary
+
+| ReadModel | Purpose | Events | Consumed By |
+|-----------|---------|--------|-------------|
+| OrderStatus | Show order state | OrderCreated, OrderConfirmed | UI, Processor |
+| OrderList | List orders | OrderCreated, OrderCancelled | UI |
+| PaymentStatus | Payment info | OrderConfirmed, PaymentAuthorized | UI, Accounting |
+| Shipment Tracking | Track delivery | OrderShipped, DeliveryConfirmed | UI, Notifications |
+
+---
+
+## Detailed Read Models
+
+### ReadModel: OrderStatusView
+
+**Purpose**: Order Status screen displays current order state
+
+**Events subscribed**:
+- OrderCreated
+- OrderConfirmed
+- PaymentAuthorized
+- OrderShipped
+- OrderCancelled
+- DeliveryConfirmed
+
+**Data**:
+```
+{
+  orderId: string
+  customerId: string
+  status: 'Draft' | 'Confirmed' | 'Authorized' | 'Shipped' | 'Delivered' | 'Cancelled'
+  items: Array<{productId, quantity, unitPrice}>
+  total: number
+  shippingAddress: Address
+
+  createdAt: Date
+  confirmedAt: Date
+  paymentId: string
+  paymentMethod: 'card' | 'transfer'
+  authorizedAt: Date
+
+  shipmentId: string
+  carrier: string
+  trackingNumber: string
+  shippedAt: Date
+  estimatedDelivery: Date
+}
+```
+
+**Update Logic**:
+- OrderCreated: Insert with status='Draft'
+- OrderConfirmed: Update status='Confirmed'
+- PaymentAuthorized: Update status='Authorized', set paymentId
+- OrderShipped: Update status='Shipped', set shipmentId, carrier, trackingNumber
+- DeliveryConfirmed: Update status='Delivered'
+- OrderCancelled: Update status='Cancelled'
+
+**Consumed By**:
+- Order Status Screen (displays)
+- Order Processing Processor (checks status)
+- Notification System (sends updates)
+
+--- [Repeat for each read model]
+
+---
+
+## Data Completeness Check
+
+### Events → UI Needs
+
+Verify all UI needs have event sources:
+
+| UI Need | Event Source | Status |
+|---------|-------------|--------|
+| Order status | OrderConfirmed, OrderShipped |  |
+| Tracking number | OrderShipped |  |
+| Order items | OrderCreated |  |
+| Estimated delivery | OrderShipped |  |
+| Cancellation reason | OrderCancelled |  |
+
+### Missing Data
+
+Identify UI needs without event sources:
+- None identified
+
+---
+
+## Processor Consumption
+
+### Processors and their reads:
+
+| Processor | Reads From | Writes Commands |
+|-----------|-----------|-----------------|
+| Inventory | OrderStatusView (Authorized) | ReserveInventory |
+| Fulfillment | OrderStatusView (InventoryReserved) | CreateShipment |
+| Notification | OrderStatusView (all) | None (info-only) |
+| Accounting | PaymentStatusView | None (reporting) |
+```

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-interview-protocol/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: eventmodeling-interview-protocol
+description: Shared procedure for deciding whether to ask the user clarifying questions before an event-modeling step proceeds, and how to record what was decided. Not a step of its own — referenced by other eventmodeling-* skills' Interview Phase section. Do not use standalone.
+---
+
+# Interview Protocol
+
+Shared by every event-modeling step that has an "Interview Phase" section. A step's own SKILL.md defines only what's specific to it — when to interview and its Critical Questions. Everything below is common to all of them.
+
+## When to ask
+
+Missing information, or something ambiguous that this step needs? Ask the user — using the step's own Critical Questions as a guide, via `AskUserQuestion` where appropriate. Follow any listed follow-up trigger based on the answer.
+
+Already have everything the step needs? Skip straight to the step's own workflow — don't ask questions whose answers you already have.
+
+**Unless told not to ask** (an autonomous/unattended run, or the user has said not to stop for questions): don't block. Proceed with the most reasonable assumption for anything missing, and say so plainly in this step's findings below — visibly, so it can be corrected later. Never silently guess.
+
+## Recording the outcome
+
+Append to the project's event modeling file: `.trogonai/interviews/[project-name]/EVENTMODELING.md`, under a section for this step:
+
+```markdown
+## <Step Number>. <Step Name> (<skill-name>)
+[What was asked and decided — or, if nothing was asked, what was assumed and why]
+```
+
+Then add or update this step's row in the `## Interview Trail` table (create it if this is the first step to run):
+
+```markdown
+| <Step Number> | <skill-name> | Done | <one-line summary of key outputs> |
+```

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-optimizing-stream-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: eventmodeling-optimizing-stream-design
-description: "Design event streams with proper stream identity to keep streams appropriately sized, avoid unnecessary snapshotting, and balance performance with simplicity. Use when concerned about stream length, planning performance, or validating stream design before implementation. Do not use for: designing the initial event model structure (use eventmodeling-designing-event-models) or general architectural validation (use eventmodeling-validating-event-models)."
+description: "Validate and fix an entity's event timeline boundary — is it anchored on a single business identity, or is it secretly a collection/log that will grow unbounded? Use when concerned about a timeline mixing concerns, reviewing timeline boundaries, or when a timeline feels like it's absorbing unrelated events. Do not use for: designing the initial event model structure (use eventmodeling-designing-event-models) or general model validation (use eventmodeling-validating-event-models)."
 allowed-tools:
   - AskUserQuestion
   - Write
@@ -8,224 +8,77 @@ allowed-tools:
 
 # Optimizing Stream Design
 
-## Interview Phase (Optional)
+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.
 
-**When to Interview**: Skip if the user has specified: expected event frequency, stream lifetime, and growth patterns. Interview when stream length concerns exist but growth estimates are unclear.
+## Timeline Boundary Optimization
 
-**Interview Strategy**: Establish growth expectations and performance requirements before recommending snapshotting. Most snapshotting proposals stem from poor stream boundary design, not genuine volume — surface the estimates first to distinguish real performance concerns from design problems.
+**Purpose**: Validate timeline boundaries — confirm each entity's event timeline is anchored on a single business entity's own lifecycle, and catch the two common anti-patterns (an unbounded collection, or an unrelated event log) before they get modeled further.
 
-### Critical Questions
-
-1. **Growth Estimates** (Impact: Determines if snapshotting is needed or if stream design should change)
-   - Question: "Estimate events: (A) Per entity per day, (B) Lifetime total, (C) Growth over years. Example: 5-10 events/order, 1-10 million orders/year?"
-   - Why it matters: Growth estimates reveal if streams will genuinely be too long or if design is wrong
-   - Follow-up triggers: If estimates exceed 300 events per stream lifetime → ask "Is the stream identity correct? Could this stream be split by a narrower business entity?"
-
-2. **Performance SLAs** (Impact: Determines acceptable latency and snapshotting decisions)
-   - Question: "Performance requirements? (A) <100ms read latency, (B) <1s acceptable, (C) Eventual consistency OK?"
-   - Why it matters: Strict SLAs might need snapshotting; loose SLAs often don't
-   - Follow-up triggers: If (A) → ask "Which commands specifically need sub-100ms replay? Are those commands reading from a read model or replaying the stream directly?"
-
-### Interview Flow
-
-**Conditional Entry**:
-```
-If user has provided:
-  - Event frequency estimate (per entity per day or per transaction)
-  - AND stream lifetime estimate (months or years)
-  - AND read latency SLA (or confirmation that eventual consistency is acceptable)
-
-Then: Skip interview, proceed directly to stream analysis
-
-Else: Conduct interview
-```
-
-**Phase 1: Growth Estimation** (Question 1)
-- Establish per-entity event volume
-- Project lifetime stream length using the estimation formula
-- Determine whether redesign or snapshotting analysis is warranted
-
-**Phase 2: SLA Requirements** (Question 2)
-- Identify read latency requirements per command
-- Determine whether read models or direct stream replay satisfies the SLA
-- Establish whether snapshotting is justified by SLA alone
-
-### Capturing Interview Findings
-
-Append findings to the project's event modeling file:
-
-**File**: `.trogonai/interviews/[project-name]/EVENTMODELING.md`
-
-Use Write tool to add/update this section:
-
-```markdown
-## Optimizing Stream Design (eventmodeling-optimizing-stream-design)
-
-### Growth Estimates
-[From Q1: Events per entity per day, lifetime total, annual growth]
-
-### Performance SLAs
-[From Q2: Latency requirements per command or view]
-
-### Optimization Decisions
-- Streams requiring redesign: [list or "None"]
-- Streams where snapshotting is justified: [list or "None"]
-- Streams within acceptable bounds: [list]
-```
-
-Update Interview Trail:
-```markdown
-| Optimization | eventmodeling-optimizing-stream-design | Done | Stream growth estimates, SLA review, snapshotting decisions |
-```
-
----
-
-## Stream Design Optimization
-
-**Purpose**: Optimize event stream design by validating stream boundaries, estimating growth, and making snapshotting decisions based on design quality—not just size.
-
-**Applies To**: Any domain - e-commerce, banking, SaaS, marketplace, healthcare, etc.
+**Applies To**: Any domain — e-commerce, banking, SaaS, marketplace, healthcare, etc.
 
 **When to Use**:
-- After defining event streams in domain analysis
-- When concerned about stream length or performance
-- Before implementing to validate stream design
-- During performance planning to determine snapshotting strategy
-- When redesigning streams for scalability
+- After defining events in domain analysis
+- When a timeline feels like it's growing for reasons unrelated to one entity's own story
+- When redesigning a timeline whose boundary turned out to be wrong
 
 **What It Does**:
-1. Analyzes event stream design for proper event organization
-2. Estimates stream growth over time
-3. Identifies when snapshotting is genuinely needed vs. design issue
-4. Recommends optimal stream identity boundaries
-5. Balances performance optimization against complexity
-6. Provides snapshotting strategy without over-engineering
+1. Checks that each timeline has a single, natural business identity
+2. Identifies timelines that are actually collections or logs in disguise
+3. Recommends the correct boundary when one is wrong
+4. Distinguishes "this timeline is long because the entity has a long history" (fine) from "this timeline is long because it's absorbing events that don't belong to it" (a boundary bug)
 
 ---
 
-## Core Principle: Design First, Snapshot Second
+## Core Principle: Get the Identity Right
 
 **Golden Rule**:
-> If you find yourself needing to snapshot because the stream is too long, first ask: "Is my stream identity wrong?" Usually, the answer is yes.
+> If a timeline feels like it's growing for the wrong reasons, first ask: "Does this timeline actually have one business identity, or is it a collection/log wearing an entity's name?"
 
-Snapshotting is a **performance optimization**, not a design problem. Good stream design (proper identity boundaries) often eliminates the need for snapshotting entirely.
+A long timeline is not, by itself, evidence of a design problem — an account open for thirty years is correctly one long timeline. What *is* always a design problem is a timeline whose events don't all belong to the same entity's own lifecycle.
 
 ---
 
-## Stream Design Analysis Framework
+## Timeline Boundary Review
 
-### 1. Estimate Stream Growth
+For each entity's timeline in scope, work through:
 
-**Formula**:
-```
-Estimated Stream Length (total events/instance) =
-Events Per Aggregate Instance Per Year (events/instance/year)
-  × Lifetime of Instance (years)
-  × Annual Growth Factor (dimensionless year-over-year multiplier ≥ 1.0)
-```
+### 1. Name the identity
 
-**Quick Examples**:
+What single business entity does this timeline represent the history of? Write it down explicitly (e.g. `orderId`, not "orders").
 
-**E-commerce Order**: 8 events/year × 1.5 year lifetime = 8-16 events → NOT NEEDED
+### 2. Check every event against that identity
 
-**Banking Account**: 100-200 events/year × 10 years = 1000-2000 events → CONSIDER AT 1000+
+Does each event on the timeline describe something that happened to *this* entity — not to a category of entities, not to the system in general? If any event fails this test, the boundary is wrong (see `references/patterns.md`'s Red Flags).
 
-**Order Processing**: 100+ events/year × 5 years = 300-500+ events → PROBABLY NEEDED
+### 3. Classify the result
 
-**SaaS User**: 12-60 events/year × 5 years = 60-300 events → RARELY NEEDED
-
-### 2. Identify Stream Length Categories
-
-| Length | Status | Action | Snapshotting |
-|--------|--------|--------|--------------|
-| < 50 events | IDEAL | Keep as-is | NOT NEEDED  |
-| 50-100 events | GOOD | Monitor growth | NOT NEEDED  |
-| 100-300 events | ACCEPTABLE | Review boundary | CONSIDER if replayed |
-| 300-1000 events | LONG | REDESIGN first | Only last resort |
-| 1000+ events | CRITICAL | REDESIGN required | Won't help |
-
----
-
-## Quick Decision Matrix
-
-| Stream Length | Read Pattern | Frequency | Action |
-|---|---|---|---|
-| < 50 | Any | Any |  IDEAL - Keep as-is |
-| 50-100 | Any | Any |  Good - Monitor |
-| 100-300 | From Model | Any |  OK - No snapshot |
-| 100-300 | Stream Replay | Low |  OK - Monitor |
-| 100-300 | Stream Replay | High |  REDESIGN |
-| 300-1000 | From Model | Any |  OK - No snapshot |
-| 300-1000 | Stream Replay | Any |  REDESIGN |
-| 1000+ | Any | Any |  CRITICAL - REDESIGN |
+| Result | Meaning | Action |
+|---|---|---|
+| Every event belongs to one clear entity | Boundary is correct | Keep as-is, regardless of how long the history gets |
+| Events span a category or "all X" | Pattern 3 (Collection) anti-pattern | Re-scope to the real per-entity identity; the category becomes a read model/query, not an event timeline |
+| Events span unrelated concerns (users, orders, payments mixed) | Pattern 4 (Event Log) anti-pattern | Split into one timeline per concern |
+| Timeline conflates an entity's active life with its historical record | Missing the Pattern 5 split | Separate active vs. archived/historical timelines |
 
 ---
 
 ## Reference Files
 
-**Aggregate Boundary Design**: See [patterns.md](references/patterns.md) for:
-- 5 aggregate patterns (single entity, composite, collections, event logs, historical)
-- Stream size decision tree
-- Red flags that indicate redesign needed
-- Tips for optimal stream design
-
-**Snapshotting Strategy**: See [snapshotting.md](references/snapshotting.md) for:
-- Criteria for when snapshotting is truly needed
-- Context-based decision thresholds
-- Snapshot frequency, versioning, and cleanup strategies
-- Cost-benefit analysis
+**Timeline Boundary Design**: See [patterns.md](references/patterns.md) for:
+- 5 boundary patterns (single entity, composite, collection anti-pattern, event-log anti-pattern, historical)
+- The timeline boundary decision tree
+- Red flags that indicate the boundary — not the volume — is wrong
+- Tips for finding the right boundary
 
 **Domain-Specific Guidance**: See [domain-patterns.md](references/domain-patterns.md) for:
 - E-commerce patterns (orders, carts, accounts)
 - Banking patterns (accounts, transactions, loans)
 - SaaS patterns (subscriptions, workspaces, data collections)
-- Implementation checklist
-
----
-
-## Key Insights
-
-### Why Snapshotting Usually Isn't the Answer
-
-```
-Before implementing snapshotting, ask:
-
-1. Can I split this aggregate into smaller ones?
-   → YES: Do that instead. Simpler, better design.
-
-2. Can I reduce event granularity?
-   → YES: Batch events or create coarser state changes.
-
-3. Am I using a read model for this aggregate?
-   → NO: Create a read model (cached projection).
-      Stream size becomes irrelevant.
-
-4. Have I measured actual replay latency?
-   → NO: Measure first. Most systems exceed expectations.
-
-If ANY of these is YES, do that before snapshotting.
-Only after exhausting design improvements, consider snapshots.
-```
-
-### The Snapshotting Trade-off
-
-```
-Snapshotting Complexity ≈ 2-3x Complexity of Better Design
-
-Before snapshot:  50 lines of code, simple, testable
-With snapshots:   150+ lines, versioning, recovery logic, testing matrix
-
-Better to redesign and keep streams < 300 events.
-```
 
 ---
 
 ## Quality Checklist
 
-- [ ] Each stream is identified by a business entity identity (e.g., `orderId`), not a category or type
-- [ ] No stream grows unboundedly without a design reason — event frequency and stream lifetime estimated
-- [ ] Streams under 1000 events require no snapshotting justification
-- [ ] If snapshotting is proposed, all simpler alternatives (split stream, shorter lifetime) have been eliminated first
-- [ ] Command handler state is reconstructed from stream events — no persistent state stored outside the stream
-- [ ] Each stream can be independently versioned and replayed without affecting other streams
-
+- [ ] Each timeline is identified by a business entity identity (e.g., `orderId`), not a category or type
+- [ ] Every event on a timeline belongs to that one entity's own lifecycle — none of them describe a different entity or an unrelated system concern
+- [ ] No timeline is secretly a collection ("all X") or a log ("everything that happened") wearing an entity's name
+- [ ] A timeline that conflates an entity's active life with its historical record has been split (active vs. archived)