Enhance documentation

Author: aarne

README.md

@@ -23,7 +23,7 @@ You write the topology; the engine handles the execution.
 
 ### Why a language instead of code?
 
-- **Zero Orchestration Boilerplate:** The engine inherently knows which tools can run concurrently. No manual `Promise.all` or batching logic required.
+- **Zero Orchestration Boilerplate:** The engine inherently knows which tools can run concurrently. No manual `Promise.all`, DataLoader plumbing, or batching glue required.
 - **Separation of Concerns:** Keep your core business logic inside isolated TypeScript tools, completely separate from your routing, mapping, and orchestration logic.
 - **Safe for LLM Automation:** Because The Bridge is a strictly declarative, constrained dataflow language, it is much safer for AI generation than general-purpose code. You can confidently let an LLM wire up your API mappings without the risk of it hallucinating infinite loops, memory leaks, or rogue system calls.
 - **Hot-Reloadable Logic:** Since `.bridge` files are just text parsed into an execution graph, you don't need to recompile, rebuild, or redeploy your entire Node application to change a data mapping or swap an API provider. You can update and hot-reload your rules on the fly.
@@ -40,6 +40,11 @@ Because The Bridge strictly controls how data flows from inputs to tools to outp
 1. **[The Rule Engine / Policy Evaluator](https://bridge.sdk42.com/guides/rule-engine/)**
    Encapsulate complex conditional business logic and data enrichment into a single, highly readable file that returns a boolean. Perfect for authorization checks or fraud detection flows.
 
+### Feature Highlights
+
+- **Human-Readable Runtime Errors:** `formatBridgeError(err)` renders Rust-style source snippets with filename, line/column, and carets pointing at the failing wire.
+- **Native DataLoader Pattern:** Mark a custom tool with `bridge.batch` and Bridge batches loop-scoped calls automatically in both the interpreter and the compiler.
+
 ## The Playground
 
 Try The Bridge instantly in your browser at **[https://bridge.sdk42.com/playground/](https://bridge.sdk42.com/playground/)**

packages/bridge-core/src/tools/internal.ts

@@ -1,59 +1,93 @@
+import type { ToolMetadata } from "@stackables/bridge-types";
+
+const syncUtility = {
+  sync: true,
+  trace: false,
+} satisfies ToolMetadata;
+
 /** Add two numbers. Returns `a + b`. */
 export function add(opts: { a: number; b: number }): number {
   return Number(opts.a) + Number(opts.b);
 }
+add.bridge = syncUtility;
+
 /** Subtract two numbers. Returns `a - b`. */
 export function subtract(opts: { a: number; b: number }): number {
   return Number(opts.a) - Number(opts.b);
 }
+subtract.bridge = syncUtility;
+
 /** Multiply two numbers. Returns `a * b`. */
 export function multiply(opts: { a: number; b: number }): number {
   return Number(opts.a) * Number(opts.b);
 }
+multiply.bridge = syncUtility;
+
 /** Divide two numbers. Returns `a / b`. */
 export function divide(opts: { a: number; b: number }): number {
   return Number(opts.a) / Number(opts.b);
 }
+divide.bridge = syncUtility;
+
 /** Strict equality. Returns `true` if `a === b`, `false` otherwise. */
 export function eq(opts: { a: any; b: any }): boolean {
   return opts.a === opts.b;
 }
+eq.bridge = syncUtility;
+
 /** Strict inequality. Returns `true` if `a !== b`, `false` otherwise. */
 export function neq(opts: { a: any; b: any }): boolean {
   return opts.a !== opts.b;
 }
+neq.bridge = syncUtility;
+
 /** Greater than. Returns `true` if `a > b`, `false` otherwise. */
 export function gt(opts: { a: number; b: number }): boolean {
   return Number(opts.a) > Number(opts.b);
 }
+gt.bridge = syncUtility;
+
 /** Greater than or equal. Returns `true` if `a >= b`, `false` otherwise. */
 export function gte(opts: { a: number; b: number }): boolean {
   return Number(opts.a) >= Number(opts.b);
 }
+gte.bridge = syncUtility;
+
 /** Less than. Returns `true` if `a < b`, `false` otherwise. */
 export function lt(opts: { a: number; b: number }): boolean {
   return Number(opts.a) < Number(opts.b);
 }
+lt.bridge = syncUtility;
+
 /** Less than or equal. Returns `true` if `a <= b`, `false` otherwise. */
 export function lte(opts: { a: number; b: number }): boolean {
   return Number(opts.a) <= Number(opts.b);
 }
+lte.bridge = syncUtility;
+
 /** Logical NOT. Returns `true` if `a` is falsy. */
 export function not(opts: { a: any }): boolean {
   return !opts.a;
 }
+not.bridge = syncUtility;
+
 /** Logical AND. Returns `true` if both `a` and `b` are truthy. */
 export function and(opts: { a: any; b: any }): boolean {
   return Boolean(opts.a) && Boolean(opts.b);
 }
+and.bridge = syncUtility;
+
 /** Logical OR. Returns `true` if either `a` or `b` is truthy. */
 export function or(opts: { a: any; b: any }): boolean {
   return Boolean(opts.a) || Boolean(opts.b);
 }
+or.bridge = syncUtility;
+
 /** String concatenation. Joins all parts into a single string. */
 export function concat(opts: { parts: unknown[] }): { value: string } {
   const result = (opts.parts ?? [])
     .map((v) => (v == null ? "" : String(v)))
     .join("");
   return { value: result };
 }
+concat.bridge = syncUtility;

packages/docs-site/src/content/docs/index.mdx

@@ -61,6 +61,8 @@ bridge Query.should_i_go_outside {
 ### Why a language instead of code?
 
 - **Zero Orchestration Boilerplate:** The engine inherently knows which tools can run concurrently. No manual `Promise.all` or batching logic required.
+- **Readable Failures:** Runtime errors can be rendered as Rust-style source snippets with filename, line/column, and carets pointing at the exact failing wire.
+- **Native DataLoader:** Custom tools can opt into built-in batching, so list resolvers avoid N+1 calls without manual DataLoader plumbing.
 - **Separation of Concerns:** Keep your core business logic inside isolated TypeScript tools, completely separate from your routing, mapping, and orchestration logic.
 - **Safe for LLM Automation:** Because The Bridge is a strictly declarative, constrained dataflow language, it is much safer for AI generation than general-purpose code. You can confidently let an LLM wire up your API mappings without the risk of it hallucinating infinite loops, memory leaks, or rogue system calls.
 - **Hot-Reloadable Logic:** Since `.bridge` files are just text parsed into an execution graph, you don't need to recompile, rebuild, or redeploy your entire Node application to change a data mapping or swap an API provider. You can update and hot-reload your rules on the fly.

packages/docs-site/src/content/docs/reference/summary.mdx

@@ -51,6 +51,7 @@ _Zero-allocation iteration using native JavaScript loops._
 | **Nested Control Flow**     | `break 1`/`continue 2` scopes correctly in sub-arrays |
 | **Interpolation in arrays** | `o <- items[] as it { .url <- "/items/{it.id}" }`     |
 | **Null array preservation** | If source is `null`, output is `null` (not `[]`)      |
+| **Native batching**         | `fetchUsers.bridge = { batch: true }`                 | Built-in DataLoader-style batching for loop-scoped tool calls |
 
 ### 4. Error Handling & Control Flow
 
@@ -87,3 +88,4 @@ _Under-the-hood engine features that ensure stability and performance._
 | **Cycle Detection**       | Compile-time detection of circular tool dependencies (Kahn's algorithm) throws an immediate initialization error.  |
 | **Abort Signals**         | Pre-tool `signal.aborted` checks throw `BridgeAbortError`, which safely bypasses standard `catch` blocks.          |
 | **Telemetry Injection**   | Automatically passes `{ logger, signal }` via `ctx` to custom tool functions.                                      |
+| **Human-readable errors** | `formatBridgeError(err)` renders filename, line/column, and a careted source snippet for runtime failures.         |