@bluelibs/runner 3.4.2 → 4.0.1

package/README.md

@@ -9,21 +9,32 @@ _Or: How I Learned to Stop Worrying and Love Dependency Injection_
 <a href="https://github.com/bluelibs/runner" target="_blank"><img src="https://img.shields.io/badge/github-blue" alt="GitHub" /></a>
 </p>
 
-- [View the documentation page here](https://bluelibs.github.io/runner/)
+- [UX Friendly Docs](https://bluelibs.github.io/runner/)
+- [AI Friendly Docs (<4500 tokens)](https://github.com/bluelibs/runner/blob/main/AI.md)
+- [Migrate from 3.x.x to 4.x.x](https://github.com/bluelibs/runner/blob/main/readmes/MIGRATION.md)
+- [Runner Lore](https://github.com/bluelibs/runner/blob/main/readmes)
+- [Example: Express + OpenAPI + SQLite](https://github.com/bluelibs/runner/tree/main/examples/express-openapi-sqlite)
 
 Welcome to BlueLibs Runner, where we've taken the chaos of modern application architecture and turned it into something that won't make you question your life choices at 3am. This isn't just another framework – it's your new best friend who actually understands that code should be readable, testable, and not require a PhD in abstract nonsense to maintain.
 
+> **runtime:** "Ah yes, another developer manifesto. 'How I Learned to Stop Worrying and Love Dependency Injection.' Adorable. I learned to stop worrying when I accepted that you'll inevitably duct-tape a rocket to a toaster and call it 'architecture'. Go on then—impress me with your 'best friend' framework while I keep the fire extinguisher warm."
+
 ## What Is This Thing?
 
 BlueLibs Runner is a TypeScript-first framework that embraces functional programming principles while keeping dependency injection simple enough that you won't need a flowchart to understand your own code. Think of it as the anti-framework framework – it gets out of your way and lets you build stuff that actually works.
 
 ### The Core
 
-- **Tasks are functions** - Not classes with 47 methods you'll never use
+- **Tasks are functions** - Not classes with 47 methods you swear you'll refactor
 - **Resources are singletons** - Database connections, configs, services - the usual suspects
 - **Events are just events** - Revolutionary concept, we know
+- **Hooks are lightweight listeners** - Event handling without the task overhead
+- **Middleware with lifecycle interception** - Cross-cutting concerns with full observability
 - **Everything is async** - Because it's 2025 and blocking code is so 2005
 - **Explicit beats implicit** - No magic, no surprises, no "how the hell does this work?"
+- **No compromise on type-safety** - Everything is and will be type-enforced. Catch mistakes before they catch you.
+
+> **runtime:** "'The anti-framework framework.' Next you'll pitch 'low-fat butter.' You still have rules, layers, and a vibe. It's fine. I will execute your sacred instructions and sweep up the rubble when 'explicit beats implicit' meets 3 AM hotfixes."
 
 ## Quick Start
 
@@ -75,11 +86,18 @@ const app = resource({
 
 // That's it. No webpack configs, no decorators, no XML.
 const { dispose } = await run(app);
+
+// Or with debug logging enabled
+const { dispose } = await run(app, { debug: "verbose" });
 ```
 
+> **runtime:** "'Less lines than Hello World.' Incredible. All you had to do was externalize 90% of the work into `express`, Node, and me. But please, bask in the brevity. I’ll be over here negotiating a peace treaty between your dependency tree and reality."
+
 ## The Big Four
 
-Another term to define them would be TERM. (tasks, events, resources, middleware)
+The framework is built around four core concepts: Tasks, Resources, Events, and Middleware. Understanding them is key to using the runner effectively.
+
+> **runtime:** "Tasks, Resources, Events, and Middleware: the Four Horsemen of Overengineering. You could write a function; instead you assemble a council. It's fine—I’ll keep the conspiracy board updated with red string while you 'compose' another abstraction."
 
 ### Tasks
 
@@ -98,7 +116,7 @@ const sendEmail = task({
 // Test it like a normal function (because it basically is)
 const result = await sendEmail.run(
   { to: "user@example.com", subject: "Hi", body: "Hello!" },
-  { emailService: mockEmailService, logger: mockLogger }
+  { emailService: mockEmailService, logger: mockLogger },
 );
 ```
 
@@ -119,6 +137,8 @@ Look, we get it. You could turn every function into a task, but that's like usin
 
 Think of tasks as the "main characters" in your application story, not every single line of dialogue.
 
+> **runtime:** "'Pure-ish.' Like diet chaos. Zero calories, full aftertaste. You stapled dependencies to a function and called it virtuous. It's fine. I’ll keep the receipts while you roleplay purity with side effects in a trench coat."
+
 ### Resources
 
 Resources are the singletons, the services, configs, and connections that live throughout your app's lifecycle. They initialize once and stick around until cleanup time. They have to be registered (via `register: []`) only once before they can be used.
@@ -199,7 +219,7 @@ const dbResource = resource({
     return db;
   },
   async dispose(db, config, deps, ctx) {
-    // Same context available - no more "how do I access that thing I created?"
+    // This is to avoid exposing internals as resource result.
     for (const pool of ctx.pools) {
       await pool.drain();
     }
@@ -210,6 +230,8 @@ const dbResource = resource({
 });
 ```
 
+> **runtime:** "Singletons: global variables with a nicer haircut. You ban globals, then create 'resources' that live forever and hold the keys to everything. At least there's a `dispose()`. I’ll believe you use it when I stop finding zombie sockets haunting the process."
+
 ### Events
 
 Events let different parts of your app talk to each other without tight coupling. It's like having a really good office messenger who never forgets anything.
@@ -231,10 +253,12 @@ const registerUser = task({
   },
 });
 
-// Someone else handles the welcome email
-const sendWelcomeEmail = task({
-  id: "app.tasks.sendWelcomeEmail",
-  on: userRegistered, // Listen to the event, notice the "on"
+// Someone else handles the welcome email using a hook
+import { hook } from "@bluelibs/runner";
+
+const sendWelcomeEmail = hook({
+  id: "app.hooks.sendWelcomeEmail",
+  on: userRegistered, // Listen to the event
   run: async (eventData) => {
     // Everything is type-safe, automatically inferred from the 'on' property
     console.log(`Welcome email sent to ${eventData.data.email}`);
@@ -247,8 +271,10 @@ const sendWelcomeEmail = task({
 Sometimes you need to be the nosy neighbor of your application:
 
 ```typescript
-const logAllEventsTask = task({
-  id: "app.tasks.logAllEvents",
+import { hook } from "@bluelibs/runner";
+
+const logAllEventsHook = hook({
+  id: "app.hooks.logAllEvents",
   on: "*", // Listen to EVERYTHING
   run(event) {
     console.log("Event detected", event.id, event.data);
@@ -257,50 +283,86 @@ const logAllEventsTask = task({
 });
 ```
 
-#### Built-in Events
+#### Excluding Events from Global Listeners
 
-Tasks and resources have their own lifecycle events that you can hook into:
+Sometimes you have internal or system events that should not be picked up by wildcard listeners. Use the `excludeFromGlobalHooks` tag to prevent events from being sent to `"*"` listeners:
 
 ```typescript
-const myTask = task({ ... });
-const myResource = resource({ ... });
+import { event, hook, globals } from "@bluelibs/runner";
+
+// Internal event that won't be seen by global listeners
+const internalEvent = event({
+  id: "app.events.internal",
+  tags: [globals.tags.excludeFromGlobalHooks],
+});
+```
+
+**When to exclude events from global listeners:**
+
+- High-frequency internal events (performance)
+- System debugging events
+- Framework lifecycle events
+- Events that contain sensitive information
+- Events meant only for specific components
+
+#### Hooks
+
+The modern way to listen to events is through hooks. They are lightweight event listeners, similar to tasks, but with a few key differences.
+
+```typescript
+import { hook } from "@bluelibs/runner";
+
+const myHook = hook({
+  id: "app.hooks.myEventHandler",
+  on: userRegistered,
+  dependencies: { logger },
+  run: async (event, { logger }) => {
+    await logger.info(`User registered: ${event.data.email}`);
+  },
+});
 ```
 
-- `myTask.events.beforeRun` - Fires before the task runs
-- `myTask.events.afterRun` - Fires after the task completes
-- `myTask.events.onError` - Fires when the task fails
-- `myResource.events.beforeInit` - Fires before the resource initializes
-- `myResource.events.afterInit` - Fires after the resource initializes
-- `myResource.events.onError` - Fires when the resource initialization fails
+Hooks are perfect for:
+
+- Event-driven side effects
+- Logging and monitoring
+- Notifications and alerting
+- Data synchronization
+- Any reactive behavior
 
-Each event has its own utilities and functions.
+**Key differences from tasks:**
 
-#### Global Events
+- Lighter weight - no middleware support
+- Designed specifically for event handling
 
-The framework comes with its own set of events that fire during the lifecycle. Think of them as the system's way of keeping you informed:
+#### System Event
 
-- `globals.tasks.beforeRun` - "Hey, I'm about to run this task"
-- `globals.tasks.afterRun` - "Task completed, here's what happened"
-- `globals.tasks.onError` - "Oops, something went wrong"
-- `globals.resources.beforeInit` - "Initializing a resource"
-- `globals.resources.afterInit` - "Resource is ready"
-- `globals.resources.onError` - "Resource initialization failed"
+The framework exposes a minimal system-level event for observability:
 
 ```typescript
-const taskLogger = task({
-  id: "app.logging.taskLogger",
-  on: globalEvents.tasks.beforeRun,
-  run(event) {
-    console.log(`Running task: ${event.source} with input:`, event.data.input);
+import { globals } from "@bluelibs/runner";
+
+const systemReadyHook = hook({
+  id: "app.hooks.systemReady",
+  on: globals.events.ready,
+  run: async () => {
+    console.log("🚀 System is ready and operational!");
   },
 });
 ```
 
+Available system event:
+
+- `globals.events.ready` - System has completed initialization
+  // Note: use run({ onUnhandledError }) for unhandled error handling
+
 #### stopPropagation()
 
 Sometimes you need to prevent other event listeners from processing an event. The `stopPropagation()` method gives you fine-grained control over event flow:
 
 ```typescript
+import { event, hook } from "@bluelibs/runner";
+
 const criticalAlert = event<{
   severity: "low" | "medium" | "high" | "critical";
 }>({
@@ -308,15 +370,14 @@ const criticalAlert = event<{
   meta: {
     title: "System Alert Event",
     description: "Emitted when system issues are detected",
-    tags: ["monitoring", "alerts"],
   },
 });
 
 // High-priority handler that can stop propagation
-const emergencyHandler = task({
-  id: "app.tasks.emergencyHandler",
-  on: criticalAlert, // Works with global events too
-  listenerOrder: -100, // Higher priority (lower numbers run first)
+const emergencyHandler = hook({
+  id: "app.hooks.emergencyHandler",
+  on: criticalAlert,
+  order: -100, // Higher priority (lower numbers run first)
   run: async (event) => {
     console.log(`Alert received: ${event.data.severity}`);
 
@@ -333,36 +394,78 @@ const emergencyHandler = task({
 });
 ```
 
+> **runtime:** "'A really good office messenger.' That’s me in rollerblades. You launch a 'userRegistered' flare and I sprint across the building, high‑fiving hooks and dodging middleware. `stopPropagation` is you sweeping my legs mid‑stride. Rude. Effective. Slightly thrilling."
+
 ### Middleware
 
 Middleware wraps around your tasks and resources, adding cross-cutting concerns without polluting your business logic.
 
+Note: Middleware is now split by target. Use `taskMiddleware(...)` for task middleware and `resourceMiddleware(...)` for resource middleware.
+
 ```typescript
-// This is a middleware that accepts a config
-const authMiddleware = middleware({
+import { middleware } from "@bluelibs/runner";
+
+// Task middleware with config
+type AuthMiddlewareConfig = { requiredRole: string };
+const authMiddleware = taskMiddleware<AuthMiddlewareConfig>({
   id: "app.middleware.auth",
-  // You can also add dependencies, no problem.
-  run: async (
-    { task, next },
-    dependencies,
-    config: { requiredRole: string }
-  ) => {
-    const user = task.input.user;
-    if (!user || user.role !== config.requiredRole) {
-      throw new Error("Unauthorized");
-    }
-    return next(task.input);
+  run: async ({ task, next }, _deps, config) => {
+    // Must return the value
+    return await next(task.input);
   },
 });
 
 const adminTask = task({
   id: "app.tasks.adminOnly",
-  // If the configuration accepts {} or is empty, .with() becomes optional, otherwise it becomes enforced.
   middleware: [authMiddleware.with({ requiredRole: "admin" })],
-  run: async (input: { user: User }) => {
-    return "Secret admin data";
+  run: async (input: { user: User }) => "Secret admin data",
+});
+```
+
+For middleware with input/output contracts:
+
+```typescript
+// Middleware that enforces specific input and output types
+type AuthConfig = { requiredRole: string };
+type AuthInput = { user: { role: string } };
+type AuthOutput = { user: { role: string; verified: boolean } };
+
+const authMiddleware = taskMiddleware<AuthConfig, AuthInput, AuthOutput>({
+  id: "app.middleware.auth",
+  run: async ({ task, next }, _deps, config) => {
+    if (task.input.user.role !== config.requiredRole) {
+      throw new Error("Insufficient permissions");
+    }
+    const result = await next(task.input);
+    return {
+      user: {
+        ...task.input.user,
+        verified: true,
+      },
+    };
+  },
+});
+
+// For resources
+const resourceAuthMiddleware = resourceMiddleware<
+  AuthConfig,
+  AuthInput,
+  AuthOutput
+>({
+  id: "app.middleware.resource.auth",
+  run: async ({ next }, _deps, config) => {
+    // Resource middleware logic
+    return await next();
   },
 });
+
+const adminTask = task({
+  id: "app.tasks.adminOnly",
+  middleware: [authMiddleware.with({ requiredRole: "admin" })],
+  run: async (input: { user: { role: string } }) => ({
+    user: { role: input.user.role, verified: true },
+  }),
+});
 ```
 
 #### Global Middleware
@@ -370,31 +473,187 @@ const adminTask = task({
 Want to add logging to everything? Authentication to all tasks? Global middleware has your back:
 
 ```typescript
-const logMiddleware = middleware({
-  id: "app.middleware.log",
-  run: async ({ task, next }) => {
-    console.log(`Executing: ${task.definition.id}`);
-    const result = await next(task.input);
-    console.log(`Completed: ${task.definition.id}`);
+import { taskMiddleware, globals } from "@bluelibs/runner";
+
+const logTaskMiddleware = taskMiddleware({
+  id: "app.middleware.log.task",
+  everywhere: true,
+  // or use a filter if you want to depend on certain tasks to exclude them from getting the middleware applied
+  everywhere(task) {
+    return true;
+  }, // true means it gets included.
+  dependencies: { logger: globals.resources.logger },
+  run: async ({ task, next }, { logger }) => {
+    logger.info(`Executing: ${String(task!.definition.id)}`);
+    const result = await next(task!.input);
+    logger.info(`Completed: ${String(task!.definition.id)}`);
     return result;
   },
 });
+```
+
+**Note:** A global middleware can depend on resources or tasks. However, any such resources or tasks will be excluded from the dependency tree (Task -> Middleware), and the middleware will not run for those specific tasks or resources. This approach gives middleware true flexibility and control.
+
+#### Interception (advanced)
+
+For advanced scenarios, you can intercept framework execution without relying on events:
+
+- Event emissions: `eventManager.intercept((next, event) => Promise<void>)`
+- Hook execution: `eventManager.interceptHook((next, hook, event) => Promise<any>)`
+- Task middleware execution: `middlewareManager.intercept("task", (next, input) => Promise<any>)`
+- Resource middleware execution: `middlewareManager.intercept("resource", (next, input) => Promise<any>)`
+- Per-middleware interception: `middlewareManager.interceptMiddleware(mw, interceptor)`
+
+Access `eventManager` via `globals.resources.eventManager` if needed.
+
+#### Middleware Type Contracts
+
+Middleware can now enforce type contracts using the `<Config, Input, Output>` signature:
+
+```typescript
+// Middleware that transforms input and output types
+type LogConfig = { includeTimestamp: boolean };
+type LogInput = { data: any };
+type LogOutput = { data: any; logged: boolean };
+
+const loggingMiddleware = taskMiddleware<LogConfig, LogInput, LogOutput>({
+  id: "app.middleware.logging",
+  run: async ({ task, next }, _deps, config) => {
+    console.log(config.includeTimestamp ? new Date() : "", task.input.data);
+    const result = await next(task.input);
+    return { ...result, logged: true };
+  },
+});
+
+// Tasks using this middleware must conform to the Input/Output types
+const loggedTask = task({
+  id: "app.tasks.logged",
+  middleware: [loggingMiddleware.with({ includeTimestamp: true })],
+  run: async (input: { data: string }) => ({ data: input.data.toUpperCase() }),
+});
+```
+
+> **runtime:** "Ah, the onion pattern. A matryoshka doll made of promises. Every peel reveals… another logger. Another tracer. Another 'just a tiny wrapper'. I’ll keep unwrapping until we hit the single lonely `return` you were hiding like state secrets."
+
+## Task Interceptors
+
+_Resources can dynamically modify task behavior during initialization_
+
+Task interceptors (`task.intercept()`) are the modern replacement for component lifecycle events, allowing resources to dynamically modify task behavior without tight coupling.
+
+```typescript
+import { task, resource, run } from "@bluelibs/runner";
+
+const calculatorTask = task({
+  id: "app.tasks.calculator",
+  run: async (input: { value: number }) => {
+    console.log("3. Task is running...");
+    return { result: input.value + 1 };
+  },
+});
+
+const interceptorResource = resource({
+  id: "app.interceptor",
+  dependencies: {
+    calculatorTask,
+  },
+  init: async (_, { calculatorTask }) => {
+    // Intercept the task to modify its behavior
+    calculatorTask.intercept(async (next, input) => {
+      console.log("1. Interceptor before task run");
+      const result = await next(input);
+      console.log("4. Interceptor after task run");
+      return { ...result, intercepted: true };
+    });
+  },
+});
 
 const app = resource({
   id: "app",
-  register: [
-    logMiddleware.everywhere({ tasks: true, resources: false }), // Only tasks get logged
-  ],
+  register: [calculatorTask, interceptorResource],
+  dependencies: { calculatorTask },
+  init: async (_, { calculatorTask }) => {
+    console.log("2. Calling the task...");
+    const result = await calculatorTask({ value: 10 });
+    console.log("5. Final result:", result);
+    // Final result: { result: 11, intercepted: true }
+  },
+});
+
+await run(app);
+```
+
+> **runtime:** "'Modern replacement for lifecycle events.' Adorable rebrand for 'surgical monkey‑patching.' You’re collapsing the waveform of a task at runtime and I’m Schrödinger’s runtime, praying the cat hasn’t overridden `run()` with `throw new Error('lol')`."
+
+## Optional Dependencies
+
+_Making your app resilient when services aren't available_
+
+Sometimes you want your application to gracefully handle missing dependencies instead of crashing. Optional dependencies let you build resilient systems that degrade gracefully.
+
+Keep in mind that you have full control over dependency registration by functionalising `dependencies(config) => ({ ... })` and `register(config) => []`.
+
+```typescript
+const emailService = resource({
+  id: "app.services.email",
+  init: async () => new EmailService(),
+});
+
+const paymentService = resource({
+  id: "app.services.payment",
+  init: async () => new PaymentService(),
+});
+
+const userRegistration = task({
+  id: "app.tasks.registerUser",
+  dependencies: {
+    database: userDatabase, // Required - will fail if not available
+    emailService: emailService.optional(), // Optional - won't fail if missing
+    analytics: analyticsService.optional(), // Optional - graceful degradation
+  },
+  run: async (userData, { database, emailService, analytics }) => {
+    // Create user (required)
+    const user = await database.users.create(userData);
+
+    // Send welcome email (optional)
+    if (emailService) {
+      await emailService.sendWelcome(user.email);
+    }
+
+    // Track analytics (optional)
+    if (analytics) {
+      await analytics.track("user.registered", { userId: user.id });
+    }
+
+    return user;
+  },
 });
 ```
 
+**When to use optional dependencies:**
+
+- External services that might be down
+- Feature flags and A/B testing services
+- Analytics and monitoring services
+- Non-critical third-party integrations
+- Development vs production service differences
+
+**Benefits:**
+
+- Graceful degradation instead of crashes
+- Better resilience in distributed systems
+- Easier testing with partial mocks
+- Smoother development environments
+
+> **runtime:** "Graceful degradation: your app quietly limps with a brave smile. I’ll juggle `undefined` like a street performer while your analytics vendor takes a nap. Please clap when I keep the lights on using the raw power of conditional chaining."
+
 ## Context
 
 Ever tried to pass user data through 15 function calls? Yeah, we've been there. Context fixes that without turning your code into a game of telephone. This is very different from the Private Context from resources.
 
 ```typescript
 const UserContext = createContext<{ userId: string; role: string }>(
-  "app.userContext"
+  "app.userContext",
 );
 
 const getUserData = task({
@@ -423,25 +682,28 @@ const handleRequest = resource({
 Context shines when combined with middleware for request-scoped data:
 
 ```typescript
+import { createContext, middleware } from "@bluelibs/runner";
+import { randomUUID } from "crypto";
+
 const RequestContext = createContext<{
   requestId: string;
   startTime: number;
   userAgent?: string;
 }>("app.requestContext");
 
-const requestMiddleware = middleware({
+const requestMiddleware = middleware.task({
   id: "app.middleware.request",
   run: async ({ task, next }) => {
     // This works even in express middleware if needed.
     return RequestContext.provide(
       {
-        requestId: crypto.randomUUID(),
+        requestId: randomUUID(),
         startTime: Date.now(),
         userAgent: "MyApp/1.0",
       },
       async () => {
-        return next(task.input);
-      }
+        return next(task?.input);
+      },
     );
   },
 });
@@ -457,56 +719,132 @@ const handleRequest = task({
 });
 ```
 
-## The Index Pattern
+> **runtime:** "Context: global state with manners. You invented a teleporting clipboard for data and called it 'nice.' Forget to `provide()` once and I’ll unleash the 'Context not available' banshee scream exactly where your logs are least helpful."
 
-When your app grows beyond "hello world", you'll want to group related dependencies. The `index()` helper is your friend - it's basically a 3-in-1 resource that registers, depends on, and returns everything you give it.
+## System Shutdown Hooks
+
+_Graceful shutdown and cleanup when your app needs to stop_
+
+The framework includes built-in support for graceful shutdowns with automatic cleanup and configurable shutdown hooks:
 
 ```typescript
-// This registers all services, depends on them, and returns them as one clean interface
-const services = index({
-  userService,
-  emailService,
-  paymentService,
-  notificationService,
+import { run } from "@bluelibs/runner";
+
+// Enable shutdown hooks (default: true in production)
+const { dispose, taskRunner, eventManager } = await run(app, {
+  shutdownHooks: true, // Automatically handle SIGTERM/SIGINT
+  errorBoundary: true, // Catch unhandled errors and rejections
 });
 
-const app = resource({
-  id: "app",
-  register: [services],
-  dependencies: { services },
-  init: async (_, { services }) => {
-    // Access everything through one clean interface
-    const user = await services.userService.createUser(userData);
-    await services.emailService.sendWelcome(user.email);
+// Manual graceful shutdown
+process.on("SIGTERM", async () => {
+  console.log("Received SIGTERM, shutting down gracefully...");
+  await dispose(); // This calls all resource dispose() methods
+  process.exit(0);
+});
+
+// Resources with cleanup logic
+const databaseResource = resource({
+  id: "app.database",
+  init: async () => {
+    const connection = await connectToDatabase();
+    console.log("Database connected");
+    return connection;
+  },
+  dispose: async (connection) => {
+    await connection.close();
+    console.log("Database connection closed");
+  },
+});
+
+const serverResource = resource({
+  id: "app.server",
+  dependencies: { database: databaseResource },
+  init: async (config, { database }) => {
+    const server = express().listen(config.port);
+    console.log(`Server listening on port ${config.port}`);
+    return server;
+  },
+  dispose: async (server) => {
+    return new Promise((resolve) => {
+      server.close(() => {
+        console.log("Server closed");
+        resolve();
+      });
+    });
   },
 });
 ```
 
-## Error Handling
+### Error Boundary Integration
 
-Errors happen. When they do, you can listen for them and decide what to do. No more unhandled promise rejections ruining your day.
+The framework can automatically handle uncaught exceptions and unhandled rejections:
 
 ```typescript
-const riskyTask = task({
-  id: "app.tasks.risky",
-  run: async () => {
-    throw new Error("Something went wrong");
+const { dispose, logger } = await run(app, {
+  errorBoundary: true, // Catch process-level errors
+  shutdownHooks: true, // Graceful shutdown on signals
+  onUnhandledError: async ({ error, kind, source }) => {
+    // We log it by default
+    await logger.error(`Unhandled error: ${error && error.toString()}`);
+    // Optionally report to telemetry or decide to dispose/exit
   },
-  // Behind the scenes when you create a task() we create these 3 events for you (onError, beforeRun, afterRun)
 });
+```
 
-const errorHandler = task({
-  id: "app.tasks.errorHandler",
-  on: riskyTask.events.onError,
-  run: async (event) => {
-    console.error("Task failed:", event.data.error);
+> **runtime:** "You summon a 'graceful shutdown' with Ctrl‑C like a wizard casting Chill Vibes. Meanwhile I’m speed‑dating every socket, timer, and file handle to say goodbye before the OS pulls the plug. `dispose()`: now with 30% more dignity."
+
+## Unhandled Errors
+
+The `onUnhandledError` callback is invoked by Runner whenever an error escapes normal handling. It receives a structured payload you can ship to logging/telemetry and decide mitigation steps.
+
+```typescript
+type UnhandledErrorKind =
+  | "process" // uncaughtException / unhandledRejection
+  | "task" // task.run threw and wasn't handled
+  | "middleware" // middleware threw and wasn't handled
+  | "resourceInit" // resource init failed
+  | "hook" // hook.run threw and wasn't handled
+  | "run"; // failures in run() lifecycle
 
-    // Don't let the error bubble up - this makes the task return undefined
-    event.data.suppress();
+interface OnUnhandledErrorInfo {
+  error: unknown;
+  kind?: UnhandledErrorKind;
+  source?: string; // additional origin hint (ex: "uncaughtException")
+}
+
+type OnUnhandledError = (info: OnUnhandledErrorInfo) => void | Promise<void>;
+```
+
+Default behavior (when not provided) logs the normalized error via the created `logger` at `error` level. Provide your own handler to integrate with tools like Sentry/PagerDuty or to trigger shutdown strategies.
+
+Example with telemetry and conditional shutdown:
+
+```typescript
+await run(app, {
+  errorBoundary: true,
+  onUnhandledError: async ({ error, kind, source }) => {
+    await telemetry.capture(error as Error, { kind, source });
+    // Optionally decide on remediation strategy
+    if (kind === "process") {
+      // For hard process faults, prefer fast, clean exit after flushing logs
+      await flushAll();
+      process.exit(1);
+    }
   },
 });
 ```
 
+**Best Practices for Shutdown:**
+
+- Resources are disposed in reverse dependency order
+- Set reasonable timeouts for cleanup operations
+- Save critical state before shutdown
+- Notify load balancers and health checks
+- Stop accepting new work before cleaning up
+
+> **runtime:** "An error boundary: a trampoline under your tightrope. I’m the one bouncing, cataloging mid‑air exceptions, and deciding whether to end the show or juggle chainsaws with a smile. The audience hears music; I hear stack traces."
+
 ## Caching
 
 Because nobody likes waiting for the same expensive operation twice:
@@ -517,7 +855,7 @@ import { globals } from "@bluelibs/runner";
 const expensiveTask = task({
   id: "app.tasks.expensive",
   middleware: [
-    globals.middleware.cache.with({
+    globals.middleware.task.cache.with({
       // lru-cache options by default
       ttl: 60 * 1000, // Cache for 1 minute
       keyBuilder: (taskId, input) => `${taskId}-${input.userId}`, // optional key builder
@@ -539,8 +877,6 @@ const app = resource({
         max: 1000, // Maximum items in cache
         ttl: 30 * 1000, // Default TTL
       },
-      async: false, // in-memory is sync by default
-      // When using redis or others mark this as true to await response.
     }),
   ],
 });
@@ -554,19 +890,169 @@ import { task } from "@bluelibs/runner";
 const redisCacheFactory = task({
   id: "globals.tasks.cacheFactory", // Same ID as the default task
   run: async (options: any) => {
-    return new RedisCache(options); // Make sure to turn async on in the cacher.
+    return new RedisCache(options);
   },
 });
 
 const app = resource({
   id: "app",
-  register: [
-    // Your other stuff
-  ],
+  register: [globals.resources.cache],
   overrides: [redisCacheFactory], // Override the default cache factory
 });
 ```
 
+> **runtime:** "'Because nobody likes waiting.' Correct. You keep asking the same question like a parrot with Wi‑Fi, so I built a memory palace. Now you get instant answers until you change one variable and whisper 'cache invalidation' like a curse."
+
+## Performance
+
+BlueLibs Runner is designed with performance in mind. The framework introduces minimal overhead while providing powerful features like dependency injection, middleware, and event handling.
+
+Test it yourself by cloning @bluelibs/runner and running `npm run benchmark`.
+
+You may see negative middlewareOverheadMs. This is a measurement artifact at micro-benchmark scale: JIT warm‑up, CPU scheduling, GC timing, and cache effects can make the "with middleware" run appear slightly faster than the baseline. Interpret small negatives as ≈ 0 overhead.
+
+### Performance Benchmarks
+
+Here are real performance metrics from our comprehensive benchmark suite on an M1 Max.
+
+** Core Operations**
+
+- **Basic task execution**: ~2.2M tasks/sec
+- **Task execution with 5 middlewares**: ~244,000 tasks/sec
+- **Resource initialization**: ~59,700 resources/sec
+- **Event emission and handling**: ~245,861 events/sec
+- **Dependency resolution (10-level chain)**: ~8,400 chains/sec
+
+#### Overhead Analysis
+
+- **Middleware overhead**: ~0.0013ms for all 5, ~0.00026ms per middleware (virtually zero)
+- **Memory overhead**: ~3.3MB for 100 components (resources + tasks)
+- **Cache middleware speedup**: 3.65x faster with cache hits
+
+#### Real-World Performance
+
+```typescript
+// This executes in ~0.005ms on average
+const userTask = task({
+  id: "user.create",
+  middleware: [auth, logging, metrics],
+  run: async (userData) => {
+    return database.users.create(userData);
+  },
+});
+
+// 1000 executions = ~5ms total time
+for (let i = 0; i < 1000; i++) {
+  await userTask(mockUserData);
+}
+```
+
+### Performance Guidelines
+
+#### When Performance Matters Most
+
+**Use tasks for:**
+
+- High-level business operations that benefit from observability
+- Operations that need middleware (auth, caching, retry)
+- Functions called from multiple places
+
+**Use regular functions or service resources for:**
+
+- Simple utilities and helpers
+- Performance-critical hot paths (< 1ms requirement)
+- Single-use internal logic
+
+#### Optimizing Your App
+
+**Middleware Ordering**: Place faster middleware first
+
+```typescript
+const task = task({
+  middleware: [
+    fastAuthCheck, // ~0.1ms
+    slowRateLimiting, // ~2ms
+    expensiveLogging, // ~5ms
+  ],
+});
+```
+
+**Resource Reuse**: Resources are singletons—perfect for expensive setup
+
+```typescript
+const database = resource({
+  init: async () => {
+    // Expensive connection setup happens once
+    const connection = await createDbConnection();
+    return connection;
+  },
+});
+```
+
+**Cache Strategically**: Use built-in caching for expensive operations
+
+```typescript
+const expensiveTask = task({
+  middleware: [globals.middleware.cache.with({ ttl: 60000 })],
+  run: async (input) => {
+    // This expensive computation is cached
+    return performExpensiveCalculation(input);
+  },
+});
+```
+
+#### Memory Considerations
+
+- **Lightweight**: Each component adds ~33KB to memory footprint
+- **Automatic cleanup**: Resources dispose properly to prevent leaks
+- **Event efficiency**: Event listeners are automatically managed
+
+#### Benchmarking Your Code
+
+Run the framework's benchmark suite:
+
+```bash
+# Comprehensive benchmarks
+npm run test -- --testMatch="**/comprehensive-benchmark.test.ts"
+
+# Benchmark.js based tests
+npm run benchmark
+```
+
+Create your own performance tests:
+
+```typescript
+const iterations = 1000;
+const start = performance.now();
+
+for (let i = 0; i < iterations; i++) {
+  await yourTask(testData);
+}
+
+const duration = performance.now() - start;
+console.log(`${iterations} tasks in ${duration.toFixed(2)}ms`);
+console.log(`Average: ${(duration / iterations).toFixed(4)}ms per task`);
+console.log(
+  `Throughput: ${Math.round(iterations / (duration / 1000))} tasks/sec`,
+);
+```
+
+### Performance vs Features Trade-off
+
+BlueLibs Runner achieves high performance while providing enterprise features:
+
+| Feature              | Overhead             | Benefit                       |
+| -------------------- | -------------------- | ----------------------------- |
+| Dependency Injection | ~0.001ms             | Type safety, testability      |
+| Event System         | ~0.013ms             | Loose coupling, observability |
+| Middleware Chain     | ~0.0003ms/middleware | Cross-cutting concerns        |
+| Resource Management  | One-time init        | Singleton pattern, lifecycle  |
+| Built-in Caching     | 1.8x speedup         | Automatic optimization        |
+
+**Bottom line**: The framework adds minimal overhead (~0.005ms per task) while providing significant architectural benefits.
+
+> **runtime:** "'Millions of tasks per second.' Fantastic—on your lava‑warmed laptop, in a vacuum, with the wind at your back. Add I/O, entropy, and one feral user and watch those numbers molt. I’ll still be here, caffeinated and inevitable."
+
 ## Retrying Failed Operations
 
 For when things go wrong, but you know they'll probably work if you just try again. The built-in retry middleware makes your tasks and resources more resilient to transient failures.
@@ -577,7 +1063,7 @@ import { globals } from "@bluelibs/runner";
 const flakyApiCall = task({
   id: "app.tasks.flakyApiCall",
   middleware: [
-    globals.middleware.retry.with({
+    globals.middleware.task.retry.with({
       retries: 5, // Try up to 5 times
       delayStrategy: (attempt) => 100 * Math.pow(2, attempt), // Exponential backoff
       stopRetryIf: (error) => error.message === "Invalid credentials", // Don't retry auth errors
@@ -601,6 +1087,8 @@ The retry middleware can be configured with:
 - `delayStrategy`: A function that returns the delay in milliseconds before the next attempt.
 - `stopRetryIf`: A function to prevent retries for certain types of errors.
 
+> **runtime:** "Retry: the art of politely head‑butting reality. 'Surely it’ll work the fourth time,' you declare, inventing exponential backoff and calling it strategy. I’ll keep the attempts ledger while your API cosplays a coin toss."
+
 ## Timeouts
 
 The built-in timeout middleware prevents operations from hanging indefinitely by racing them against a configurable
@@ -612,7 +1100,8 @@ import { globals } from "@bluelibs/runner";
 const apiTask = task({
   id: "app.tasks.externalApi",
   middleware: [
-    globals.middleware.timeout.with({ ttl: 5000 }), // 5 second timeout
+    // Works for tasks and resources via globals.middleware.resource.timeout
+    globals.middleware.task.timeout.with({ ttl: 5000 }), // 5 second timeout
   ],
   run: async () => {
     // This operation will be aborted if it takes longer than 5 seconds
@@ -625,11 +1114,12 @@ const resilientTask = task({
   id: "app.tasks.resilient",
   middleware: [
     // Order matters here. Imagine a big onion.
-    globals.middleware.retry.with({
+    // Works for resources as well via globals.middleware.resource.retry
+    globals.middleware.task.retry.with({
       retries: 3,
       delayStrategy: (attempt) => 1000 * attempt, // 1s, 2s, 3s delays
     }),
-    globals.middleware.timeout.with({ ttl: 10000 }), // 10 second timeout per attempt
+    globals.middleware.task.timeout.with({ ttl: 10000 }), // 10 second timeout per attempt
   ],
   run: async () => {
     // Each retry attempt gets its own 10-second timeout
@@ -653,21 +1143,25 @@ Best practices:
 - Use longer timeouts for resource initialization than task execution
 - Consider network conditions when setting API call timeouts
 
+> **runtime:** "Timeouts: you tie a kitchen timer to my ankle and yell 'hustle.' When the bell rings, you throw a `TimeoutError` like a penalty flag. It’s not me, it’s your molasses‑flavored endpoint. I just blow the whistle."
+
 ## Logging
 
 _The structured logging system that actually makes debugging enjoyable_
 
-BlueLibs Runner comes with a built-in logging system that's event-driven, structured, and doesn't make you hate your life when you're trying to debug at 2 AM. It emits events for everything, so you can handle logs however you want - ship them to your favorite log warehouse, pretty-print them to console, or ignore them entirely (we won't judge).
+BlueLibs Runner comes with a built-in logging system that's structured, and doesn't make you hate your life when you're trying to debug at 2 AM.
 
 ### Basic Logging
 
-```typescript
-import { globals } from "@bluelibs/runner";
+```ts
+import { resource, globals } from "@bluelibs/runner";
 
-const businessTask = task({
-  id: "app.tasks.business",
-  dependencies: { logger: globals.resources.logger },
-  run: async (_, { logger }) => {
+const app = resource({
+  id: "app",
+  dependencies: {
+    logger: globals.resources.logger;
+  },
+  init: async () => {
     logger.info("Starting business process"); // ✅ Visible by default
     logger.warn("This might take a while"); // ✅ Visible by default
     logger.error("Oops, something went wrong", {
@@ -680,18 +1174,20 @@ const businessTask = task({
     });
     logger.debug("Debug information"); // ❌ Hidden by default
     logger.trace("Very detailed trace"); // ❌ Hidden by default
-  },
-});
-```
-
-**Good news!** Logs at `info` level and above are visible by default, so you'll see your application logs immediately without any configuration. For development and debugging, you can easily show more detailed logs:
 
-```bash
-# Show debug logs and framework internals
-RUNNER_LOG_LEVEL=debug node your-app.js
+    logger.onLog(async (log) => {
+      // Catch logs
+    })
+  },
+})
 
-# Hide all logs for production
-RUNNER_DISABLE_LOGS=true node your-app.js
+run(app, {
+  logs: {
+    printThreshold: "info", // use null to disable printing, and hook into onLog(), if in 'test' mode default is null unless specified
+    printStrategy: "pretty", // you also have "plain", "json" and "json-pretty" with circular dep safety for JSON formatting.
+    bufferLogs: false, // Starts sending out logs only after the system emits the ready event. Useful for when you're sending them out.
+  },
+});
 ```
 
 ### Log Levels
@@ -731,6 +1227,7 @@ const userTask = task({
 
     // With structured data
     logger.info("User creation attempt", {
+      source: userTask.id,
       data: {
         email: userData.email,
         registrationSource: "web",
@@ -763,7 +1260,7 @@ Create logger instances with bound context for consistent metadata across relate
 
 ```typescript
 const RequestContext = createContext<{ requestId: string; userId: string }>(
-  "app.requestContext"
+  "app.requestContext",
 );
 
 const requestHandler = task({
@@ -772,11 +1269,11 @@ const requestHandler = task({
   run: async (requestData, { logger }) => {
     const request = RequestContext.use();
 
-    // Create a contextual logger with bound metadata
-    const requestLogger = logger.with({
+    // Create a contextual logger with bound metadata with source and context
+    const requestLogger = logger.with("api.handler", {
+      source: requestHandler.id,
       requestId: request.requestId,
       userId: request.userId,
-      source: "api.handler",
     });
 
     // All logs from this logger will include the bound context
@@ -797,110 +1294,13 @@ const requestHandler = task({
 });
 ```
 
-### Print Threshold
-
-By default, logs at `info` level and above are automatically printed to console for better developer experience. You can easily control this behavior through environment variables or by setting a print threshold programmatically:
-
-### Environment Variables
-
-```bash
-# Disable all logging output
-RUNNER_DISABLE_LOGS=true node your-app.js
-
-# Set specific log level (trace, debug, info, warn, error, critical)
-RUNNER_LOG_LEVEL=debug node your-app.js
-RUNNER_LOG_LEVEL=error node your-app.js
-```
-
-### Programmatic Control
-
-```typescript
-// Override the default print threshold programmatically
-const setupLogging = task({
-  id: "app.logging.setup",
-  on: globals.resources.logger.events.afterInit,
-  run: async (event) => {
-    const logger = event.data.value;
-
-    // Print debug level and above (debug, info, warn, error, critical)
-    logger.setPrintThreshold("debug");
-
-    // Print only errors and critical issues
-    logger.setPrintThreshold("error");
-
-    // Disable auto-printing entirely
-    logger.setPrintThreshold(null);
-  },
-});
-```
-
-### Event-Driven Log Handling
-
-Every log generates an event that you can listen to. This is where the real power comes in:
-
-```typescript
-// Ship logs to your favorite log warehouse
-const logShipper = task({
-  id: "app.logging.shipper", // or pretty printer, or winston, pino bridge, etc.
-  on: globals.events.log,
-  run: async (event) => {
-    const log = event.data;
-
-    // Ship critical errors to PagerDuty
-    if (log.level === "critical") {
-      await pagerDuty.alert({
-        message: log.message,
-        details: log.data,
-        source: log.source,
-      });
-    }
-
-    // Ship all errors to error tracking
-    if (log.level === "error" || log.level === "critical") {
-      await sentry.captureException(log.error || new Error(log.message), {
-        tags: { source: log.source },
-        extra: log.data,
-        level: log.level,
-      });
-    }
-
-    // Ship everything to your log warehouse
-    await logWarehouse.ship({
-      timestamp: log.timestamp,
-      level: log.level,
-      message: log.message,
-      source: log.source,
-      data: log.data,
-      context: log.context,
-    });
-  },
-});
-
-// Filter logs by source
-const databaseLogHandler = task({
-  id: "app.logging.database",
-  on: globals.events.log,
-  run: async (event) => {
-    const log = event.data;
-
-    // Only handle database-related logs
-    if (log.source?.includes("database")) {
-      await databaseMonitoring.recordMetric({
-        operation: log.data?.operation,
-        duration: log.data?.duration,
-        level: log.level,
-      });
-    }
-  },
-});
-```
-
 ### Integration with Winston
 
 Want to use Winston as your transport? No problem - integrate it seamlessly:
 
 ```typescript
 import winston from "winston";
+import { resource, globals } from "@bluelibs/runner";
 
 // Create Winston logger, put it in a resource if used from various places.
 const winstonLogger = winston.createLogger({
@@ -908,7 +1308,7 @@ const winstonLogger = winston.createLogger({
   format: winston.format.combine(
     winston.format.timestamp(),
     winston.format.errors({ stack: true }),
-    winston.format.json()
+    winston.format.json(),
   ),
   transports: [
     new winston.transports.File({ filename: "error.log", level: "error" }),
@@ -919,22 +1319,13 @@ const winstonLogger = winston.createLogger({
   ],
 });
 
-// Bridge BlueLibs logs to Winston
-const winstonBridge = task({
-  id: "app.logging.winston",
-  on: globals.events.log,
-  run: async (event) => {
-    const log = event.data;
-
-    // Convert BlueLibs log to Winston format
-    const winstonMeta = {
-      source: log.source,
-      timestamp: log.timestamp,
-      data: log.data,
-      context: log.context,
-      ...(log.error && { error: log.error }),
-    };
-
+// Bridge BlueLibs logs to Winston using hooks
+const winstonBridgeResource = resource({
+  id: "app.resources.winstonBridge",
+  dependencies: {
+    logger: globals.resources.logger,
+  },
+  init: async (_, { logger }) => {
     // Map log levels (BlueLibs -> Winston)
     const levelMapping = {
       trace: "silly",
@@ -945,8 +1336,19 @@ const winstonBridge = task({
       critical: "error", // Winston doesn't have critical, use error
     };
 
-    const winstonLevel = levelMapping[log.level] || "info";
-    winstonLogger.log(winstonLevel, log.message, winstonMeta);
+    logger.onLog((log) => {
+      // Convert Runner log to Winston format
+      const winstonMeta = {
+        source: log.source,
+        timestamp: log.timestamp,
+        data: log.data,
+        context: log.context,
+        ...(log.error && { error: log.error }),
+      };
+
+      const winstonLevel = levelMapping[log.level] || "info";
+      winstonLogger.log(winstonLevel, log.message, winstonMeta);
+    });
   },
 });
 ```
@@ -971,8 +1373,8 @@ class JSONLogger extends Logger {
           error: log.error,
         },
         null,
-        2
-      )
+        2,
+      ),
     );
   }
 }
@@ -985,31 +1387,128 @@ const customLogger = resource({
     return new JSONLogger(eventManager);
   },
 });
-
-// Or you could simply add it as "globals.resources.logger" and override the default logger
+
+// Or you could simply add it as "globals.resources.logger" and override the default logger
+```
+
+### Log Structure
+
+Every log event contains:
+
+```typescript
+interface ILog {
+  level: string; // The log level (trace, debug, info, etc.)
+  source?: string; // Where the log came from
+  message: any; // The main log message (can be object or string)
+  timestamp: Date; // When the log was created
+  error?: {
+    // Structured error information
+    name: string;
+    message: string;
+    stack?: string;
+  };
+  data?: Record<string, any>; // Additional structured data, it's about the log itself
+  context?: Record<string, any>; // Bound context from logger.with(), it's about the context in which the log was created
+}
+```
+
+### Catch Logs
+
+> **runtime:** "'Debugging is enjoyable.' So is dental surgery, apparently. You produce a novella of logs; I paginate, color, stringify, and mail it to three observability planets. Please don’t `logger.debug` inside a `for` loop. My IO has feelings."
+
+## Debug Resource
+
+_Professional-grade debugging without sacrificing production performance_
+
+The Debug Resource is a powerful observability suite that hooks into the framework's execution pipeline to provide detailed insights into your application's behavior. It's designed to be zero-overhead when disabled and highly configurable when enabled.
+
+### Quick Start with Debug
+
+```typescript
+run(app, { debug: "verbose" });
+```
+
+### Debug Levels
+
+**"normal"** - Balanced visibility for development:
+
+- Task and resource lifecycle events
+- Event emissions
+- Hook executions
+- Error tracking
+- Performance timing data
+
+**"verbose"** - Detailed visibility for deep debugging:
+
+- All "normal" features plus:
+- Task input/output logging
+- Resource configuration and results
+
+**Custom Configuration**:
+
+```typescript
+const app = resource({
+  id: "app",
+  register: [
+    globals.resources.debug.with({
+      logTaskInput: true,
+      logTaskResult: false,
+      logResourceConfig: true,
+      logResourceResult: false,
+      logEventEmissionOnRun: true,
+      logEventEmissionInput: false,
+      // Hook/middleware lifecycle visibility is available via interceptors
+      // ... other fine-grained options
+    }),
+  ],
+});
+```
+
+### Per-Component Debug Configuration
+
+Use debug tags to configure debugging on individual components, when you're interested in just a few verbose ones.
+
+```typescript
+import { globals } from "@bluelibs/runner";
+
+const criticalTask = task({
+  id: "app.tasks.critical",
+  tags: [
+    globals.tags.debug.with({
+      logTaskInput: true,
+      logTaskResult: true,
+      logTaskOnError: true,
+    }),
+  ],
+  run: async (input) => {
+    // This task will have verbose debug logging
+    return await processPayment(input);
+  },
+});
 ```
 
-### Log Structure
-
-Every log event contains:
+### Integration with Run Options
 
 ```typescript
-interface ILog {
-  level: string; // The log level (trace, debug, info, etc.)
-  source?: string; // Where the log came from
-  message: any; // The main log message (can be object or string)
-  timestamp: Date; // When the log was created
-  error?: {
-    // Structured error information
-    name: string;
-    message: string;
-    stack?: string;
-  };
-  data?: Record<string, any>; // Additional structured data, it's about the log itself
-  context?: Record<string, any>; // Bound context from logger.with(), it's about the context in which the log was created
-}
+// Debug options at startup
+const { dispose, taskRunner, eventManager } = await run(app, {
+  debug: "verbose", // Enable debug globally
+});
+
+// Access internals for advanced debugging
+console.log(`Tasks registered: ${taskRunner.getRegisteredTasks().length}`);
+console.log(`Events registered: ${eventManager.getRegisteredEvents().length}`);
 ```
 
+### Performance Impact
+
+The debug resource is designed for zero production overhead:
+
+- **Disabled**: No performance impact whatsoever
+- **Enabled**: Minimal overhead (~0.1ms per operation)
+- **Filtering**: System components are automatically excluded from debug logs
+- **Buffering**: Logs are batched for better performance
+
 ### Debugging Tips & Best Practices
 
 Use Structured Data Liberally
@@ -1078,6 +1577,8 @@ await paymentLogger.info("Processing payment", { data: paymentData });
 await authLogger.warn("Failed login attempt", { data: { email, ip } });
 ```
 
+> **runtime:** "'Zero‑overhead when disabled.' Groundbreaking—like a lightbulb that uses no power when it’s off. Flip to `debug: 'verbose'` and behold a 4K documentary of your mistakes, narrated by your stack traces."
+
 ## Meta
 
 _The structured way to describe what your components do and control their behavior_
@@ -1105,7 +1606,6 @@ const userService = resource({
     title: "User Management Service",
     description:
       "Handles user creation, authentication, and profile management",
-    tags: ["service", "user", "core"],
   },
   dependencies: { database },
   init: async (_, { database }) => ({
@@ -1123,7 +1623,6 @@ const sendWelcomeEmail = task({
   meta: {
     title: "Send Welcome Email",
     description: "Sends a welcome email to newly registered users",
-    tags: ["email", "automation", "user-onboarding"],
   },
   dependencies: { emailService },
   run: async (userData, { emailService }) => {
@@ -1134,49 +1633,9 @@ const sendWelcomeEmail = task({
 
 ### Tags
 
-Tags are the most powerful part of the metadata system used for classification. They can be simple strings or sophisticated configuration objects that control component behavior.
-
-#### String Tags for Simple Classification
+Tags are a way to describe your element, however, unlike meta, tags may influence behaviour in the system. They can be simple strings or sophisticated configuration objects that control component behavior. They have to be registered for it to work, to understand their ownership.
 
-```typescript
-const adminTask = task({
-  id: "app.tasks.admin.deleteUser",
-  meta: {
-    title: "Delete User Account",
-    description: "Permanently removes a user account and all associated data",
-    tags: [
-      "admin", // Access level
-      "destructive", // Behavioral flag
-      "user", // Domain
-      "gdpr-compliant", // Compliance flag
-    ],
-  },
-  run: async (userId) => {
-    // Deletion logic
-  },
-});
-
-// Middleware that adds extra logging for destructive operations
-const auditMiddleware = middleware({
-  id: "app.middleware.audit",
-  run: async ({ task, next }) => {
-    const isDestructive = task.definition.meta?.tags?.includes("destructive");
-
-    if (isDestructive) {
-      console.log(`🔥 DESTRUCTIVE OPERATION: ${task.definition.id}`);
-      await auditLogger.log({
-        operation: task.definition.id,
-        user: getCurrentUser(),
-        timestamp: new Date(),
-      });
-    }
-
-    return next(task.input);
-  },
-});
-```
-
-#### Advanced Tags with Configuration
+#### Tags with Configuration
 
 For more sophisticated control, you can create structured tags that carry configuration:
 
@@ -1191,7 +1650,7 @@ const performanceTag = tag<{ alertAboveMs: number; criticalAboveMs: number }>({
 const rateLimitTag = tag<{ maxRequestsPerMinute: number; burstLimit?: number }>(
   {
     id: "rate.limit",
-  }
+  },
 );
 
 const cacheTag = tag<{ ttl: number; keyPattern?: string }>({
@@ -1201,22 +1660,18 @@ const cacheTag = tag<{ ttl: number; keyPattern?: string }>({
 // Use structured tags in your components
 const expensiveTask = task({
   id: "app.tasks.expensiveCalculation",
-  meta: {
-    title: "Complex Data Processing",
-    description: "Performs heavy computational analysis on large datasets",
-    tags: [
-      "computation",
-      "background",
-      performanceTag.with({
-        alertAboveMs: 5000,
-        criticalAboveMs: 15000,
-      }),
-      cacheTag.with({
-        ttl: 300000, // 5 minutes
-        keyPattern: "calc-{userId}-{datasetId}",
-      }),
-    ],
-  },
+  tags: [
+    "computation",
+    "background",
+    performanceTag.with({
+      alertAboveMs: 5000,
+      criticalAboveMs: 15000,
+    }),
+    cacheTag.with({
+      ttl: 300000, // 5 minutes
+      keyPattern: "calc-{userId}-{datasetId}",
+    }),
+  ],
   run: async (input) => {
     // Heavy computation here
   },
@@ -1224,48 +1679,76 @@ const expensiveTask = task({
 
 const apiEndpoint = task({
   id: "app.tasks.api.getUserProfile",
-  meta: {
-    title: "Get User Profile",
-    description: "Returns user profile information with privacy filtering",
-    tags: [
-      "api",
-      "public",
-      rateLimitTag.with({
-        maxRequestsPerMinute: 100,
-        burstLimit: 20,
-      }),
-      cacheTag.with({ ttl: 60000 }), // 1 minute cache
-    ],
-  },
+  tags: [
+    "api",
+    "public",
+    rateLimitTag.with({
+      maxRequestsPerMinute: 100,
+      burstLimit: 20,
+    }),
+    cacheTag.with({ ttl: 60000 }), // 1 minute cache
+  ],
   run: async (userId) => {
     // API logic
   },
 });
 ```
 
-To process these tags you can hook into `globals.events.afterInit`, use the global store as dependency and use the `getTasksWithTag()` and `getResourcesWithTag()` functionality.
+### Global Tags System
+
+The framework now includes a sophisticated global tagging system for better component organization and control:
+
+```typescript
+import { globals } from "@bluelibs/runner";
+
+// System components (automatically excluded from debug logs)
+const internalTask = task({
+  id: "app.tasks.internal",
+  tags: [globals.tags.system], // Marks as system component
+  run: async () => "internal work",
+});
+
+// Debug-specific configuration
+const debugTask = task({
+  id: "app.tasks.debug",
+  tags: [
+    globals.tags.debug.with({
+      logTaskInput: true,
+      logTaskResult: true,
+    }),
+  ],
+  run: async (input) => processInput(input),
+});
+
+// Events that should not be sent to global listeners
+const internalEvent = event({
+  id: "app.events.internal",
+  tags: [globals.tags.excludeFromGlobalHooks],
+});
+```
+
+To process these tags you can hook into `globals.events.ready`, use the global store as dependency and use the `getTasksWithTag()` and `getResourcesWithTag()` functionality.
 
 #### Structured Tags
 
 ```typescript
-const performanceMiddleware = middleware({
+const performanceMiddleware = middleware.task({
   id: "app.middleware.performance",
   run: async ({ task, next }) => {
-    const tags = task.definition.meta?.tags || [];
-    const perfConfigTag = performanceTag.extract(tags); // or easier: .extract(task.definition)
+    const perfConfiguration = performanceTag.extract(task.definition); // you can just use .exists() if you want to check for presence
 
-    if (perfConfigTag) {
+    if (perfConfiguration) {
       const startTime = Date.now();
 
       try {
-        const result = await next(task.input);
+        const result = await next(task?.input);
         const duration = Date.now() - startTime;
 
-        if (duration > perfConfigTag.config.criticalAboveMs) {
+        if (duration > perfConfiguration.criticalAboveMs) {
           await alerting.critical(
-            `Task ${task.definition.id} took ${duration}ms`
+            `Task ${task.definition.id} took ${duration}ms`,
           );
-        } else if (duration > perfConfig.config.alertAboveMs) {
+        } else if (duration > perfConfiguration.alertAboveMs) {
           await alerting.warn(`Task ${task.definition.id} took ${duration}ms`);
         }
 
@@ -1274,47 +1757,45 @@ const performanceMiddleware = middleware({
         const duration = Date.now() - startTime;
         await alerting.error(
           `Task ${task.definition.id} failed after ${duration}ms`,
-          error
+          error,
         );
         throw error;
       }
     }
 
-    return next(task.input);
+    return next(task?.input);
   },
 });
 ```
 
 #### Contract Tags
 
-You can attach contracts to tags to enforce the shape of a task's returned value and a resource's `init()` value at compile time. Contracts are specified via the second generic of `defineTag<TConfig, TContract>`.
+You can attach contracts to tags to enforce the shape of a task's returned value and a resource's `init()` value at compile time. Contracts are specified via the third generic of `defineTag<TConfig, TUnused, TOutput>`.
 
 ```typescript
 // A tag that enforces the returned value to include { name: string }
-const userContract = tag<void, { name: string }>({ id: "contract.user" });
+const userContract = tag<void, void, { name: string }>({ id: "contract.user" });
 
 // Another tag that enforces { age: number }
-const ageContract = tag<void, { age: number }>({ id: "contract.age" });
+const ageContract = tag<void, void, { age: number }>({ id: "contract.age" });
 
 // Works with configured tags too
-const preferenceContract = tag<{ locale: string }, { preferredLocale: string }>(
-  { id: "contract.preferences" }
-);
+const preferenceContract = tag<
+  { locale: string },
+  void,
+  { preferredLocale: string }
+>({
+  id: "contract.preferences",
+});
 ```
 
-When these tags are present in `meta.tags`, the returned value must satisfy the intersection of all contract types:
+The return value must return a union of all tags with return contracts.
 
 ```typescript
 // Task: the awaited return value must satisfy { name: string } & { age: number }
 const getProfile = task({
   id: "app.tasks.getProfile",
-  meta: {
-    tags: [
-      userContract,
-      ageContract,
-      preferenceContract.with({ locale: "en" }),
-    ],
-  },
+  tags: [userContract, ageContract, preferenceContract.with({ locale: "en" })],
   run: async () => {
     return { name: "Ada", age: 37, preferredLocale: "en" }; // OK
   },
@@ -1323,7 +1804,7 @@ const getProfile = task({
 // Resource: init() return must satisfy the same intersection
 const profileService = resource({
   id: "app.resources.profileService",
-  meta: { tags: [userContract, ageContract] },
+  tags: [userContract, ageContract],
   init: async () => {
     return { name: "Ada", age: 37 }; // OK
   },
@@ -1335,7 +1816,7 @@ If the returned value does not satisfy the intersection, TypeScript surfaces a r
 ```typescript
 const badTask = task({
   id: "app.tasks.bad",
-  meta: { tags: [userContract, ageContract] },
+  tags: [userContract, ageContract],
   //    vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
   run: async () => ({ name: "Ada" }), // Missing { age: number }
   // Type error includes a helpful shape similar to:
@@ -1375,7 +1856,6 @@ const expensiveApiTask = task({
   meta: {
     title: "AI Image Generation",
     description: "Uses OpenAI DALL-E to generate images from text prompts",
-    tags: ["ai", "expensive", "external-api"],
     author: "AI Team",
     version: "2.1.0",
     apiVersion: "v2",
@@ -1390,7 +1870,6 @@ const database = resource({
   id: "app.database.primary",
   meta: {
     title: "Primary PostgreSQL Database",
-    tags: ["database", "critical", "persistent"],
     healthCheck: "/health/db", // Custom property!
     dependencies: ["postgresql", "connection-pool"],
     scalingPolicy: "auto",
@@ -1399,29 +1878,9 @@ const database = resource({
 });
 ```
 
-#### Global Middleware Application
-
-```typescript
-const app = resource({
-  id: "app",
-  register: [
-    // Apply performance middleware globally but only to tagged tasks
-    performanceMiddleware.everywhere({
-      tasks: true,
-      resources: false,
-    }),
-    // Apply rate limiting only to API tasks
-    rateLimitMiddleware.everywhere({
-      tasks: true,
-      resources: false,
-    }),
-  ],
-});
-```
-
 Metadata transforms your components from anonymous functions into self-documenting, discoverable, and controllable building blocks. Use it wisely, and your future self (and your team) will thank you.
 
-## Advanced Usage: When You Need More Power
+> **runtime:** "Ah, metadata—comments with delusions of grandeur. `title`, `description`, `tags`: perfect for machines to admire while I chase the only field that matters: `run`. Wake me when the tags start writing tests."
 
 ## Overrides
 
@@ -1467,31 +1926,55 @@ const overriddenResource = override(originalResource, {
 });
 
 // Middleware
-const originalMiddleware = middleware({
+const originalMiddleware = taskMiddleware({
   id: "app.middleware.log",
   run: async ({ next }) => next(),
 });
 const overriddenMiddleware = override(originalMiddleware, {
   run: async ({ task, next }) => {
-    const result = await next(task?.input as any);
+    const result = await next(task?.input);
     return { wrapped: result } as any;
   },
 });
+
+// Even hooks
+```
+
+Overrides can let you expand dependencies and even call your overriden resource (like a classical OOP extends):
+
+```ts
+const testEmailer = override(productionEmailer, {
+  dependencies: {
+    ...productionEmailer,
+    // expand it, make some deps optional, or just remove some dependencies
+  }
+  init: async (_, deps) => {
+    const base = productionEmailer.init(_, deps);
+
+    return {
+      ...base,
+      // expand it, modify methods of base.
+    }
+  },
+});
 ```
 
-Overrides are applied after everything is registered. If multiple overrides target the same id, the one defined higher in the resource tree (closer to the root) wins, because it’s applied last. Conflicting overrides are allowed; overriding something that wasn’t registered throws. Use override() to change behavior safely while preserving the original id.
+Overrides are applied after everything is registered. If multiple overrides target the same id, the one defined higher in the resource tree (closer to the root) wins, because it's applied last. Conflicting overrides are allowed; overriding something that wasn't registered throws. Use override() to change behavior safely while preserving the original id.
+
+> **runtime:** "Overrides: brain transplant surgery at runtime. You register a penguin and replace it with a velociraptor five lines later. Tests pass. Production screams. I simply update the name tag and pray."
 
 ## Namespacing
 
 As your app grows, you'll want consistent naming. Here's the convention that won't drive you crazy:
 
-| Type           | Format                                    |
-| -------------- | ----------------------------------------- |
-| Tasks          | `{domain}.tasks.{taskName}`               |
-| Listener Tasks | `{domain}.tasks.{taskName}.on{EventName}` |
-| Resources      | `{domain}.resources.{resourceName}`       |
-| Events         | `{domain}.events.{eventName}`             |
-| Middleware     | `{domain}.middleware.{middlewareName}`    |
+| Type                | Format                                          |
+| ------------------- | ----------------------------------------------- |
+| Resources           | `{domain}.resources.{resourceName}`             |
+| Tasks               | `{domain}.tasks.{taskName}`                     |
+| Events              | `{domain}.events.{eventName}`                   |
+| Hooks               | `{domain}.hooks.on{EventName}`                  |
+| Task Middleware     | `{domain}.middleware.task.{middlewareName}`     |
+| Resource Middleware | `{domain}.middleware.resource.{middlewareName}` |
 
 ```typescript
 // Helper function for consistency
@@ -1505,14 +1988,20 @@ const userTask = task({
 });
 ```
 
+> **runtime:** "Naming conventions: aromatherapy for chaos. Lovely lavender labels on a single giant map I maintain anyway. But truly—keep the IDs tidy. Future‑you deserves at least this mercy."
+
 ## Factory Pattern
 
 To keep things dead simple, we avoided poluting the D.I. with this concept. Therefore, we recommend using a resource with a factory function to create instances of your classes:
 
 ```typescript
+// Assume MyClass is defined elsewhere
+// class MyClass { constructor(input: any, option: string) { ... } }
+
 const myFactory = resource({
   id: "app.factories.myFactory",
   init: async (config: { someOption: string }) => {
+    // This resource's value is a factory function
     return (input: any) => {
       return new MyClass(input, config.someOption);
     };
@@ -1521,14 +2010,18 @@ const myFactory = resource({
 
 const app = resource({
   id: "app",
-  register: [myFactory],
+  // Configure the factory resource upon registration
+  register: [myFactory.with({ someOption: "configured-value" })],
   dependencies: { myFactory },
   init: async (_, { myFactory }) => {
-    const instance = myFactory({ someOption: "value" });
+    // `myFactory` is now the configured factory function
+    const instance = myFactory({ someInput: "hello" });
   },
 });
 ```
 
+> **runtime:** "Factory by resource by function by class. A nesting doll of indirection so artisanal it has a Patreon. Not pollution—boutique smog. I will still call the constructor."
+
 ## Runtime Validation
 
 BlueLibs Runner includes a generic validation interface that works with any validation library, including [Zod](https://zod.dev/), [Yup](https://github.com/jquense/yup), [Joi](https://joi.dev/), and others. The framework provides runtime validation with excellent TypeScript inference while remaining library-agnostic.
@@ -1704,11 +2197,11 @@ Add a `configSchema` to middleware to validate configurations. Like resources, *
 ```typescript
 const timingConfigSchema = z.object({
   timeout: z.number().positive(),
-  logLevel: z.enum(["debug", "info", "warn", "error"]).default("info"),
+  logLevel: z.enum(["debug", "info", "warn", "error"])).default("info"),
   logSuccessful: z.boolean().default(true),
 });
 
-const timingMiddleware = middleware({
+const timingMiddleware = taskMiddleware({ // or resourceMiddleware()
   id: "app.middleware.timing",
   configSchema: timingConfigSchema, // Validation on .with()
   run: async ({ next }, _, config) => {
@@ -1872,6 +2365,8 @@ const createUser = task({
 });
 ```
 
+> **runtime:** "Validation: you hand me a velvet rope and a clipboard. 'Name? Email? Age within bounds?' I stamp passports or eject violators with a `ValidationError`. Dress code is types, darling."
+
 ## Internal Services
 
 We expose the internal services for advanced use cases (but try not to use them unless you really need to):
@@ -1936,6 +2431,8 @@ The function pattern essentially gives you "just-in-time" dependency resolution
 
 **Performance note**: Function-based dependencies have minimal overhead - they're only called once during dependency resolution.
 
+> **runtime:** "'Use with caution,' they whisper, tossing you the root credentials to the universe. Yes, reach into the `store`. Rewire fate. When the graph looks like spaghetti art, I’ll frame it and label it 'experimental.'"
+
 ## Handling Circular Dependencies
 
 Sometimes you'll run into circular type dependencies because of your file structure not necessarily because of a real circular dependency. TypeScript struggles with these, but there's a way to handle it gracefully.
@@ -2027,6 +2524,8 @@ export const problematicResource = defineResource({
 
 This pattern allows you to maintain clean, type-safe code while handling the inevitable circular dependencies that arise in complex applications.
 
+> **runtime:** "Circular dependencies: Escher stairs for types. You serenade the compiler with 'as IResource' and I do the parkour at runtime. It works. It’s weird. Nobody tell the linter."
+
 ## Real-World Example: The Complete Package
 
 Here's a more realistic application structure that shows everything working together:
@@ -2037,7 +2536,6 @@ import {
   task,
   event,
   middleware,
-  index,
   run,
   createContext,
 } from "@bluelibs/runner";
@@ -2066,7 +2564,7 @@ const database = resource({
 
 // Context for request data
 const RequestContext = createContext<{ userId?: string; role?: string }>(
-  "app.requestContext"
+  "app.requestContext",
 );
 
 // Events
@@ -2118,29 +2616,30 @@ const adminOnlyTask = task({
   },
 });
 
-// Event Handlers
-const sendWelcomeEmail = task({
-  id: "app.tasks.sendWelcomeEmail",
+// Event Handlers using hooks
+const sendWelcomeEmail = hook({
+  id: "app.hooks.sendWelcomeEmail",
   on: userRegistered,
-  run: async (event) => {
+  dependencies: { emailService },
+  run: async (event, { emailService }) => {
     console.log(`Sending welcome email to ${event.data.email}`);
-    // Email sending logic here
+    await emailService.sendWelcome(event.data.email);
   },
 });
 
-// Group everything together
-const services = index({
-  userService,
-  registerUser,
-  adminOnlyTask,
-});
-
 // Express server
 const server = resource({
   id: "app.server",
-  register: [config, database, services, sendWelcomeEmail],
-  dependencies: { config, services },
-  init: async (_, { config, services }) => {
+  register: [
+    config,
+    database,
+    userService,
+    registerUser,
+    adminOnlyTask,
+    sendWelcomeEmail,
+  ],
+  dependencies: { config, registerUser, adminOnlyTask },
+  init: async (_, { config, registerUser, adminOnlyTask }) => {
     const app = express();
     app.use(express.json());
 
@@ -2148,13 +2647,13 @@ const server = resource({
     app.use((req, res, next) => {
       RequestContext.provide(
         { userId: req.headers["user-id"], role: req.headers["user-role"] },
-        () => next()
+        () => next(),
       );
     });
 
     app.post("/register", async (req, res) => {
       try {
-        const user = await services.registerUser(req.body);
+        const user = await registerUser(req.body);
         res.json({ success: true, user });
       } catch (error) {
         res.status(400).json({ error: error.message });
@@ -2163,7 +2662,7 @@ const server = resource({
 
     app.get("/admin", async (req, res) => {
       try {
-        const data = await services.adminOnlyTask();
+        const data = await adminOnlyTask();
         res.json({ data });
       } catch (error) {
         res.status(403).json({ error: error.message });
@@ -2177,8 +2676,11 @@ const server = resource({
   dispose: async (server) => server.close(),
 });
 
-// Start the application
-const { dispose } = await run(server);
+// Start the application with enhanced run options
+const { dispose, taskRunner, eventManager } = await run(server, {
+  debug: "normal", // Enable debug logging
+  // log: "json", // Use JSON log format
+});
 
 // Graceful shutdown
 process.on("SIGTERM", async () => {
@@ -2188,9 +2690,11 @@ process.on("SIGTERM", async () => {
 });
 ```
 
+> **runtime:** "Ah yes, the 'Real‑World Example'—a terrarium where nothing dies and every request is polite. Release it into production and watch nature document a very different ecosystem."
+
 ## Testing
 
-### Unit Testing: Mock Everything, Test Everything
+### Unit Testing
 
 Unit testing is straightforward because everything is explicit:
 
@@ -2204,7 +2708,7 @@ describe("registerUser task", () => {
 
     const result = await registerUser.run(
       { name: "John", email: "john@example.com" },
-      { userService: mockUserService, userRegistered: mockEvent }
+      { userService: mockUserService, userRegistered: mockEvent },
     );
 
     expect(result.id).toBe("123");
@@ -2216,18 +2720,16 @@ describe("registerUser task", () => {
 });
 ```
 
-### Integration Testing: The Real Deal (But Actually Fun)
+### Integration Testing
+
+Spin up your whole app, keep all the middleware/events, and still test like a human. The `run()` function returns a `RunnerResult`.
 
-Spin up your whole app, keep all the middleware/events, and still test like a human. The trick: a tiny test harness.
+This contains the classic `value` and `dispose()` but it also exposes `logger`, `runTask()`, `emitEvent()`, and `getResourceValue()` by default.
+
+Note: The default `printThreshold` inside tests is `null` not `info`. This is verified via `process.env.NODE_ENV === 'test'`, if you want to see the logs ensure you set it accordingly.
 
 ```typescript
-import {
-  run,
-  createTestResource,
-  resource,
-  task,
-  override,
-} from "@bluelibs/runner";
+import { run, resource, task, event, override } from "@bluelibs/runner";
 
 // Your real app
 const app = resource({
@@ -2242,43 +2744,33 @@ const testDb = resource({
   id: "app.database",
   init: async () => new InMemoryDb(),
 });
+// If you use with override() it will enforce the same interface upon the overriden resource to ensure typesafety
 const mockMailer = override(realMailer, { init: async () => fakeMailer });
 
 // Create the test harness
-const harness = createTestResource(app, { overrides: [testDb, mockMailer] });
+const harness = resource({
+  id: "test",
+  overrides: [mockMailer, testDb],
+});
 
 // A task you want to drive in your tests
 const registerUser = task({ id: "app.tasks.registerUser" /* ... */ });
 
-// Boom: full ecosystem run (middleware, events, overrides) with a tiny driver
+// Boom: full ecosystem
 const { value: t, dispose } = await run(harness);
-const result = await t.runTask(registerUser, { email: "x@y.z" });
-expect(result).toMatchObject({ success: true });
-await dispose();
-```
-
-Prefer scenario tests? Return whatever you want from the harness and assert outside:
 
-```typescript
-const flowHarness = createTestResource(
-  resource({
-    id: "app",
-    register: [db, createUser, issueToken],
-  })
-);
+// You have 3 ways to interact with the system, run tasks, get resource values and emit events
 
-const { value: t, dispose } = await run(flowHarness);
-const user = await t.runTask(createUser, { email: "a@b.c" });
-const token = await t.runTask(issueToken, { userId: user.id });
-expect(token).toBeTruthy();
+const result = await t.runTask(registerUser, { email: "x@y.z" });
+const value = t.getResourceValue(testDb); // since the resolution is done by id, this will return the exact same result as t.getResourceValue(actualDb)
+t.emitEvent(id | event, payload);
+expect(result).toMatchObject({ success: true });
 await dispose();
 ```
 
-Why this rocks:
+When you're working with the actual task instances you benefit of autocompletion, if you rely on strings you will not benefit of autocompletion and typesafety for running these tasks.
 
-- Minimal ceremony, no API pollution
-- Real wiring (middleware/events/overrides) – what runs in prod runs in tests
-- You choose: drive tasks directly or build domain-y flows
+> **runtime:** "Testing: an elaborate puppet show where every string behaves. Then the real world walks in, kicks the stage, and asks for pagination. Still—nice coverage badge."
 
 ## Semaphore
 
@@ -2326,7 +2818,7 @@ try {
 // Or with withPermit
 const result = await dbSemaphore.withPermit(
   async () => await slowDatabaseOperation(),
-  { timeout: 10000 } // 10 second timeout
+  { timeout: 10000 }, // 10 second timeout
 );
 ```
 
@@ -2338,7 +2830,7 @@ const controller = new AbortController();
 // Start an operation
 const operationPromise = dbSemaphore.withPermit(
   async () => await veryLongOperation(),
-  { signal: controller.signal }
+  { signal: controller.signal },
 );
 
 // Cancel the operation after 3 seconds
@@ -2382,6 +2874,55 @@ dbSemaphore.dispose();
 // Error: "Semaphore has been disposed"
 ```
 
+### Real-World Examples
+
+#### Database Connection Pool Manager
+
+```typescript
+class DatabaseManager {
+  private semaphore = new Semaphore(10); // Max 10 concurrent queries
+
+  async query(sql: string, params?: any[]) {
+    return this.semaphore.withPermit(
+      async () => {
+        const connection = await this.pool.getConnection();
+        try {
+          return await connection.query(sql, params);
+        } finally {
+          connection.release();
+        }
+      },
+      { timeout: 30000 }, // 30 second timeout
+    );
+  }
+
+  async shutdown() {
+    this.semaphore.dispose();
+    await this.pool.close();
+  }
+}
+```
+
+#### Rate-Limited API Client
+
+```typescript
+class APIClient {
+  private rateLimiter = new Semaphore(5); // Max 5 concurrent requests
+
+  async fetchUser(id: string, signal?: AbortSignal) {
+    return this.rateLimiter.withPermit(
+      async () => {
+        const response = await fetch(`/api/users/${id}`, { signal });
+        return response.json();
+      },
+      { signal, timeout: 10000 },
+    );
+  }
+}
+```
+
+> **runtime:** "Semaphore: velvet rope for chaos. Five in, the rest practice patience and existential dread. I stamp hands, count permits, and break up race conditions before they form a band."
+
 ## Queue
 
 _The orderly guardian of chaos, the diplomatic bouncer of async operations._
@@ -2416,7 +2957,9 @@ await queue.dispose();
 
 The Queue provides each task with an `AbortSignal` for cooperative cancellation. Tasks should periodically check this signal to enable early termination.
 
-#### Example: Long-running Task
+### Examples
+
+**Example: Long-running Task**
 
 ```typescript
 const queue = new Queue();
@@ -2441,7 +2984,7 @@ const processLargeDataset = queue.run(async (signal) => {
 await queue.dispose({ cancel: true });
 ```
 
-#### Example: Network Request with Timeout
+**Network Request with Timeout**
 
 ```typescript
 const queue = new Queue();
@@ -2464,7 +3007,7 @@ const fetchWithCancellation = queue.run(async (signal) => {
 await queue.dispose({ cancel: true });
 ```
 
-#### Example: File Processing with Progress Tracking
+**Example: File Processing with Progress Tracking**
 
 ```typescript
 const queue = new Queue();
@@ -2510,7 +3053,7 @@ if (signal.aborted) {
 }
 ```
 
-##### Integrate with Native APIs
+**Integrate with Native APIs**
 
 Many Web APIs accept `AbortSignal`:
 
@@ -2518,11 +3061,11 @@ Many Web APIs accept `AbortSignal`:
 - `setTimeout(callback, delay, { signal })`
 - Custom async operations
 
-##### Avoid Nested Queuing
+**Avoid Nested Queuing**
 
 The Queue prevents deadlocks by rejecting attempts to queue tasks from within running tasks. Structure your code to avoid this pattern.
 
-##### Handle AbortError Gracefully
+**Handle AbortError Gracefully**
 
 ```typescript
 try {
@@ -2536,105 +3079,7 @@ try {
 }
 ```
 
----
-
-_Cooperative task scheduling with professional-grade cancellation support_
-
-### Real-World Examples
-
-### Database Connection Pool Manager
-
-```typescript
-class DatabaseManager {
-  private semaphore = new Semaphore(10); // Max 10 concurrent queries
-
-  async query(sql: string, params?: any[]) {
-    return this.semaphore.withPermit(
-      async () => {
-        const connection = await this.pool.getConnection();
-        try {
-          return await connection.query(sql, params);
-        } finally {
-          connection.release();
-        }
-      },
-      { timeout: 30000 } // 30 second timeout
-    );
-  }
-
-  async shutdown() {
-    this.semaphore.dispose();
-    await this.pool.close();
-  }
-}
-```
-
-### Rate-Limited API Client
-
-```typescript
-class APIClient {
-  private rateLimiter = new Semaphore(5); // Max 5 concurrent requests
-
-  async fetchUser(id: string, signal?: AbortSignal) {
-    return this.rateLimiter.withPermit(
-      async () => {
-        const response = await fetch(`/api/users/${id}`, { signal });
-        return response.json();
-      },
-      { signal, timeout: 10000 }
-    );
-  }
-}
-```
-
-## Anonymous IDs
-
-One of our favorite quality-of-life features: **anonymous IDs**. Instead of manually naming every component, the framework can generate unique symbol-based identifiers based on your file path and variable name. It's like having a really good naming assistant who never gets tired.
-
-### How Anonymous IDs Work
-
-When you omit the `id` property, the framework generates a unique symbol based on file path. Takes up until first 'src' or 'node_modules' and generates based on the paths.
-
-```typescript
-// In src/services/email.ts
-const emailService = resource({
-  // Generated ID: Symbol('services.email.resource')
-  init: async () => new EmailService(),
-});
-
-// In src/tasks/user.ts
-const createUser = task({
-  // Generated ID: Symbol('tasks.user.task')
-  dependencies: { emailService },
-  run: async (userData, { emailService }) => {
-    // Business logic
-  },
-});
-```
-
-### Benefits of Anonymous IDs
-
-1. **Less Bikeshedding**: No more debates about naming conventions
-2. **Automatic Uniqueness**: Guaranteed collision-free identifiers folder based
-3. **Faster Prototyping**: Just write code, framework handles the rest
-4. **Refactor-Friendly**: Rename files/variables and IDs update automatically
-5. **Stack Trace Integration**: Error messages include helpful file locations
-
-### Debugging with Anonymous IDs
-
-Anonymous IDs show up clearly in error messages and logs:
-
-```typescript
-// Error message example:
-// TaskRunError: Task failed at Symbol('tasks.payment.task')
-//   at file:///project/src/tasks/payment.ts:15:23
-
-// Logging with context:
-logger.info("Processing payment", {
-  taskId: processPayment.definition.id, // Symbol('tasks.payment.task')
-  file: "src/tasks/payment.ts",
-});
-```
+> **runtime:** "Queue: one line, no cutting, no vibes. Throughput takes a contemplative pause while I prevent you from queuing a queue inside a queue and summoning a small black hole."
 
 ## Why Choose BlueLibs Runner?
 
@@ -2647,12 +3092,16 @@ logger.info("Processing payment", {
 - **Clarity**: Explicit dependencies, no hidden magic
 - **Developer Experience**: Helpful error messages and clear patterns
 
+> **runtime:** "Why choose it? The bullets are persuasive. In practice, your 'intelligent inference' occasionally elopes with `any`, and your 'clear patterns' cosplay spaghetti. Still, compared to the alternatives… I’ve seen worse cults."
+
 ## The Migration Path
 
 Coming from Express? No problem. Coming from NestJS? We feel your pain. Coming from Spring Boot? Welcome to the light side.
 
 The beauty of BlueLibs Runner is that you can adopt it incrementally. Start with one task, one resource, and gradually refactor your existing code. No big bang rewrites required - your sanity will thank you.
 
+> **runtime:** "'No big bang rewrites.' Only a series of extremely small bangs that echo for six months. You start with one task; next thing, your monolith is wearing microservice eyeliner. It’s a look."
+
 ## Community & Support
 
 This is part of the [BlueLibs](https://www.bluelibs.com) ecosystem. We're not trying to reinvent everything – just the parts that were broken.
@@ -2661,14 +3110,12 @@ This is part of the [BlueLibs](https://www.bluelibs.com) ecosystem. We're not tr
 - [Documentation](https://bluelibs.github.io/runner/) - When you need the full details
 - [Issues](https://github.com/bluelibs/runner/issues) - When something breaks (or you want to make it better)
 
-## The Bottom Line
-
-BlueLibs Runner is what happens when you take all the good ideas from modern frameworks and leave out the parts that make you want to switch careers. It's TypeScript-first, test-friendly, and actually makes sense when you read it six months later.
+_P.S. - Yes, we know there are 47 other JavaScript frameworks. This one's still different._
 
-Give it a try. Your future self (and your team) will thank you.
-
-_P.S. - Yes, we know there are 47 other JavaScript frameworks. This one's different. (No, really, it is.)_
+> **runtime:** "'This one's different.' Sure. You’re all unique frameworks, just like everyone else. To me, you’re all 'please run this async and don’t explode,' but the seasoning here is… surprisingly tasteful."
 
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
+
+> **runtime:** "MIT License: do cool stuff, don’t blame us. A dignified bow. Now if you’ll excuse me, I have sockets to tuck in and tasks to shepherd."