@nebulit/embuilder 0.1.46 → 0.1.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulit/embuilder",
-  "version": "0.1.46",
+  "version": "0.1.47",
   "description": "Event-model driven development toolkit for Claude Code",
   "type": "module",
   "bin": {

package/templates/.claude/skills/slice-automation/SKILL.md

@@ -1,49 +1,251 @@
 ---
-name: skeleton-automation
-description: Generate automation slices from config.json
+name: slice-automation
+description: builds an automation slice from an event model
 ---
 
-# Generate Automation Slice
+### Critical understanding
 
-Generate automation slices (background processors with CRON scheduling) from your event model configuration.
+Make sure to read the Agents.md file before building anything.
 
-## Task
+If the processors-Array is not empty, it´s an automation slice.
 
-You are tasked with generating one or more automation slices using the emmet-supabase Yeoman generator.
+Important - an automation slice is "just" a state-change slice with an additional automation that triggers the command.
+So also read the skill for 'state-change-slice'
 
-## Steps
+## Critical Requirements
 
-1. Check if a `config.json` file exists in the current directory
-   - If not found, inform the user they need a config.json file
-   - Exit with instructions on creating one
+### Restaurant ID Requirement
+- **CRITICAL**: ALL events MUST have `restaurantId` in their metadata (camelCase)
+- **NEVER** use `locationId` or `location_id` - these are outdated and forbidden
+- **CRITICAL**: ALL database tables (including TODO lists) MUST have a `restaurant_id` column (snake_case)
+- This ensures proper multi-tenancy and data isolation
 
-2. Read the config.json to find available AUTOMATION slices:
-   - Look for slices with `"sliceType": "AUTOMATION"`
-   - Extract their IDs and titles
+## Overview
 
-3. Show the user available automation slices and ask which ones to generate
-   - Allow multiple selections
-   - Or accept slice IDs from the user's original request
+Automations are processes that happen in the background, based on a TODO List.
+TODO Lists are always tables (read models) and each row in the table is a TODO Item.
 
-4. Run the local generator with selected slices:
-   ```bash
-   npx yo ./.claude/skills/gen-skeleton/generators/emmet-supabase/app --action AUTOMATION --slices <slice-id-1>,<slice-id-2>
-   ```
+The automation is only responsible to:
+1. Fetch items from the TODO List (read model)
+2. Fire the command for each item
+3. Repeat on a schedule using CRON
 
-5. After generation completes:
-   - List the files that were created
-   - Run tests for the generated slices if available
-   - Explain the CRON configuration if applicable
-   - Suggest next steps
+## Architecture Pattern
+
+```
+┌─────────────────┐
+│  TODO List      │  (Read Model - Inbound Dependency)
+│  "items to do"  │  Example: "clerks_to_invite", "items_to_fetch"
+└────────┬────────┘
+         │
+         │ reads
+         │
+┌────────▼────────┐
+│   processor.ts  │  (CRON scheduled automation)
+│                 │  - Fetches TODO items
+│                 │  - Fires commands
+└────────┬────────┘
+         │
+         │ invokes
+         │
+┌────────▼────────┐
+│ CommandHandler  │  (State-change logic)
+│   Command.ts    │  - decide() function
+│   routes.ts     │  - evolve() function
+└─────────────────┘
+```
+
+## Implementation Structure
+
+An automation slice consists of:
+1. **processor.ts** - CRON automation that fetches TODO items and fires commands
+2. **[Command]Command.ts** - Command handler with decide/evolve logic
+3. **routes.ts** - HTTP API endpoint for manual command invocation
+
+## Processor Configuration
+
+Two patterns exist in the codebase:
+
+### Pattern 1: Using startProcessor helper (Recommended)
+
+```typescript
+import {ProcessorConfig, ProcessorTodoItem, startProcessor} from "../../process/process";
+import {handleYourCommand} from "./YourCommandCommand";
+
+export type ItemToProcess = {
+    itemId: string,
+    // other fields from read model
+}
+
+const config: ProcessorConfig = {
+    schedule: "*/5 * * * * *", // Every 5 seconds (cron format)
+    endpoint: "your-todo-list-collection", // Read model endpoint
+    query: {
+        "status": "OPEN",    // Filter criteria
+        "_limit": "1"         // Process one at a time
+    }
+}
+
+const handler = async (item: ItemToProcess & ProcessorTodoItem) => {
+    console.log(`Processing item: ${item.itemId}`)
+
+    try {
+        await handleYourCommand(`aggregate-${item.itemId}`, {
+            type: "YourCommand",
+            data: {
+                itemId: item.itemId,
+                // map other fields
+            },
+            metadata: {}
+        })
+
+        console.log(`Successfully processed item: ${item.itemId}`)
+    } catch (error) {
+        console.error(`Error processing item ${item.itemId}:`, error)
+    }
+}
+
+export const processor = {
+    start: () => {
+        console.log("[YourProcessor] Starting processor...")
+        startProcessor<ItemToProcess>(config, handler)
+    }
+}
+```
+
+### Pattern 2: Direct Supabase query (Legacy)
+
+```typescript
+import {ProcessorConfig} from "../../process/process";
+import {YourCommand, handleYourCommand} from "./YourCommandCommand";
+import cron from "node-cron";
+import {createServiceClient} from "../../supabase/api";
+
+const config: ProcessorConfig = {
+    schedule: '*/30 * * * * *',  // Every 30 seconds
+    endpoint: "your_todo_table",  // Supabase table name
+}
+
+export const processor = {
+    start: () => {
+        cron.schedule(config.schedule, async () => {
+            console.log("Running process")
+            let client = createServiceClient()
+            let result = await client.from(config.endpoint).select("*")
+
+            if (result.count == 0) {
+                console.log(`Nothing to do for ${config.endpoint}`)
+                return;
+            }
+
+            for (const item of result.data ?? []) {
+                const command: YourCommand = {
+                    type: "YourCommand",
+                    data: {
+                        itemId: item.itemId!
+                    },
+                    metadata: {}
+                }
+
+                const id = item.itemId
+                if (!id) {
+                    throw `Cannot process Command ${command.type}. No Id available.`
+                }
+                await handleYourCommand(id, command)
+            }
+        })
+    }
+}
+```
+
+## CRON Schedule Format
+
+```
+┌───────────── second (0-59)
+│ ┌─────────── minute (0-59)
+│ │ ┌───────── hour (0-23)
+│ │ │ ┌─────── day of month (1-31)
+│ │ │ │ ┌───── month (1-12)
+│ │ │ │ │ ┌─── day of week (0-7)
+│ │ │ │ │ │
+* * * * * *
+```
+
+Common schedules:
+- `*/5 * * * * *` - Every 5 seconds
+- `*/30 * * * * *` - Every 30 seconds
+- `0 */1 * * * *` - Every minute
+- `0 0 * * * *` - Every hour
+
+## Real Examples from Codebase
+
+### Example 1: ConfirmInvitation (Clerk management)
+
+**TODO List Read Model**: `clerks_to_invite` table
+**Automation**: `src/slices/ConfirmInvitation/processor.ts`
+**Command**: `ConfirmInvitationCommand`
+**Event Emitted**: `ClerkInvitationConfirmed`
+
+```typescript
+// processor.ts
+const config: ProcessorConfig = {
+    schedule: '*/30 * * * * *',
+    endpoint: "clerks_to_invite",
+}
+
+// Fetches clerks from TODO list and confirms their invitations
+for (const clerk of result.data ?? []) {
+    const command: ConfirmInvitationCommand = {
+        type: "ConfirmInvitation",
+        data: {
+            clerkId: clerk.clerkId!
+        },
+        metadata: {}
+    }
+    await handleConfirmInvitation(clerk.clerkId, command)
+}
+```
+
+in each slice folder, generate a file .slice.json
+```
+{
+    "id" : "<slice id>",
+    "slice": "<slice title>",
+    "context": "<contextx>",
+    "link": "https://miro.com/app/board/<board-id>=/?moveToWidget=<slice id>"
+}
+```
+
+## Key Points
+
+1. **TODO List Naming**: Use format `<things>_to_<action>` (e.g., `clerks_to_invite`, `items_to_fetch`)
+2. **Read Model Endpoint**: TODO list is accessed via `/api/query/<name>-collection` endpoint
+3. **Processor Types**: Define TypeScript types for TODO items matching read model structure
+4. **Error Handling**: Always wrap command execution in try-catch, log errors but continue processing
+5. **Schedule Wisely**: Balance responsiveness vs system load (30 seconds is common for production)
+6. **Status Management**: TODO list typically has a `status` field ("OPEN", "PROCESSING", "DONE")
+7. **Limit Processing**: Use `_limit: "1"` to process one item at a time, preventing concurrent issues
+8. **Stream Naming**: Use aggregate-based stream names (e.g., `catalogue-${itemId}`)
+
+## Implementation Steps
+
+1. **Read the input JSON** from templates/sample-input.json
+2. **Create processor.ts** following one of the patterns above
+3. **Implement state-change slice** using the 'state-change-slice' skill
+    - Creates `[Command]Command.ts` with decide/evolve functions
+    - No `routes.ts` for Automations.
+4. **Register processor** in main application startup
+5. **Ensure TODO List exists** as a read model (separate slice handles this)
+
+## Sample Input Structure
+
+Sample input: read 'templates/sample-input.json'
+
+The input defines:
+- **processors[]**: Array of automation definitions
+    - title: Automation name
+    - dependencies: Inbound (TODO list) and Outbound (Command) connections
+- **commands[]**: Commands triggered by the automation
+- **events[]**: Events emitted by the commands
 
-## Important Notes
 
-- The generator is located in `.claude/skills/gen-skeleton/generators/emmet-supabase`
-- Multiple slices can be generated in one command (comma-separated)
-- Slice IDs must exactly match those in config.json
-- Generated files typically include:
-  - processor.ts (background automation logic)
-  - CRON configuration
-  - Tests
-- Automation slices read from TODO lists (work queues) and fire commands on a schedule
-- Common use cases: auto-confirm invitations, process checkouts, send notifications

package/templates/backend/AGENTS.md

@@ -0,0 +1,531 @@
+# Agent Learnings
+
+## Core Principles
+
+### Source of Truth
+- **config.json is the TRUE source of truth** for slice status - always check it, not just index.json or slice.json
+- **slice.json reflects the current specification** for field definitions, event structures, and specifications
+- When config.json shows "Planned" but index.json/slice.json show "Done", verify implementation and update config.json
+- The aggregate field in slice.json determines domain entity naming (Location → locationId, Restaurant → restaurantId)
+- When an event is used by multiple slices, fixing it requires updating ALL slices that use it
+- Field names must be consistent across: events, commands, migrations, projections, routes, tests, API docs
+
+### Pre-Implementation Checks
+- **Always check if slice already exists** before implementing a "Planned" slice - verify `src/slices/{SliceName}/`
+- **Run tests first**: existing implementations may only need test data fixes
+- **Search for event usage**: `grep -r "EventName" src/slices/` before modifying events
+- **Status drift**: slice status in index.json may lag behind actual implementation
+
+### Slice Status
+- Valid statuses: "Done", "Planned", "Assigned", "Created", "Blocked", "Informational"
+- **"Assigned" = "Planned"** - treat as equivalent when picking next slice
+- Always update status to "Done" after completing implementation and passing tests
+
+## Event Management
+
+### Event Type Naming & Registration
+- Event type names MUST use PascalCase (RestaurantRegistered, not Restaurantregistered)
+- All new events MUST be added to ContextEvents union type in `src/events/ContextEvents.ts`
+- Event types follow `Event<'EventName', {...fields}, {...metadata}>` pattern
+- Event titles in slice.json use lowercase (e.g., "Event created" not "Event Created")
+- TypeScript type names use PascalCase (e.g., `EventCreated` type)
+
+### Event Field Structure
+- DateTime type in slice.json → TypeScript `Date` type (not string)
+- Event metadata MUST include restaurantId and userId for multi-tenancy and authorization
+- Auto-generated code may have incorrect casing or wrong field types - always verify against slice.json
+- Field name typos in slice.json must be preserved for consistency (e.g., "restaurandId")
+
+### Event Verification & Creation
+- **Always verify events exist** in `src/events/` and `ContextEvents.ts` before creating them
+- Events from unimplemented slices can be created based on their slice.json specifications
+- STATE_VIEW slices can reference events that don't exist yet - create them based on slice.json
+- Check slice.json → dependencies array (INBOUND) for STATE_VIEW event sources
+
+### Event Structure Changes - CRITICAL
+When modifying existing event structure:
+1. Find all consumers: `grep -r "EventName" src/slices/`
+2. Update ALL occurrences: command handlers, projections, tests, routes, API docs
+3. Run `npm run build` BEFORE tests - TypeScript shows ALL files with type mismatches
+4. Checklist: Event updated → handlers updated → tests updated → build passes → all tests pass
+
+### Cross-Slice Event Reuse
+- Events created for STATE_VIEW projection can be reused by STATE_CHANGE commands
+- Same event consumed by multiple projections (e.g., CheckinCancelled)
+- Create event once, reference in multiple slice implementations
+
+## Architecture & Auto-Discovery
+
+### Auto-Discovery System
+- **Routes**: `src/slices/**/routes.ts` (exports `api` function returning `WebApiSetup`)
+- **Processors**: `src/slices/**/processor.ts` (exports `processor = { start: () => {...} }`)
+- No manual registration needed - loaded automatically at server startup
+
+### Projections Registration
+- All new projections must be registered in `src/common/loadPostgresEventstore.ts`
+- **Critical**: When slice files deleted, check for stale imports causing build failures
+- Pattern: `grep -n "DeletedSliceName" src/common/loadPostgresEventstore.ts`
+
+### PostgreSQL Critical Imports
+```typescript
+import { postgreSQLRawSQLProjection } from '@event-driven-io/emmett-postgresql';
+import { sql } from '@event-driven-io/dumbo';  // NOT from emmett-postgresql!
+import { ContextEvents } from '../../events/ContextEvents';
+```
+- Always use `.withSchema('public')` in PostgreSQL queries
+
+### Type Coercion
+- Pongo stores numeric-looking strings (e.g., "1") as bigints (e.g., 1n)
+- Use `String(value)` when comparing IDs in test assertions
+
+## Stream ID Patterns Reference
+
+### `idAttribute` and Stream ID
+- If a field on command/event has `"idAttribute": true`, that field is the streamId
+- Explicit stream identifier in slice.json takes precedence over `idAttribute`
+
+### Common Stream ID Patterns
+
+| Aggregate Type | Stream ID Format | Helper | Used By |
+|---------------|------------------|--------|---------|
+| Time Entry | `time-entry-{clerkId}-{month}` | `timeEntryStreamId()` | CheckIn, CheckOut, SubmitTimeEntry, DeleteTimeentry, UpdateTimeEntry |
+| Event Assignment | `{restaurantId}-event-{eventId}` | `eventStreamId()` | AssignClerkToEvent, UnAssignClerkFromEvent |
+| Shift Publication | `shift-publication-{shiftId}` | N/A | PublishShift, UnpublishShift |
+
+**Notes**: Time entry month format: MMYYYY (e.g., "022026"). Multiple commands can share same stream.
+
+## Implementation Patterns
+
+> For templates and step-by-step guides, use skills: `/state-change-slice`, `/state-view-slice`, `/automation-slice`
+
+### STATE_CHANGE Slice Pattern
+
+**Key Rules**:
+- Use proper `initialState` function (not empty object `{}`) in `DeciderSpecification.for()`
+- Do NOT add explicit type arguments - let TypeScript infer (avoids TS2558)
+- Switch statements: always use explicit `break` to prevent fallthrough bugs
+
+**Structure**:
+```typescript
+type State = { /* track relevant state */ };
+const initialState = (): State => ({ /* defaults */ });
+const decide = (state: State, cmd: Command): Event[] => {
+  if (invalidCondition) throw 'error.code';
+  return [createEvent(cmd)];
+};
+const evolve = (state: State, event: ContextEvents): State => {
+  switch (event.type) {
+    case 'EventType': return { ...state, field: newValue };
+    default: return state;
+  }
+};
+```
+
+**Error Testing**: Use `.shouldFail()` or `assert.throws()`
+
+### STATE_VIEW Slice Pattern
+
+**Key Rules**:
+- Always verify ALL events from slice.json are in `canHandle` array
+- Use specific event union type (e.g., `Event1 | Event2`) NOT `ContextEvents` when handling subset
+- Missing event handlers = incomplete implementation
+
+**Projection Structure**:
+```typescript
+export const ProjectionName = postgreSQLRawSQLProjection({
+  canHandle: ['Event1', 'Event2'],
+  evolve: (event: Event1 | Event2) => {
+    switch (event.type) {
+      case 'Event1': return sql(db(table).insert({...}).onConflict().merge());
+      case 'Event2': return sql(db(table).where({...}).delete());
+      default: return [];
+    }
+  }
+});
+```
+
+**Event Dependencies**: Look in slice.json → readmodels → dependencies (INBOUND) for event IDs
+
+### AUTOMATION Slice Pattern
+
+**Structure**: STATE_CHANGE + processor.ts + work queue projection
+
+**Processor Implementation**:
+```typescript
+import * as cron from 'node-cron';
+import { createServiceClient } from '../../common/supabaseClient';
+
+const config = { schedule: '*/30 * * * * *', endpoint: "work_queue_table" };
+
+export const processor = {
+  start: () => {
+    cron.schedule(config.schedule, async () => {
+      const client = createServiceClient();
+      const result = await client.from(config.endpoint)
+        .select("*").eq('must_process', true).limit(1);
+
+      if (result.error) return;
+      for (const item of result.data ?? []) {
+        try {
+          await handleCommand(streamId, command, { userId: 'system', ...metadata });
+        } catch (error) {
+          console.error('Processing error:', error);
+        }
+      }
+    });
+  }
+};
+```
+
+**Key Rules**:
+- Use `.limit(1)` to process one item at a time
+- `createServiceClient()` bypasses RLS for automation
+- Processor uses snake_case column names (e.g., `reservation_id`)
+- Work queue lifecycle: add on trigger → update flags → delete on completion
+
+## State Tracking Patterns
+
+### Boolean/Toggle State
+```typescript
+type State = { isActive: boolean };
+const decide = (state: State, cmd: Command): Event[] => {
+  if (state.isActive) throw "already.active";  // Activate guard
+  if (!state.isActive) throw "not.active";     // Deactivate guard
+  return [event];
+};
+```
+
+**Database**: Use flag column (e.g., `is_online_active BOOLEAN`), update with upsert `.onConflict().merge()`
+
+### Set<string> for ID Tracking
+```typescript
+type State = { trackedIds: Set<string> };
+const evolve = (state: State, event: ContextEvents): State => {
+  switch (event.type) {
+    case 'ItemAdded': return { trackedIds: new Set([...state.trackedIds, event.data.id]) };
+    case 'ItemRemoved':
+      const newSet = new Set(state.trackedIds);
+      newSet.delete(event.data.id);
+      return { trackedIds: newSet };
+  }
+};
+```
+
+**Examples**: UnAssign Clerk from Event, Delete Time Entry, Update Time Entry
+
+### Multi-Flag State Machine
+```typescript
+type State = { submitted: boolean; reverted: boolean; approved: boolean; declined: boolean };
+const decide = (state: State, cmd: Command): Event[] => {
+  if (state.submitted) throw 'cannot submit twice';
+  if (!state.submitted) throw 'not_submitted';
+  if (state.reverted) throw 'already_reverted';
+  return [event];
+};
+```
+
+**Workflows**: Timesheet (Submitted → Reverted → Resubmitted), Approval (Approved → Declined → Reapproved)
+
+## Database & Projections
+
+### Migration Rules
+- **NEVER modify existing migrations** - always add new ones
+- Version check: `ls -1 supabase/migrations/ | grep "^V" | sort -V | tail -5`
+- Naming: `V{N}__{table_name}.sql` (e.g., `V41__clerk_details.sql`)
+- PostgreSQL types: Use TEXT/VARCHAR (not "string"), valid UUID format required
+- Composite PKs for multi-tenant: `PRIMARY KEY (restaurant_id, entity_id)`
+
+### Projection Patterns
+
+**Add/Remove**:
+```typescript
+case 'Added': return sql(db(table).insert({...}).onConflict(key).merge());
+case 'Removed': return sql(db(table).where({id}).delete());
+```
+
+**Work Queue Lifecycle**:
+```typescript
+case 'TriggerEvent': return sql(db(table).insert({id, must_process: false}).onConflict().merge());
+case 'ProgressEvent': return sql(db(table).where({id}).update({must_process: true}));
+case 'CompletionEvent': return sql(db(table).where({id}).delete());
+```
+
+**Conditional Flags**: Set flags based on matching business data (e.g., `must_cancel = true` only when clerkId matches)
+
+### JSONB Field Handling
+- PostgreSQL JSONB auto-parsed by pg driver - DO NOT use `JSON.parse()` in tests
+- Storage: `assignees JSONB DEFAULT '[]'::jsonb`
+- Updates: `assignees: JSON.stringify(data.assignees)` (plain JavaScript, not raw SQL)
+- Array conversion for display: `Array.isArray(field) ? field.join(', ') : field || ''`
+
+### Query Endpoints - Authentication
+All endpoints must:
+1. Require JWT: `requireUser(req, res, true)`
+2. Filter by authenticated user's ID
+3. Use anon key Supabase client
+
+### Date Handling
+- slice.json DateTime → TypeScript `Date` type
+- Routes: `date: new Date(assertNotEmpty(req.body.date))`
+- Tests: Use Date objects: `new Date('2026-03-15T10:00:00Z')`
+- Timezone: Europe/Berlin → UTC conversion (CET = UTC+1, CEST = UTC+2 for DST)
+
+## Test Patterns Reference
+
+### STATE_CHANGE Tests
+```typescript
+DeciderSpecification.for(decide, evolve, initialState)
+  .given([PrerequisiteEvent1, PrerequisiteEvent2])
+  .when(Command({ field: 'value' }))
+  .then([ExpectedEvent({ field: 'value' })]);
+```
+
+### STATE_VIEW Tests
+```typescript
+PostgreSQLProjectionSpec.for(ProjectionName)
+  .given([Event1, Event2])
+  .when([])  // Always empty
+  .then(async (state) => {
+    const result = await state.query();
+    assert.equal(result[0].field, expectedValue);
+  });
+```
+
+### Error Case Tests
+```typescript
+.given([EventCreated])
+.when(Command)
+.shouldFail();  // Expects error
+```
+
+### Test Coverage
+- **STATE_CHANGE**: Happy path + all error guards
+- **STATE_VIEW**: One test per INBOUND event dependency
+- **AUTOMATION**: Command logic + error guards (processor not unit tested)
+
+## Test Specifications & code-slice.json
+
+### Purpose of test-analyzer
+- Analyzes tests to extract behavioral specifications
+- Generates code-slice.json in `.slices/{Context}/{folder}/`
+- Includes only specs NOT in slice.json (drift detection)
+
+### Drift Detection
+**Generate code-slice.json when**:
+- Test specs NOT in slice.json specifications array
+- slice.json has `specifications: []` but tests exist
+
+**No code-slice.json when** (No Drift):
+- All test specs already in slice.json
+- Quality indicator: implementation matches design
+
+### linkedId Lookup
+**STATE_CHANGE**: Command/Event IDs from slice.json → commands/events array → id field
+**STATE_VIEW**: Event IDs from slice.json → readmodels → dependencies (INBOUND) → id field
+
+```bash
+# Find slice.json for event source
+find .slices -name "slice.json" -path "*{slicename}*"
+
+# Extract event ID (use lowercase title)
+cat path/to/slice.json | jq '.events[] | select(.title == "Event created") | .id'
+```
+
+**Note**: Event titles in slice.json are lowercase ("Event created"), TypeScript types are PascalCase (`EventCreated`)
+
+### Field Type Mapping
+- UUID format → "UUID" type
+- ISO dates → "String" or "Date"
+- Whole numbers → "Integer"
+- Text → "String"
+- Cardinality: "Single" for non-array fields
+
+## Implementation Quality Checklist
+
+### Standard Workflow (All Slices)
+1. [ ] Build passes: `npm run build`
+2. [ ] All tests pass: `npm run test`
+3. [ ] Run test-analyzer skill (if drift detected)
+4. [ ] Update `.slices/index.json` status to "Done"
+5. [ ] Update `progress.txt` with iteration summary
+6. [ ] Update `AGENTS.md` with new learnings
+7. [ ] Commit with Co-Authored-By line
+
+### Additional: AUTOMATION Slices
+- [ ] Processor.ts with CRON schedule
+- [ ] Routes for manual invocation
+- [ ] Test includes error cases
+
+### Additional: STATE_VIEW Slices
+- [ ] All INBOUND events in canHandle array
+- [ ] Each event has handler in evolve
+- [ ] Test per INBOUND event
+- [ ] Projection registered in `loadPostgresEventstore.ts`
+
+### "To-Do List" STATE_VIEW Pattern
+When a STATE_VIEW acts as a work queue (items appear when created, disappear when processed):
+- Use `insert().onConflict().ignore()` for the trigger event (e.g., RestaurantRegistered)
+- Use `where({id}).delete()` for the completion event (e.g., BucketCreated)
+- Table naming: `slice_<name>` prefix for slice-specific work queue tables
+- The "bucketId" maps to "restaurantId" — both fields stored, one used as PK
+
+### AUTOMATION Processor with External API
+When an AUTOMATION slice's `backendPrompt` specifies an external operation (e.g., "create a bucket using the Supabase storage API"):
+- Perform the external API call **before** firing the command
+- Use `client.storage.createBucket(id)` for Supabase storage bucket creation
+- Name the bucket after the entity identifier (e.g., restaurant ID)
+- On failure, catch per-item and continue (don't stop the entire batch)
+- The command acts as the **confirmation** that the external operation succeeded
+
+### folder Field in slice.json
+When a command/event has a `folder` field with `"mapping": "month"`:
+- The `folder` field's value = the `month` field's value (same value, different semantic purpose)
+- In storage uploads: use `${month}/` as the folder prefix in the file path (e.g., `${month}/${clerkId}-${month}.csv`)
+- `backendPrompt: "use the month as a folder in the bucket"` = upload path `${month}/{filename}` not just `{filename}`
+- Pass `folder` in command data and event data just like other fields
+
+### Additional: Completing Partial Slices
+- [ ] Verify all dependencies from slice.json implemented
+- [ ] Compare canHandle with dependencies
+- [ ] Add missing handlers and tests
+
+### Event Structure Changes
+- [ ] Event definition updated
+- [ ] All command handlers updated
+- [ ] All consuming slice tests updated
+- [ ] Build passes, all tests pass
+
+## Common Patterns by Domain
+
+### Time Entry Domain
+
+**Stream ID**: `time-entry-{clerkId}-{month}` (MMYYYY format)
+
+**Key Events**: CheckedIn, CheckedOut, TimeEntryAdded, TimesheetSubmitted, SubmissionReverted, TimesheetApproved, TimesheetDeclined, CheckinCancelled
+
+**Workflow**:
+1. CheckIn → ActiveCheckins
+2. CheckOut → TimeEntryCheckoutsToProcess (work queue)
+3. ProcessTimeEntryCheckout (automation) → TimeEntryAdded
+4. SubmitTimeEntry → ActiveCheckinsToCancel (mark for cancellation)
+5. CancelCheckin (automation) → CheckinCancelled
+6. SubmitTimesheet → TimesheetSubmitted → SubmissionDate, SubmissionStatus
+7. ApproveTimesheet → TimesheetApproved → ApprovalDate
+8. DeclineTimesheet → TimesheetDeclined (allows reapproval)
+
+**Hours Calculation**: `(endDate - startDate) ms / (1000*60*60)`, rounded to 0.5
+
+**Guard Patterns**:
+- CheckOut: if CheckedOut in stream → throw "no active check"
+- ProcessTimeEntryCheckout: if NO CheckedOut → throw "no confirmed checkout"
+- SubmitTimesheet: if submitted → throw "cannot submit twice"
+- Delete/Update: track Set<string> of entry IDs
+- SubmitTimeEntry: if `approved && !declined` → throw "cannot submit time entry after approval"
+- DeleteTimeentry: if `approved && !declined` → throw "cannot delete after approval"
+- UpdateTimeEntry: if `submitted && !declined` → throw "cannot submit after submission"
+
+**Cross-Slice State Rules (Time Entry Approval Guards)**:
+- `TimesheetApproved` event: sets `approved=true, declined=false`
+- `TimesheetDeclined` event: sets `approved=false, declined=true` (resets approval, re-enables submit/delete/update)
+- `SubmissionReverted` event: sets `approved=false` (allows new submissions after revert)
+- Multiple commands track the same approval state: SubmitTimeEntry, DeleteTimeentry, UpdateTimeEntry
+- Decline AFTER approval is valid workflow (and allows subsequent operations)
+
+### Event Assignment Domain
+
+**Stream ID**: `{restaurantId}-event-{eventId}` via `eventStreamId()` helper
+
+**Key Events**: EventCreated, EventCancelled, EventPlanned, EventReplanned, ClerkAssignedToEvent, ClerkUnassignedFromEvent
+
+**Inverse Operations**:
+- Assign/UnAssign share same stream ID
+- Use Set<string> for tracking assigned clerks
+- Assign guard: `if (has(clerkId)) throw "already.assigned"`
+- UnAssign guard: `if (!has(clerkId)) throw "not.assigned"`
+
+**Planning**: EventReplanned resets isPlanned to false (allows re-planning)
+
+### Activation/Deactivation Pattern
+
+**Complementary Commands**:
+- Both track same boolean state, validate opposite conditions
+- Activate: `if (active) throw "already.active"`
+- Deactivate: `if (!active) throw "not.active"`
+- Shared evolve handles BOTH events
+
+**Implementation Order**: events → STATE_VIEW → Activate → Deactivate
+
+**Examples**: OnlineReservation, Shift Publication
+
+### Dashboard Read Models
+
+**Characteristics**:
+- Handle 4 events: Create, Cancel, Assign, Unassign
+- JSONB assignees array
+- PRIMARY KEY on entity_id
+- Table naming: `active_{entity}_for_dashboard`
+
+**Test Pattern**: Create → Assignment/unassignment → Delete
+
+## Common Gotchas
+
+### Hooks Rewrite Files
+- Claude Code hooks extensively rewrite files after save
+- Always read files AFTER hook execution
+- Hooks add restaurantId, userId, enrich ContextEvents.ts
+
+### Auto-Generation Issues
+- Migration files may get auto-numbered incorrectly (V99) - renumber
+- Projection `canHandle` may be incomplete - verify against slice.json
+- Pre-generated routes may use wrong streamId
+
+### TypeScript Issues
+- Don't chain `.given()` directly on `DeciderSpecification.for()`
+- macOS filesystem case-insensitive, TypeScript imports case-sensitive
+- Use specific event union, NOT `ContextEvents` when handling subset
+- Don't add explicit type arguments to `DeciderSpecification.for()`
+
+### State Management
+- Always use explicit `break` in switch statements
+- Tests for state-dependent commands need prerequisite events in given
+- Paired commands share same stream
+- Use proper `initialState` function (not `{}`)
+
+### Knex/Database
+- `.insert({...}).del()` does NOT insert - it deletes
+- Use `.insert().onConflict().merge()` for upserts
+- Use `.where().update()` or `.where().delete()` for modifications
+
+### Specifications
+- Empty `specifications: []` → create tests covering event dependencies
+- Dependency-only events → include in `canHandle` as no-op (return `[]`)
+- Spec assertions may target different read model than slice's own
+- Pre-existing test failures don't block new slice implementation
+
+### Metadata Updates
+- Specs may be added to slice.json AFTER tests implemented
+- Verify executable tests exist before assuming new work needed
+- If tests exist and pass → metadata sync → commit as "chore: sync specifications"
+
+### Rate Limit Recovery
+- Agent context resets after hitting API rate limits ("You've hit your limit")
+- On resume, re-read slice.json and current implementation to verify state before continuing
+- Do not re-implement already-completed files — check for existing files first
+
+## Error Handling
+
+- HTTP 409 for conflicts, HTTP 500 for server errors
+- Business-friendly error codes (e.g., "already.active", "not.assigned")
+- German error messages typical in this codebase
+- Check errors most specific to most general (e.g., not_submitted → already_reverted → already_approved)
+
+## UI Documentation (ui-prompt.md)
+
+Each STATE_CHANGE slice should include `ui-prompt.md` with:
+1. Endpoint URL + HTTP method
+2. Payload example (realistic JSON)
+3. Required headers (correlation_id, Authorization)
+4. Response format (success/error)
+5. Field descriptions + API client code + curl commands
+
+For STATE_VIEW: include query endpoint docs + database table definition.

package/templates/frontend/prompt.md

@@ -14,16 +14,17 @@ Build React + TypeScript UI components from slice JSON definitions using establi
 7. A slice can define additional prompts as codegen/uiPrompt. any additional prompts defined in backend are hints for the implementation of the slice and have to be taken into account. If you use the additional prompt, add a line in progress.txt
 8. Write a short progress one liner after each step to progress.txt
 9. Analyze and Implement according to the Rest of the instructions in this file, make use of the skills in the skills directory, but also your previsously collected
-   knowledge. Make a list TODO list for what needs to be done. Also make sure to adjust the implementation according to the json definition. 
+   knowledge. Make a list TODO list for what needs to be done. Also make sure to adjust the implementation according to the json definition.
 10. The slice in the json is always true, the code follows what is defined in the json
 11. the slice is only 'Done' if APIs are implemented.
 12. make sure to read the ui-prompt.md in /backend/src/slices/<slice>
-13. Run quality checks ( npm run build, tsc ) - Attention - it´s enough to run the tests for the slice. Do not run all tests.
-15. Update the Slice in the index.json to status 'Done' and remove assignment
-16. If checks pass, commit ALL changes with message: `feat: [Slice Name]` and merge back to main as FF merge ( update
+13. Place the component where it belongs. If you can´t find a place, add a new page with /debug/<page> to showcase the component.
+14. Run quality checks ( npm run build, tsc ) - Attention - it´s enough to run the tests for the slice. Do not run all tests.
+16. Update the Slice in the index.json to status 'Done' and remove assignment
+17. If checks pass, commit ALL changes with message: `feat: [Slice Name]` and merge back to main as FF merge ( update
     first )
-17. Append your progress to `progress.txt` after each step in the iteration.
-18. append your new learnings to frontend/AGENTS.md in a compressed form, reusable for future iterations. Only add learnings if they are not already there.
+18. Append your progress to `progress.txt` after each step in the iteration.
+19. append your new learnings to frontend/AGENTS.md in a compressed form, reusable for future iterations. Only add learnings if they are not already there.
 20. Finish the iteration.
 
 ---
@@ -208,7 +209,7 @@ export function CreateEventDialog({ open, onOpenChange }) {
         if (!form.name) return toast.error("Name required");
         try {
             await createEvent.mutateAsync(form);
-            toast.success("Created");
+            toast.success("Planned");
             onOpenChange(false);
         } catch (err) {
             toast.error(`Error: ${err.message}`);

package/templates/frontend/src/App.tsx

@@ -23,7 +23,8 @@ const App = () => (
                     <Routes>
                         <Route path="/register" element={<Register/>}/>
                         <Route path="/auth" element={<Auth/>}/>
-                        <Route path="/" element={<ProtectedRoute><Dashboard/></ProtectedRoute>}/>
+                        {/*<Route path="/" element={<ProtectedRoute><Dashboard/></ProtectedRoute>}/>*/}
+                        <Route path="/" element={<Dashboard/>}/>
                         <Route path="*" element={<NotFound/>}/>
                     </Routes>
                 </BrowserRouter>

package/templates/frontend/src/contexts/AuthContext.tsx

@@ -21,10 +21,10 @@ const AuthContext = createContext<AuthContextType>({
 export const useAuth = () => useContext(AuthContext);
 
 const fetchAssignedTenant = async (userId: string): Promise<string | null> => {
-  try {
+  /*try {
     const { data, error } = await supabase
-      .from("slice_assigned_restaurants")
-      .select("restaurant_id")
+      .from("tenant_to_user_mapping")
+      .select("tenant_id")
       .eq("owner_id", userId)
       .maybeSingle();
 
@@ -32,11 +32,12 @@ const fetchAssignedTenant = async (userId: string): Promise<string | null> => {
       console.error("Error fetching assigned tenant:", error);
       return null;
     }
-    return data?.restaurant_id ?? null;
+    return data?.tenant_id ?? null;
   } catch (error) {
     console.error("Error fetching assigned tenant:", error);
     return null;
-  }
+  }*/
+    return null
 };
 
 export const AuthProvider = ({ children }: { children: ReactNode }) => {

package/templates/server.mjs

@@ -223,7 +223,7 @@ const server = createServer(async (req, res) => {
                         if (index == -1) {
                             sliceIndices.slices.push(sliceIndex);
                         } else {
-                            sliceIndices.slices[index] = sliceIndex;
+                            sliceIndices.slices[index] = {...sliceIndices.slices[index], ...sliceIndex};
                         }
                     });
                     writeFileSync(indexFile, JSON.stringify(sliceIndices, null, 2));
@@ -275,6 +275,7 @@ const server = createServer(async (req, res) => {
             const allSlices = indexData.slices.map(s => ({
                 title: s.slice,
                 status: s.status,
+                assignee: s.assignee,
                 id: s.id,
                 specifications: specificationsMap.get(s.id)
             }));