@magek/mcp-server 0.0.9 → 0.0.11

package/dist/prompts/cqrs-flow.js

@@ -94,10 +94,13 @@ npx magek new:entity <EntityName> --fields <field1:type1> <field2:type2> --reduc
 **Best Practices:**
 - One entity per aggregate root
 - Entities should only contain state derived from events
-- Use the \`@Reduces\` decorator to specify which events affect this entity
+- Use the \`@reduces\` decorator to specify which events affect this entity
+- **Always use \`evolve()\` for state updates** - it ensures immutability
 
 **Example:**
 \`\`\`typescript
+import { evolve } from '@magek/common'
+
 @Entity
 export class <EntityName> {
   public constructor(
@@ -106,20 +109,22 @@ export class <EntityName> {
     readonly field2: number,
   ) {}
 
-  @Reduces(<EventName>)
+  @reduces(<EventName>)
   public static reduce<EventName>(
     event: <EventName>,
     currentEntity?: <EntityName>
   ): <EntityName> {
-    return new <EntityName>(
-      event.entityId,
-      event.field1,
-      event.field2,
-    )
+    return evolve(currentEntity, {
+      id: event.entityId,
+      field1: event.field1,
+      field2: event.field2,
+    })
   }
 }
 \`\`\`
 
+> **Important:** Always use \`evolve()\` from \`@magek/common\` for state updates. It ensures immutability and handles both new entities (when \`currentEntity\` is undefined) and updates.
+
 ## Step 4: Define the Read Model
 
 Read models provide optimized query access to your data.
@@ -132,9 +137,12 @@ npx magek new:read-model <ReadModelName> --fields <field1:type1> <field2:type2>
 - Design read models for specific query use cases
 - Include only the fields needed for queries
 - You can have multiple read models projecting the same entity
+- **Use \`evolve()\` for projection updates** - same pattern as entities
 
 **Example:**
 \`\`\`typescript
+import { evolve } from '@magek/common'
+
 @ReadModel({
   authorize: 'all'
 })
@@ -145,16 +153,16 @@ export class <ReadModelName> {
     readonly field2: number,
   ) {}
 
-  @Projects(<EntityName>, 'id')
+  @projects(<EntityName>, 'id')
   public static project<EntityName>(
     entity: <EntityName>,
     currentReadModel?: <ReadModelName>
   ): ProjectionResult<<ReadModelName>> {
-    return new <ReadModelName>(
-      entity.id,
-      entity.field1,
-      entity.field2,
-    )
+    return evolve(currentReadModel, {
+      id: entity.id,
+      field1: entity.field1,
+      field2: entity.field2,
+    })
   }
 }
 \`\`\`

package/dist/prompts/troubleshooting.js

@@ -43,13 +43,18 @@ export * from './read-models/ProductReadModel'
 3. Ensure the reduce method returns a new entity instance (not mutating)
 
 \`\`\`typescript
+import { evolve } from '@magek/common'
+
 @Entity
 export class Product {
   // Make sure decorator references the actual event class
   @Reduces(ProductCreated)  // ✅ Correct
   @Reduces('ProductCreated') // ❌ Won't work
-  public static reduceProductCreated(event: ProductCreated): Product {
-    return new Product(event.entityId, event.name)
+  public static reduceProductCreated(event: ProductCreated, current?: Product): Product {
+    return evolve(current, {
+      id: event.entityId,
+      name: event.name,
+    })
   }
 }
 \`\`\`
@@ -78,8 +83,9 @@ export class Product {
 1. Check the \`authorize\` option in decorators:
    \`\`\`typescript
    @Command({ authorize: 'all' })  // Public access
-   @Command({ authorize: 'authenticated' })  // Requires login
-   @Command({ authorize: ['admin'] })  // Requires admin role
+   @Command({ authorize: [User] })  // Requires User role
+   @Command({ authorize: [Admin] })  // Requires Admin role
+   @Command({ authorize: [User, Admin] })  // Requires User OR Admin role
    \`\`\`
 
 2. If using authentication, ensure JWT token is valid
@@ -138,6 +144,39 @@ export class Product {
    }
    \`\`\`
 
+### Reducer returns incorrect state
+
+**Symptoms:**
+- Entity state not updating as expected
+- State appears corrupted or missing fields
+- Immutability violations
+
+**Solutions:**
+1. **Always use \`evolve()\` for state updates** - never mutate directly:
+   \`\`\`typescript
+   // ✅ Correct - use evolve()
+   return evolve(current, { name: event.newName })
+
+   // ❌ Incorrect - mutates state directly
+   current.name = event.newName
+   return current
+
+   // ❌ Incorrect - manual construction doesn't handle undefined
+   return new Product(event.id, event.name)
+   \`\`\`
+
+2. Handle the case when \`current\` is undefined (new entity):
+   \`\`\`typescript
+   // evolve() handles this automatically
+   return evolve(current, { id: event.id, name: event.name })
+   \`\`\`
+
+3. For update-only reducers, skip if entity doesn't exist:
+   \`\`\`typescript
+   if (!current) return ReducerAction.Skip
+   return evolve(current, { name: event.newName })
+   \`\`\`
+
 ---
 
 ## Development Server Issues

package/docs/advanced/custom-adapters.md

@@ -0,0 +1,371 @@
+# Custom Adapters
+
+Magek uses an adapter pattern to abstract away database and storage implementation details. This allows you to use different storage backends without modifying your application code. This guide explains how to create custom adapters for the Magek framework.
+
+## Overview
+
+Magek has three types of adapters:
+
+1. **Event Store Adapter** - Stores events and entity snapshots for event sourcing
+2. **Read Model Store Adapter** - Stores and queries read model projections
+3. **Session Store Adapter** - Manages WebSocket connections and GraphQL subscriptions
+
+Each adapter type has a well-defined interface that you must implement. The framework provides built-in adapters for NeDB (file-based) and in-memory storage.
+
+## Adapter Interfaces
+
+### Event Store Adapter
+
+The `EventStoreAdapter` interface (defined in `@magek/common`) handles event sourcing operations:
+
+```typescript
+interface EventStoreAdapter {
+  // Convert raw data to EventEnvelope objects
+  rawToEnvelopes(rawEvents: unknown): Array<EventEnvelope>
+
+  // Streaming methods (optional - can throw "not implemented")
+  rawStreamToEnvelopes(config: MagekConfig, context: unknown, dedupEventStream: EventStream): Array<EventEnvelope>
+  dedupEventStream(config: MagekConfig, rawEvents: unknown): Promise<EventStream>
+  produce(entityName: string, entityID: UUID, eventEnvelopes: Array<EventEnvelope>, config: MagekConfig): Promise<void>
+
+  // Core event operations
+  forEntitySince(config: MagekConfig, entityTypeName: string, entityID: UUID, since?: string): Promise<Array<EventEnvelope>>
+  latestEntitySnapshot(config: MagekConfig, entityTypeName: string, entityID: UUID): Promise<EntitySnapshotEnvelope | undefined>
+  store(eventEnvelopes: Array<NonPersistedEventEnvelope>, config: MagekConfig): Promise<Array<EventEnvelope>>
+  storeSnapshot(snapshotEnvelope: NonPersistedEntitySnapshotEnvelope, config: MagekConfig): Promise<EntitySnapshotEnvelope>
+
+  // Search and pagination
+  search(config: MagekConfig, parameters: EventSearchParameters): Promise<Array<EventSearchResponse>>
+  searchEntitiesIDs(config: MagekConfig, limit: number, afterCursor: Record<string, string> | undefined, entityTypeName: string): Promise<PaginatedEntitiesIdsResult>
+
+  // Dispatch tracking
+  storeDispatched(eventEnvelope: EventEnvelope, config: MagekConfig): Promise<boolean>
+
+  // Deletion operations
+  findDeletableEvent(config: MagekConfig, parameters: EventDeleteParameters): Promise<Array<EventEnvelopeFromDatabase>>
+  findDeletableSnapshot(config: MagekConfig, parameters: SnapshotDeleteParameters): Promise<Array<EntitySnapshotEnvelopeFromDatabase>>
+  deleteEvent(config: MagekConfig, events: Array<EventEnvelopeFromDatabase>): Promise<void>
+  deleteSnapshot(config: MagekConfig, snapshots: Array<EntitySnapshotEnvelopeFromDatabase>): Promise<void>
+
+  // Health check (optional)
+  healthCheck?: {
+    isUp(config: MagekConfig): Promise<boolean>
+    details(config: MagekConfig): Promise<unknown>
+    urls(config: MagekConfig): Promise<Array<string>>
+  }
+
+  // Async event processing (optional)
+  fetchUnprocessedEvents?(config: MagekConfig): Promise<Array<EventEnvelope>>
+  markEventProcessed?(config: MagekConfig, eventId: UUID): Promise<void>
+}
+```
+
+### Read Model Store Adapter
+
+The `ReadModelStoreAdapter` interface handles read model projections:
+
+```typescript
+interface ReadModelStoreAdapter {
+  // Fetch a specific read model by ID
+  fetch<TReadModel extends ReadModelInterface>(
+    config: MagekConfig,
+    readModelName: string,
+    readModelID: UUID,
+    sequenceKey?: SequenceKey
+  ): Promise<ReadOnlyNonEmptyArray<TReadModel> | undefined>
+
+  // Search read models with filters, sorting, and pagination
+  search<TReadModel extends ReadModelInterface>(
+    config: MagekConfig,
+    readModelName: string,
+    filters: FilterFor<unknown>,
+    sortBy?: SortFor<unknown>,
+    limit?: number,
+    afterCursor?: unknown,
+    paginatedVersion?: boolean,
+    select?: ProjectionFor<TReadModel>
+  ): Promise<Array<TReadModel> | ReadModelListResult<TReadModel>>
+
+  // Store or update a read model
+  store<TReadModel extends ReadModelInterface>(
+    config: MagekConfig,
+    readModelName: string,
+    readModel: ReadModelStoreEnvelope<TReadModel>
+  ): Promise<ReadModelStoreEnvelope<TReadModel>>
+
+  // Delete a read model
+  delete(config: MagekConfig, readModelName: string, readModelID: UUID): Promise<void>
+
+  // Convert raw data to envelopes
+  rawToEnvelopes<TReadModel extends ReadModelInterface>(
+    config: MagekConfig,
+    rawReadModels: unknown
+  ): Promise<Array<ReadModelStoreEnvelope<TReadModel>>>
+
+  // Health check (optional)
+  healthCheck?: {
+    isUp(config: MagekConfig): Promise<boolean>
+    details(config: MagekConfig): Promise<unknown>
+    urls(config: MagekConfig): Promise<Array<string>>
+  }
+}
+```
+
+### Session Store Adapter
+
+The `SessionStoreAdapter` interface manages real-time connections:
+
+```typescript
+interface SessionStoreAdapter {
+  // Connection management
+  storeConnection(config: MagekConfig, connectionId: UUID, connectionData: Record<string, any>): Promise<void>
+  fetchConnection(config: MagekConfig, connectionId: UUID): Promise<Record<string, any> | undefined>
+  deleteConnection(config: MagekConfig, connectionId: UUID): Promise<void>
+
+  // Subscription management
+  storeSubscription(config: MagekConfig, connectionId: UUID, subscriptionId: UUID, subscriptionData: Record<string, any>): Promise<void>
+  fetchSubscription(config: MagekConfig, subscriptionId: UUID): Promise<Record<string, any> | undefined>
+  deleteSubscription(config: MagekConfig, connectionId: UUID, subscriptionId: UUID): Promise<void>
+
+  // Bulk operations
+  fetchSubscriptionsForConnection(config: MagekConfig, connectionId: UUID): Promise<Array<Record<string, any>>>
+  deleteSubscriptionsForConnection(config: MagekConfig, connectionId: UUID): Promise<void>
+  fetchSubscriptionsByClassName(config: MagekConfig, className: string): Promise<Array<SubscriptionEnvelope>>
+
+  // Health check (optional)
+  healthCheck?: {
+    isUp(config: MagekConfig): Promise<boolean>
+    details(config: MagekConfig): Promise<unknown>
+    urls(config: MagekConfig): Promise<Array<string>>
+  }
+}
+```
+
+## Implementation Guide
+
+### Package Structure
+
+Create your adapter package with this structure:
+
+```
+adapters/<database>/<adapter-type>/
+├── src/
+│   ├── index.ts              # Export adapter singleton
+│   └── <database>-<type>.ts  # Implementation
+├── test/
+│   ├── expect.ts             # Test utilities
+│   └── <adapter>.test.ts     # Tests
+├── package.json
+├── tsconfig.json
+├── tsconfig.test.json
+├── tsconfig.eslint.json
+├── eslint.config.mjs
+└── .mocharc.yml
+```
+
+### Package Naming Convention
+
+Use this naming pattern: `@magek/adapter-{type}-{database}`
+
+Examples:
+- `@magek/adapter-event-store-nedb`
+- `@magek/adapter-read-model-store-memory`
+- `@magek/adapter-session-store-redis`
+
+### Implementing the Event Store
+
+Key implementation considerations:
+
+1. **Event Storage**: Store events with `kind: 'event'` and snapshots with `kind: 'snapshot'`
+2. **Timestamps**: Generate `createdAt` when storing events
+3. **Soft Deletes**: Events should be soft-deleted by setting `deletedAt` and clearing `value`
+4. **Snapshots**: Hard delete snapshots when requested
+5. **Dispatch Tracking**: Track which events have been dispatched to prevent duplicate processing
+6. **Async Processing** (optional): Implement `fetchUnprocessedEvents` and `markEventProcessed` for polling-based event dispatch
+
+Example implementation pattern:
+
+```typescript
+import { EventStoreAdapter } from '@magek/common'
+
+const eventRegistry = new YourEventRegistry()
+
+export const eventStore: EventStoreAdapter = {
+  rawToEnvelopes: (rawEvents) => rawEvents as Array<EventEnvelope>,
+
+  forEntitySince: async (config, entityTypeName, entityID, since) => {
+    const query = {
+      entityTypeName,
+      entityID,
+      kind: 'event',
+      createdAt: { $gt: since || new Date(0).toISOString() },
+      deletedAt: { $exists: false },
+    }
+    return eventRegistry.query(query)
+  },
+
+  store: async (eventEnvelopes, config) => {
+    const persisted = []
+    for (const envelope of eventEnvelopes) {
+      const withTimestamp = { ...envelope, createdAt: new Date().toISOString() }
+      await eventRegistry.store(withTimestamp)
+      persisted.push(withTimestamp)
+    }
+    return persisted
+  },
+
+  // ... implement other methods
+}
+```
+
+### Implementing the Read Model Store
+
+Key implementation considerations:
+
+1. **Optimistic Concurrency**: Check version before updates, throw `OptimisticConcurrencyUnexpectedVersionError` on conflicts
+2. **Filter Support**: Implement filtering operations (eq, ne, lt, gt, lte, gte, in, contains, etc.)
+3. **Sorting**: Support multi-field sorting with ASC/DESC
+4. **Pagination**: Implement cursor-based pagination
+5. **Field Projection**: Support selecting specific fields
+
+Filter operations to support:
+
+| Operation | Description | Example |
+|-----------|-------------|---------|
+| `eq` | Equals | `{ name: { eq: 'John' } }` |
+| `ne` | Not equals | `{ status: { ne: 'deleted' } }` |
+| `lt` | Less than | `{ age: { lt: 18 } }` |
+| `gt` | Greater than | `{ price: { gt: 100 } }` |
+| `lte` | Less than or equal | `{ age: { lte: 65 } }` |
+| `gte` | Greater than or equal | `{ rating: { gte: 4 } }` |
+| `in` | In array | `{ status: { in: ['active', 'pending'] } }` |
+| `isDefined` | Field exists | `{ email: { isDefined: true } }` |
+| `contains` | String contains | `{ name: { contains: 'smith' } }` |
+| `beginsWith` | String starts with | `{ name: { beginsWith: 'Dr.' } }` |
+| `regex` | Regular expression | `{ email: { regex: '@example.com$' } }` |
+| `iRegex` | Case-insensitive regex | `{ name: { iRegex: 'john' } }` |
+| `includes` | Array includes | `{ tags: { includes: 'featured' } }` |
+| `and` | Logical AND | `{ and: [filter1, filter2] }` |
+| `or` | Logical OR | `{ or: [filter1, filter2] }` |
+| `not` | Logical NOT | `{ not: { status: { eq: 'deleted' } } }` |
+
+### Implementing the Session Store
+
+Key implementation considerations:
+
+1. **Connection Indexing**: Index connections by ID for fast lookup
+2. **Subscription Indexing**: Index subscriptions by connection ID and class name
+3. **Cleanup**: Ensure deleting a connection also cleans up its subscriptions
+4. **Class Name Queries**: Support fetching subscriptions by read model class name
+
+### Health Checks
+
+Implement health checks to support monitoring:
+
+```typescript
+healthCheck: {
+  isUp: async (config) => {
+    try {
+      // Test database connectivity
+      await database.ping()
+      return true
+    } catch {
+      return false
+    }
+  },
+
+  details: async (config) => ({
+    type: 'your-database',
+    status: 'healthy',
+    eventsCount: await database.count('events'),
+  }),
+
+  urls: async (config) => ['your-database://connection-string'],
+}
+```
+
+### Async Event Processing (Optional)
+
+Magek supports async event processing through polling. When implemented, the server polls for unprocessed events and dispatches them in batches, preventing duplicate processing.
+
+#### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `eventPollingIntervalMs` | 1000 | Milliseconds between polling cycles |
+| `eventProcessingBatchSize` | 100 | Maximum events per batch |
+
+#### Implementation Pattern
+
+```typescript
+// Track cursor position
+let processingCursor: string = new Date(0).toISOString()
+
+async function fetchUnprocessedEvents(config: MagekConfig): Promise<Array<EventEnvelope>> {
+  const query = {
+    kind: 'event',
+    deletedAt: { $exists: false },
+    processedAt: { $exists: false },
+    createdAt: { $gt: processingCursor },
+  }
+  return database.query(query, { sort: 'createdAt', limit: config.eventProcessingBatchSize })
+}
+
+async function markEventProcessed(config: MagekConfig, eventId: UUID): Promise<void> {
+  const event = await database.findById(eventId)
+  if (!event) return
+  await database.update(eventId, { processedAt: new Date().toISOString() })
+  processingCursor = event.createdAt
+}
+```
+
+#### Important Considerations
+
+1. **Remove Synchronous Dispatch**: When implementing async processing, remove any `eventDispatcher()` call from your `store()` method
+2. **Cursor Persistence**: Persistent adapters should persist the cursor; in-memory can use a variable
+3. **Event Ordering**: Process events in `createdAt` order for consistency
+4. **Optional Implementation**: If not implemented, the server uses synchronous dispatch
+
+## Configuration
+
+To use your custom adapter, configure it in your Magek application:
+
+```typescript
+import { MagekConfig } from '@magek/core'
+import { eventStore } from '@magek/adapter-event-store-your-db'
+import { readModelStore } from '@magek/adapter-read-model-store-your-db'
+import { sessionStore } from '@magek/adapter-session-store-your-db'
+
+const config = new MagekConfig('production')
+
+// Set custom adapters
+;(config as any).eventStoreAdapter = eventStore
+;(config as any).readModelStoreAdapter = readModelStore
+;(config as any).sessionStoreAdapter = sessionStore
+```
+
+## Best Practices
+
+1. **Export Singleton Instances**: Export pre-configured adapter instances for easy usage:
+   ```typescript
+   export const eventStore: EventStoreAdapter = { /* ... */ }
+   ```
+
+2. **Use Logging**: Use `getLogger(config, 'AdapterName#methodName')` for consistent logging
+
+3. **Handle Errors Gracefully**: Wrap database errors in appropriate Magek error types
+
+4. **Support TypeScript**: Export types and use generics where appropriate
+
+5. **Write Comprehensive Tests**: Test all interface methods including edge cases
+
+6. **Document Connection Requirements**: Clearly document any environment variables or configuration needed
+
+## Example Adapters
+
+For reference implementations, see:
+
+- **NeDB Adapters** (file-based): `adapters/nedb/`
+- **Memory Adapters** (in-memory): `adapters/memory/`
+
+These implementations demonstrate all required patterns and can serve as templates for your custom adapters.

package/docs/advanced/framework-packages.md

@@ -3,15 +3,108 @@ title: "Framework Packages"
 group: "Advanced"
 ---
 
-# Framework packages
-The framework is already splitted into different packages:
+# Framework Packages
 
-## Framework Core
+Magek is organized as a monorepo with these packages:
 
-The `framework-core` package includes the most important components of the framework abstraction. It can be seen as skeleton or the main architecture of the framework.
+## Core Packages
 
-The package defines the specification of how should a Magek application work without taking into account the specific providers that could be used. Every Magek provider package is based on the components that the framework core needs in order to work on the platform.
+### @magek/core
 
-## Common
+The event sourcing engine with CQRS patterns, GraphQL generation, and decorators. This is the main package that powers Magek applications.
 
-The `common` package includes the types that define the domain of the Magek framework. It defines domain concepts like an `Event`, a `Command` or a `Role`.
+```bash
+npm install @magek/core
+```
+
+### @magek/common
+
+Shared types, utilities, and helper functions used across the framework. Includes essential helpers like:
+
+- `evolve()` - Immutable state updates for entities and read models
+- `UUID` - Unique identifier generation
+- `createInstance()` - Instantiate classes from raw objects
+
+```bash
+npm install @magek/common
+```
+
+## Development Tools
+
+### @magek/cli
+
+Command-line tool for scaffolding projects, generating components, and running the development server.
+
+```bash
+# Generate new components
+npx magek new:command CreateProduct
+npx magek new:event ProductCreated
+npx magek new:entity Product
+npx magek new:read-model ProductReadModel
+
+# Start development server
+npx magek start
+```
+
+### @magek/server
+
+Fastify-based runtime for local development. Provides:
+
+- Hot reloading
+- GraphQL playground
+- Local event store and read model storage
+
+### create-magek
+
+Project scaffolding tool for creating new Magek applications with a single command.
+
+```bash
+npx create-magek my-app
+cd my-app
+npm install
+npx magek start
+```
+
+## Storage Adapters
+
+Adapters provide pluggable storage backends for Magek applications. The NeDB adapters are used for local development.
+
+### @magek/adapter-event-store-nedb
+
+NeDB-based event store adapter. Stores events in a local file-based database, ideal for development and testing.
+
+```bash
+npm install @magek/adapter-event-store-nedb
+```
+
+### @magek/adapter-read-model-store-nedb
+
+NeDB-based read model store adapter. Stores read model projections locally.
+
+```bash
+npm install @magek/adapter-read-model-store-nedb
+```
+
+### @magek/adapter-session-store-nedb
+
+NeDB-based session store adapter. Manages WebSocket connections and subscriptions for real-time features.
+
+```bash
+npm install @magek/adapter-session-store-nedb
+```
+
+## AI Integration
+
+### @magek/mcp-server
+
+Model Context Protocol (MCP) server that provides documentation, CLI reference, and guided prompts for AI coding assistants. Use this to integrate Magek knowledge into your AI-powered development workflow.
+
+```bash
+npx @magek/mcp-server
+```
+
+Features:
+- Documentation resources accessible via MCP
+- CQRS implementation guide prompt
+- Troubleshooting assistance prompt
+- CLI command reference

package/docs/advanced/sensor.md

@@ -3,8 +3,117 @@ title: "Sensors"
 group: "Advanced"
 ---
 
-# Sensor
+# Sensors
+
+Sensors are monitoring components in Magek that track and report the status of your application. They provide visibility into application health and performance through HTTP endpoints.
+
+## Overview
+
+Magek's sensor system allows you to:
+
+- Monitor the health status of application components
+- Expose status information via REST endpoints
+- Create custom monitoring for your own services
+- Integrate with external monitoring tools and dashboards
+
+## Health Sensors
+
+The primary sensor type in Magek is the **Health Sensor**, which monitors application health and exposes status via the `/sensor/health/` endpoint.
+
+### Built-in Health Indicators
+
+Magek provides these built-in health indicators:
+
+| Indicator | Endpoint | Description |
+|-----------|----------|-------------|
+| `magek` | `/sensor/health/magek` | Overall application health |
+| `magek/function` | `/sensor/health/magek/function` | GraphQL function status, CPU, and memory |
+| `magek/database` | `/sensor/health/magek/database` | Database availability |
+| `magek/database/events` | `/sensor/health/magek/database/events` | Event store health |
+| `magek/database/readmodels` | `/sensor/health/magek/database/readmodels` | Read model store health |
+
+### Quick Start
+
+Enable health sensors in your configuration:
+
+```typescript
+Magek.configure('local', (config: MagekConfig): void => {
+  config.appName = 'my-app'
+  config.runtime = ServerRuntime
+
+  // Enable all health indicators
+  Object.values(config.sensorConfiguration.health.magek).forEach((indicator) => {
+    indicator.enabled = true
+  })
+})
+```
+
+Then access health status at `http://localhost:3000/sensor/health/`.
+
+### Creating Custom Health Sensors
+
+Use the `@HealthSensor` decorator to create custom health indicators:
+
+```typescript
+import {
+  MagekConfig,
+  HealthIndicatorResult,
+  HealthIndicatorMetadata,
+  HealthStatus,
+} from '@magek/common'
+import { HealthSensor } from '@magek/core'
+
+@HealthSensor({
+  id: 'external-api',
+  name: 'External API Health',
+  enabled: true,
+  details: true,
+})
+export class ExternalApiHealthIndicator {
+  public async health(
+    config: MagekConfig,
+    metadata: HealthIndicatorMetadata
+  ): Promise<HealthIndicatorResult> {
+    // Check your external service
+    const isHealthy = await checkExternalApi()
+
+    return {
+      status: isHealthy ? HealthStatus.UP : HealthStatus.DOWN,
+      details: {
+        lastCheck: new Date().toISOString(),
+      },
+    }
+  }
+}
+```
+
+### Health Statuses
+
+| Status | Description |
+|--------|-------------|
+| `UP` | Component is working as expected |
+| `PARTIALLY_UP` | Component has reduced functionality |
+| `DOWN` | Component is not working |
+| `OUT_OF_SERVICE` | Component is temporarily unavailable |
+| `UNKNOWN` | Component state cannot be determined |
+
+### HTTP Response Codes
+
+- **200 OK**: All components are healthy (`UP`)
+- **503 Service Unavailable**: One or more components are unhealthy
+
+## Configuration Options
+
+Each health indicator supports these options:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `id` | `string` | required | Unique identifier (used in URL path) |
+| `name` | `string` | required | Display name in responses |
+| `enabled` | `boolean` | `false` | Enable/disable the indicator |
+| `details` | `boolean` | `true` | Include detailed information |
+| `showChildren` | `boolean` | `true` | Include child components |
 
 ## Related Topics
 
-- [Sensor Health](health/sensor-health.md) - Health monitoring and indicators
+- [Health Sensor Details](health/sensor-health.md) - Complete health monitoring guide with all configuration options, response formats, and examples

package/docs/architecture/best-practices.md

@@ -0,0 +1,133 @@
+---
+title: "Best Practices"
+group: "Architecture"
+---
+
+# Best Practices
+
+Quick reference for writing idiomatic Magek code.
+
+## State Updates with `evolve()`
+
+**Always use `evolve()` for entity and read model state updates.**
+
+The `evolve()` helper from `@magek/common`:
+- Creates immutable copies (never mutates)
+- Handles undefined state (new entities)
+- Provides type safety
+
+```typescript
+import { evolve } from '@magek/common'
+```
+
+### Entity Reducers
+
+```typescript
+// DO: Use evolve()
+@reduces(ProductCreated)
+public static reduceProductCreated(event: ProductCreated, current?: Product): Product {
+  return evolve(current, {
+    id: event.entityID(),
+    name: event.name,
+    price: event.price,
+  })
+}
+
+// DON'T: Manual construction
+public static reduceProductCreated(event: ProductCreated): Product {
+  return new Product(event.entityID(), event.name, event.price)  // Missing immutability!
+}
+```
+
+### Read Model Projections
+
+```typescript
+// DO: Use evolve()
+@projects(Product, 'id')
+public static projectProduct(entity: Product, current?: ProductReadModel): ProjectionResult<ProductReadModel> {
+  return evolve(current, {
+    id: entity.id,
+    displayName: entity.name,
+  })
+}
+```
+
+## Common Patterns
+
+### Creating vs Updating Entities
+
+`evolve()` handles both cases automatically:
+- When `current` is `undefined` → creates a new entity
+- When `current` exists → updates with the provided changes
+
+```typescript
+@reduces(ProductCreated)
+public static reduceProductCreated(event: ProductCreated, current?: Product): Product {
+  // Works for both new entities and updates
+  return evolve(current, {
+    id: event.entityID(),
+    name: event.name,
+  })
+}
+```
+
+### Providing Defaults for New Entities
+
+When creating entities, you can provide default values:
+
+```typescript
+return evolve(undefined, { id: event.id, name: event.name }, { status: 'active', createdAt: new Date() })
+```
+
+The third parameter provides defaults that are applied when `current` is `undefined`.
+
+### Partial Updates
+
+For update events, only include the fields that change:
+
+```typescript
+@reduces(ProductRenamed)
+public static reduceProductRenamed(event: ProductRenamed, current?: Product): Product {
+  if (!current) return ReducerAction.Skip
+  return evolve(current, { name: event.newName })
+}
+```
+
+## Anti-Patterns
+
+### Mutating State Directly
+
+```typescript
+// NEVER do this - breaks immutability
+current.balance += amount
+return current
+```
+
+### Using Spread Operator Instead of evolve()
+
+```typescript
+// Avoid - evolve() is clearer and handles edge cases
+return { ...current, balance: current.balance + amount }
+```
+
+### Constructing Entities Manually
+
+```typescript
+// Avoid - doesn't handle undefined current state properly
+return new Product(event.id, event.name, event.price)
+```
+
+## Utility Helpers Reference
+
+| Helper | Import | Purpose |
+|--------|--------|---------|
+| `evolve(current, changes)` | `@magek/common` | Immutable state updates |
+| `evolve(undefined, changes, defaults)` | `@magek/common` | Create with defaults |
+| `UUID.generate()` | `@magek/common` | Generate unique IDs |
+| `createInstance(Class, raw)` | `@magek/common` | Instantiate class from raw object |
+
+## Further Reading
+
+- [Entity](./entity.md) - Learn about entity reducers
+- [Read Model](./read-model.md) - Learn about projections
+- [Event](./event.md) - Learn about events and the `entityID()` method

package/docs/architecture/command.md

@@ -5,7 +5,7 @@ group: "Architecture"
 
 # Command
 
-Commands are any action a user performs on your application. For example, `RemoveItemFromCart`, `RatePhoto` or `AddCommentToPost`. They express the intention of an user, and they are the main interaction mechanism of your application. They are a similar to the concept of a **request on a REST API**. Command issuers can also send data on a command as parameters.
+Commands are any action a user performs on your application. For example, `RemoveItemFromCart`, `RatePhoto` or `AddCommentToPost`. They express the intention of an user, and they are the main interaction mechanism of your application. They are similar to the concept of a **request on a REST API**. Command issuers can also send data on a command as parameters.
 
 ## Creating a command
 
@@ -82,7 +82,7 @@ export class CreateProduct {
 
   public static async handle(command: CreateProduct, register: Register): Promise<void> {
     // highlight-next-line
-    register.event(new ProductCreated(/*...*/))
+    register.events(new ProductCreated(/*...*/))
   }
 }
 ```
@@ -91,7 +91,7 @@ For more details about events and the register parameter, see the [`Events`](/ar
 
 ### Returning a value
 
-The command handler function can return a value. This value will be the response of the GraphQL mutation. By default, the command handler function expects you to return a `void` as a return type. Since GrahpQL does not have a `void` type, the command handler function returns `true` when called through the GraphQL. This is because the GraphQL specification requires a response, and `true` is the most appropriate value to represent a successful execution with no return value.
+The command handler function can return a value. This value will be the response of the GraphQL mutation. By default, the command handler function expects you to return a `void` as a return type. Since GraphQL does not have a `void` type, the command handler function returns `true` when called through the GraphQL. This is because the GraphQL specification requires a response, and `true` is the most appropriate value to represent a successful execution with no return value.
 
 If you want to return a value, you need to:
 1. Change the return type of the handler function
@@ -115,7 +115,7 @@ export class CreateProduct {
   // highlight-next-line
   @returns(type => String)
   public static async handle(command: CreateProduct, register: Register): Promise<string> {
-    register.event(new ProductCreated(/*...*/))
+    register.events(new ProductCreated(/*...*/))
     // highlight-next-line
     return 'Product created!'
   }
@@ -296,7 +296,7 @@ You can read more about this on the [Authorization section](/security/authorizat
 
 ## Submitting a command
 
-Magek commands are accessible to the outside world as GraphQL mutations. GrahpQL fits very well with Magek's CQRS approach because it has two kinds of operations: Mutations and Queries. Mutations are actions that modify the server-side data, just like commands.
+Magek commands are accessible to the outside world as GraphQL mutations. GraphQL fits very well with Magek's CQRS approach because it has two kinds of operations: Mutations and Queries. Mutations are actions that modify the server-side data, just like commands.
 
 Magek automatically creates one mutation per command. The framework infers the mutation input type from the command fields. Given this `CreateProduct` command:
 
@@ -365,3 +365,10 @@ Despite you can place commands, and other Magek files, in any directory, we stro
 │   ├── index.ts
 │   └── read-models
 ```
+
+## Related Topics
+
+- [Events](./event.md) - Events registered by command handlers
+- [Event Handlers](./event-handler.md) - Side effects triggered by events
+- [Authorization](../security/authorization.md) - Securing commands with roles
+- [GraphQL API](../graphql.md) - How commands become mutations

package/docs/architecture/entity.md

@@ -39,9 +39,25 @@ export class EntityName {
 }
 ```
 
+## Working with Entity State
+
+Magek entities use immutable state updates. Always use the `evolve()` helper from `@magek/common`:
+
+```typescript
+import { evolve } from '@magek/common'
+
+// In your reducer:
+return evolve(currentEntityState, {
+  fieldA: newValue,
+  fieldB: anotherValue,
+})
+```
+
+> **Why `evolve()`?** It ensures immutability, handles undefined state for new entities, and provides clear, consistent patterns across your codebase. See [Best Practices](./best-practices.md) for more details.
+
 ## The reduce function
 
-In order to tell Magek how to reduce the events, you must define a static method decorated with the `@reduces` decorator. This method will be called by the framework every time an event of the specified type is emitted. The reducer method must return a new entity instance with the current state of the entity.
+In order to tell Magek how to reduce the events, you must define a static method decorated with the `@reduces` decorator. This method will be called by the framework every time an event of the specified type is emitted. The reducer method must return a new entity instance with the current state of the entity using `evolve()`.
 
 ```typescript title="src/entities/entity-name.ts"
 @Entity
@@ -212,3 +228,9 @@ Entities live within the entities directory of the project source: `<project-roo
 │   ├── index.ts
 │   └── read-models
 ```
+
+## Related Topics
+
+- [Best Practices](./best-practices.md) - Recommended patterns for `evolve()` and state management
+- [Events](./event.md) - Events that trigger entity reducers
+- [Read Models](./read-model.md) - Project entities into query-optimized views

package/docs/architecture/event-driven.md

@@ -13,7 +13,7 @@ Two patterns influence the Magek's event-driven architecture: Command-Query Resp
 
 As you can see in the diagram, Magek applications consist of four main building blocks: `Commands`, `Events`, `Entities`, and `Read Models`. `Commands` and `Read Models` are the public interface of the application, while `Events` and `Entities` are private implementation details. With Magek, clients submit `Commands`, query the `Read Models`, or subscribe to them for receiving real-time updates thanks to the out of the box [GraphQL API](/graphql)
 
-Magek applications are event-driven and event-sourced so, **the source of truth is the whole history of events**. When a client submits a command, Magek _wakes up_ and handles it throght `Command Handlers`. As part of the process, some `Events` may be _registered_ as needed.
+Magek applications are event-driven and event-sourced so, **the source of truth is the whole history of events**. When a client submits a command, Magek _wakes up_ and handles it through `Command Handlers`. As part of the process, some `Events` may be _registered_ as needed.
 
 On the other side, the framework caches the current state by automatically _reducing_ all the registered events into `Entities`. You can also _react_ to events via `Event Handlers`, triggering side effect actions to certain events. Finally, `Entities` are not directly exposed, they are transformed or _projected_ into `ReadModels`, which are exposed to the public.
 

package/docs/architecture/read-model.md

@@ -5,7 +5,7 @@ group: "Architecture"
 
 # Read model
 
-A read model contains the data of your application that is exposed to the client through the GraphQL API. It's a _projection_ of one or more entities, so you dont have to directly expose them to the client. Magek generates the GraphQL queries that allow you to fetch your read models.
+A read model contains the data of your application that is exposed to the client through the GraphQL API. It's a _projection_ of one or more entities, so you don't have to directly expose them to the client. Magek generates the GraphQL queries that allow you to fetch your read models.
 
 In other words, Read Models are cached data optimized for read operations. They're updated reactively when [Entities](./entity.md) are updated after reducing [events](./event.md).
 
@@ -43,7 +43,7 @@ export class ReadModelName {
 
 ## The projection function
 
-The projection function is a static method decorated with the `@projects` decorator. It is used to define how the read model is updated when an entity is modified. he projection function must return a new instance of the read model, it receives two arguments:
+The projection function is a static method decorated with the `@projects` decorator. It is used to define how the read model is updated when an entity is modified. The projection function must return a new instance of the read model, it receives two arguments:
 
 - `entity`: The entity that has been modified
 - `current?`: The current read model instance. If it's the first time the read model is created, this argument will be `undefined`
@@ -233,7 +233,7 @@ export class UserReadModel {
   @projects(User, 'id')
   public static projectUser(entity: User, current?: UserReadModel): ProjectionResult<UserReadModel>  {
     if (entity.deleted) {
-      return ReadModelAction.Delete
+      return ProjectionAction.Delete
     }
     return evolve(current, { id: entity.id, username: entity.username })
   }
@@ -259,7 +259,7 @@ export class UserReadModel {
   @projects(User, 'id')
   public static projectUser(entity: User, current?: UserReadModel): ProjectionResult<UserReadModel>  {
     if (!entity.modified) {
-      return ReadModelAction.Nothing
+      return ProjectionAction.Skip
     }
     return evolve(current, { id: entity.id, username: entity.username })
   }
@@ -357,7 +357,7 @@ And here is an example of the corresponding JSON response when this query is exe
 }
 ```
 
-Notice that getters are not cached in the read models database, so the getters will be executed every time you include these fields in the queries. If access to nested queries is frequent or the size of the responses are big, you could improe your API response performance by querying the read models separately and joining the results in the client application.
+Notice that getters are not cached in the read models database, so the getters will be executed every time you include these fields in the queries. If access to nested queries is frequent or the size of the responses are big, you could improve your API response performance by querying the read models separately and joining the results in the client application.
 
 ## Authorizing a read model
 
@@ -396,7 +396,7 @@ You can read more about this on the [Authorization section](/security/authorizat
 
 ## Querying a read model
 
-Magek read models are accessible to the outside world through GraphQL queries. GrahpQL fits very well with Magek's CQRS approach because it has two kinds of reading operations: Queries and Subscriptions. They are read-only operations that do not modify the state of the application. Magek uses them to fetch data from the read models.
+Magek read models are accessible to the outside world through GraphQL queries. GraphQL fits very well with Magek's CQRS approach because it has two kinds of reading operations: Queries and Subscriptions. They are read-only operations that do not modify the state of the application. Magek uses them to fetch data from the read models.
 
 Magek automatically creates the queries and subscriptions for each read model. You can use them to fetch the data from the read models. For example, given the following read model:
 
@@ -505,3 +505,10 @@ Despite you can place your read models in any directory, we strongly recommend y
 │   ├── index.ts
 │   └── read-models
 ```
+
+## Related Topics
+
+- [Best Practices](./best-practices.md) - Recommended patterns for `evolve()` and projections
+- [Entities](./entity.md) - Source data for read model projections
+- [Queries](./queries.md) - Alternative approach for complex query logic
+- [GraphQL API](../graphql.md) - How read models are exposed via GraphQL

package/docs/docs-index.json

@@ -1,4 +1,10 @@
 [
+  {
+    "uri": "magek://docs/advanced/custom-adapters",
+    "path": "advanced/custom-adapters.md",
+    "title": "Custom Adapters",
+    "description": "Magek uses an adapter pattern to abstract away database and storage implementation details. This allows you to use different storage backends without modifying your application code. This guide exp..."
+  },
   {
     "uri": "magek://docs/advanced/custom-templates",
     "path": "advanced/custom-templates.md",
@@ -20,8 +26,8 @@
   {
     "uri": "magek://docs/advanced/framework-packages",
     "path": "advanced/framework-packages.md",
-    "title": "Framework packages",
-    "description": "The framework is already splitted into different packages:"
+    "title": "Framework Packages",
+    "description": "Magek is organized as a monorepo with these packages:"
   },
   {
     "uri": "magek://docs/advanced/health/sensor-health",
@@ -44,8 +50,8 @@
   {
     "uri": "magek://docs/advanced/sensor",
     "path": "advanced/sensor.md",
-    "title": "Sensor",
-    "description": "- [Sensor Health](health/sensor-health.md) - Health monitoring and indicators"
+    "title": "Sensors",
+    "description": "Sensors are monitoring components in Magek that track and report the status of your application. They provide visibility into application health and performance through HTTP endpoints."
   },
   {
     "uri": "magek://docs/advanced/testing",
@@ -59,6 +65,12 @@
     "title": "TouchEntities",
     "description": "Magek provides a way to refresh the value of an entity and update the corresponding ReadModels that depend on it."
   },
+  {
+    "uri": "magek://docs/architecture/best-practices",
+    "path": "architecture/best-practices.md",
+    "title": "Best Practices",
+    "description": "Quick reference for writing idiomatic Magek code."
+  },
   {
     "uri": "magek://docs/architecture/command",
     "path": "architecture/command.md",
@@ -105,7 +117,7 @@
     "uri": "magek://docs/architecture/read-model",
     "path": "architecture/read-model.md",
     "title": "Read model",
-    "description": "A read model contains the data of your application that is exposed to the client through the GraphQL API. It's a _projection_ of one or more entities, so you dont have to directly expose them to th..."
+    "description": "A read model contains the data of your application that is exposed to the client through the GraphQL API. It's a _projection_ of one or more entities, so you don't have to directly expose them to t..."
   },
   {
     "uri": "magek://docs/contributing",

package/docs/getting-started/coding.md

@@ -394,7 +394,7 @@ Now, let's run our application to see it working. It is as simple as running:
 npx magek start -e local
 ```
 
-This will execute a local `Express.js` server and will try to expose it in port `3000`. You can change the port by using the `-p` option:
+This will execute a local `Fastify` server and will try to expose it on port `3000`. You can change the port by using the `-p` option:
 
 ```bash
 npx magek start -e local -p 8080

package/docs/getting-started/installation.md

@@ -141,3 +141,10 @@ npx magek version
 > @magek/cli/0.16.1 darwin-x64 node-v22.12.0
 
 > **Tip:** The CLI is automatically included in every Magek project - no global installation needed! Use `npx magek` for all CLI commands within your project directory.
+
+## Next Steps
+
+Now that you have Magek installed, continue with:
+
+- **[CLI Reference](../magek-cli.md)** - Learn all available CLI commands
+- **[Coding Tutorial](./coding.md)** - Build your first Magek application step by step

package/docs/index.md

@@ -1,36 +1,43 @@
 ---
 title: "Documentation"
 children:
+  # Getting Started
   - ./introduction.md
   - ./getting-started/installation.md
+  - ./magek-cli.md
   - ./getting-started/coding.md
+  - ./getting-started/ai-coding-assistants.md
+  # Architecture (follows CQRS flow: Command → Event → Entity → Read Model → Handler)
   - ./architecture/event-driven.md
   - ./architecture/command.md
   - ./architecture/event.md
-  - ./architecture/event-handler.md
   - ./architecture/entity.md
   - ./architecture/read-model.md
+  - ./architecture/event-handler.md
   - ./architecture/notifications.md
   - ./architecture/queries.md
+  - ./architecture/best-practices.md
+  # Features
+  - ./graphql.md
   - ./features/event-stream.md
   - ./features/schedule-actions.md
   - ./features/logging.md
   - ./features/error-handling.md
+  # Security
   - ./security/security.md
   - ./security/authentication.md
   - ./security/authorization.md
-  - ./magek-cli.md
-  - ./graphql.md
-  - ./advanced/custom-templates.md
-  - ./advanced/data-migrations.md
+  # Advanced
   - ./advanced/environment-configuration.md
-  - ./advanced/framework-packages.md
+  - ./advanced/testing.md
+  - ./advanced/data-migrations.md
   - ./advanced/instrumentation.md
-  - ./advanced/register.md
   - ./advanced/sensor.md
-  - ./advanced/testing.md
-  - ./advanced/touch-entities.md
   - ./advanced/health/sensor-health.md
+  - ./advanced/register.md
+  - ./advanced/touch-entities.md
+  - ./advanced/custom-templates.md
+  - ./advanced/framework-packages.md
   - ./contributing.md
 ---
 
@@ -42,21 +49,22 @@ Welcome to the Magek documentation! Use the navigation on the left to browse gui
 
 - **[Introduction](./introduction.md)** - Learn what Magek is
 - **[Installation](./getting-started/installation.md)** - Get started quickly
+- **[CLI Reference](./magek-cli.md)** - Command-line tool
 - **[Coding Tutorial](./getting-started/coding.md)** - Build your first app
 
 ## Sections
 
 ### Getting Started
-Set up your environment and build your first Magek application.
+Set up your environment, learn the CLI, and build your first Magek application.
 
 ### Architecture
-Understand Commands, Events, Entities, Read Models, and other core concepts.
+Understand the CQRS pattern: Commands, Events, Entities, Read Models, and Event Handlers.
 
 ### Features
-Learn about Event Streams, Scheduled Actions, Logging, and Error Handling.
+GraphQL API, Event Streams, Scheduled Actions, Logging, and Error Handling.
 
 ### Security
 Implement Authentication and Authorization in your applications.
 
 ### Advanced Topics
-Dive deeper into Providers, Migrations, Testing, and more.
+Environment configuration, Testing, Migrations, Instrumentation, and more.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magek/mcp-server",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "MCP server for Magek documentation and CLI reference",
   "author": "Boosterin Labs SLU",
   "homepage": "https://magek.ai",
@@ -31,8 +31,8 @@
     "@modelcontextprotocol/sdk": "^1.12.0"
   },
   "devDependencies": {
-    "@magek/eslint-config": "^0.0.9",
-    "@types/node": "22.19.7",
+    "@magek/eslint-config": "^0.0.11",
+    "@types/node": "22.19.9",
     "rimraf": "6.1.2",
     "typescript": "5.9.3"
   },