cliodot 1.2.0 → 1.2.2

package/README.md

@@ -1,6 +1,8 @@
 # cliodot
 
-SDK for building workflows, APIs, and functions with Cliodot Flowsync. Define workflows and functions in code, run them locally, and optionally sync with your Flowsync account.
+SDK for building workflows, APIs, and functions with Cliodot Flowsync. Define workflows and functions in code, run them locally, and sync with your Cliodot account.
+
+**Full documentation:** [docs.cliodot.com](https://docs.cliodot.com)
 
 ## Installation
 
@@ -8,49 +10,25 @@ SDK for building workflows, APIs, and functions with Cliodot Flowsync. Define wo
 npm install cliodot
 ```
 
-### Module Support
-
-Cliodot supports both **ES Modules** (recommended for Node.js 16+, TypeScript, and modern frameworks) and **CommonJS**.
+**ES Modules / TypeScript**
 
-**ES Modules (ESM) / TypeScript**
 ```javascript
 import { flosync, v } from 'cliodot';
-// or: import { flosync, variable as v } from 'cliodot';
-```
-
-**CommonJS (CJS)**
-```javascript
-const { flosync, v } = require('cliodot');
-// or: const { flosync, variable: v } = require('cliodot');
 ```
 
-**Note for some ESM environments:**
-If you encounter `SyntaxError: Named export 'flosync' not found`, use the default import instead:
+**CommonJS**
 
 ```javascript
-import pkg from 'cliodot';
-const { flosync, v } = pkg;
-```
-
-Optional peer dependencies:
-
-```bash
-npm install mongodb mysql2
-```
-
-For PostgreSQL and Redis:
-
-```bash
-npm install pg ioredis
+const { flosync, v } = require('cliodot');
 ```
 
-For password hashing (Argon2, bcrypt):
+Optional peer dependencies (install only what you use):
 
 ```bash
-npm install argon2 bcrypt
+npm install mongodb mysql2 pg ioredis argon2 bcrypt
 ```
 
-## Quick Start
+## Quick start
 
 ```javascript
 import { flosync, v } from 'cliodot';
@@ -72,1619 +50,40 @@ flosync.register(w);
 const result = await flosync.run('create-order', { body: { item: 'Widget', qty: 2 } });
 ```
 
-### Run Payload
-
-Pass a `body` (or plain object) as the trigger; the engine treats it as `trigger.body` and `trigger.data`. You can also pass:
-
-| Field | Description |
-|-------|-------------|
-| `body` / `data` | Request body; use `v.body('account')`, `v.body('email')` |
-| `headers` | Simulated HTTP headers for the run (`v.header('x-api-key')`); merged with `executionHeaders` (see below) |
-| `executionHeaders` | Extra headers merged after `headers` (same sanitization); useful to separate trigger data from auth headers |
-| `pathParams` | Route params (`v.pathParam('id')`) |
-| `params` | Extra params (`v.param('page')`) |
-| `query` | Query string params (`v.query('filter')`) |
-| `vars` | Override workflow vars (`v.vars('apiKey')`) |
-| `envVars` / `env` | Environment overrides (`v.env('MONGO_URI')`) |
-
-```javascript
-flosync.run('my-workflow', { body: { id: 1 } });
-flosync.run('my-workflow', { body: { id: 1 }, headers: { 'x-request-id': 'abc' }, pathParams: { id: '123' }, query: { page: 1 } });
-```
-
-### Execution headers (local and remote)
-
-Workflow steps read `state.headers` (for example `v.header('authorization')`). You control what appears there via the run payload and, for remote runs, the client options below.
-
-Local runs (`flosync.run` with a registered workflow): `headers` and `executionHeaders` on the payload are merged (after sanitization) into `state.headers`. You can also pass `executionHeaders` as the third argument to `flosync.run`, which merges on top of the payload.
-
-```javascript
-await flosync.run('my-workflow', { body: { id: 1 }, headers: { 'x-request-id': 'a' } }, {
-  executionHeaders: { authorization: `Bearer ${integrationToken}` },
-});
-```
-
-Remote runs (`flosync.run` / `flosync.runById` with `apiKey` and `apiSecret`, or `FlosyncClient`): the SDK sends its own `Authorization` header to the Cliodot API (session JWT). That value is not copied into the workflow `state.headers`, since it is not the same credential your integration steps expect.
-
-To give the server workflow the bearer or other headers it was designed for, pass them explicitly:
-
-- In the payload: `headers` or `executionHeaders` on the object you pass to `run` / `runById` (both are merged into the test payload the API receives).
-- On the client: `client.workflows.run(groupId, triggerId, { payload, executionHeaders })` — `executionHeaders` is sent in the JSON body and merged last on the server.
-- Webhook test: `client.workflows.runByWebhook(path, method, { body, executionHeaders })`.
-
-Merge order on the server is: sanitized real incoming HTTP headers (transport), then `payload.headers`, then `executionHeaders` from the body. Later keys win. Cookies, hop-by-hop headers, `sec-*`, `proxy-*`, and `proxy-authorization` are dropped from user-supplied maps. `authorization` is allowed in `headers` / `executionHeaders` so you can supply an integration bearer; it is still stripped from the raw request line so the Cliodot session token does not overwrite your value.
-
-`sanitizeExecutionHeaders` is exported if you want to preview what will be sent; the same rules apply on the server.
-
-Public webhooks (unauthenticated URL): the server does not apply an `executionHeaders` field from the JSON body for merging. Use normal request headers or put values in the webhook payload and map them in the workflow.
-
 ## Configuration
 
 ```javascript
 flosync.configure({
   apiKey: process.env.FLOSYNC_API_KEY,
   apiSecret: process.env.FLOSYNC_API_SECRET,
-  baseUrl: 'http://localhost:8080' //optional,
+  baseUrl: process.env.CLIODOT_BASE_URL,
   projectId: process.env.FLOSYNC_PROJECT_ID,
-  debug: false, // Enable to include stepResults in every response
   connectors: {
     'mongodb.system': { uri: process.env.MONGO_URI, database: 'myapp' },
-    'mysql.system': { uri: process.env.MYSQL_URI },
-    'postgres.system': { uri: process.env.PG_URI, database: 'myapp' },
-    'redis.system': { url: process.env.REDIS_URL },
-    'cliodot': { apiKey: process.env.CLIODOT_API_KEY },
-  },
-  cliodot: { baseUrl: 'https://api.example.com', apiKey: process.env.CLIODOT_API_KEY },
-});
-```
-
-`baseUrl` defaults to `http://localhost:8080` when omitted. For remote runs (workflows, functions, connectors), only `apiKey` and `apiSecret` are required. Set `CLIODOT_BASE_URL` (or `baseUrl`) to match your main Cliodot API server port.
-
-## Workflows
-
-### Triggers (optional)
-
-Triggers are optional. If you wrap workflows in your own HTTP handler, omit `.http()` and call `flosync.run()` with your payload.
-
-| Method | Description |
-|--------|-------------|
-| `.http(method, path)` | HTTP trigger (e.g. `POST /orders`) |
-| `.job(cron?, timezone?)` | Job/cron trigger (e.g. `'0 * * * *'`, `'UTC'`) |
-| `.schedule(cron, timezone?)` | Alias for scheduled jobs |
-| `.webhook(method, path)` | Alias for `.http()` |
-
-```javascript
-flosync.workflow('api-order').http('POST', '/orders').step(...).build();
-flosync.workflow('daily-job').job('0 0 * * *', 'UTC').step(...).build();
-flosync.workflow('manual').step(...).build();
-```
-
-### Variable references
-
-Use `variable` (or `v`) instead of typing `{{ }}`:
-
-| Method | Example | Resolves to |
-|--------|---------|-------------|
-| `v.body(...path)` | `v.body('amount')`, `v.body('user', 'email')` | `{{ body.amount }}`, `{{ body.user.email }}` |
-| `v.trigger(...path)` | `v.trigger('email')` | `{{ trigger.email }}` |
-| `v.stepResult(stepId, ...path)` | `v.stepResult('charge', 'id')` | `{{ stepResults.charge.id }}` |
-| `v.header(key)` | `v.header('x-api-key')` | `{{ headers["x-api-key"] }}` |
-| `v.param(key)` | `v.param('page')` | `{{ params["page"] }}` |
-| `v.pathParam(key)` | `v.pathParam('id')` | `{{ pathParams["id"] }}` |
-| `v.query(key)` | `v.query('filter')` | `{{ query["filter"] }}` |
-| `v.vars(key)` | `v.vars('apiKey')` | `{{ vars["apiKey"] }}` |
-| `v.env(key)` | `v.env('MONGO_URI')` | `{{ env["MONGO_URI"] }}` |
-| `v.args(...path)` | `v.args('amount')` | `{{ args.amount }}` |
-| `v.expr(expression)` | `v.expr('length(body.items) * 10')` | `{{ length(body.items) * 10 }}` |
-
-```javascript
-import { flosync, v } from 'cliodot';
-
-s.validator({ amount: v.body('amount'), email: v.body('email') });
-s.transform({ total: v.stepResult('calculate', 'total'), id: v.stepResult('charge', 'id') });
-```
-
-### Typed `stepResult` paths (`defineStepVars`)
-
-`v.stepResult(stepId, ...pathParts)` treats every segment as a plain `string`, so your editor cannot suggest valid fields from a connector response or from another step’s output.
-
-Use **`defineStepVars`** to describe, once per workflow file, a map from **step id** (the decorated **method name**) to that step’s **result type**. The returned **`stepResult`** then constrains the first argument to those keys and each following argument to the next key along a valid path into that type (nested objects supported up to a fixed depth). Import **`ConnectorResponse`** (and your **`defineTypedConnector`** value) so connector steps reuse the same response shape you already declared for typing.
-
-```typescript
-import { defineStepVars, v, defineTypedConnector } from "cliodot";
-import type { ConnectorResponse } from "cliodot";
-
-const Api = defineTypedConnector("my-api", { pay: "pay" }, {
-  pay: {
-    body: {} as { amount: number },
-    response: { status: "", data: { id: "", link: "" } },
-  },
-});
-
-const steps = defineStepVars<{
-  pay: ConnectorResponse<typeof Api, "pay">;
-  validate: { errors?: Record<string, unknown> };
-}>();
-
-steps.stepResult("pay", "data", "link");
-steps.stepResult("validate", "errors");
-```
-
-The type **`StepKeyPath<T>`** is exported if you want to reuse the path-tuple logic elsewhere. Plain **`v.stepResult`** remains available for ad hoc strings and for code that does not need completions.
-
-### Class decorators (`buildWorkflowFromClass`)
-
-For `@Connector`, you can target a connector that exists only on Flowsync in three ways: pass the published connector id and action as strings (`@Connector('my-connector', 'charge', { installation_id: '...', connector_version: '1.2.0' })`); use `defineCustomConnector` / `defineCustomConnectorFromList` with that same id; or use `defineRemoteConnectorRef('my-connector', { pay: 'charge' })` and `@Connector(MyRef, 'pay', config)` for a clearer name. With `apiKey` and `apiSecret` set, the local runner loads REST definitions through `client.connectors.get` and respects `connector_version` on the step when fetching.
-
-**`@CallWorkflow` by webhook path** — Use `@CallWorkflow({ webhookPath: '/orders', webhookMethod: 'POST' }, payload)` where `webhookPath` and `webhookMethod` match the child workflow’s HTTP trigger (same values as `@Http('POST', '/orders')` on that workflow). You do **not** pass a workflow group id for this mode: the platform finds the child by path and method for the tenant. When the local runner calls Flowsync with `apiKey` / `apiSecret`, it uses **`POST /workflows/test/webhook`** with a JSON body `{ webhookPath, webhookMethod, payload, ... }` (`client.workflows.runByWebhook`). On the server, `call_workflow` resolves the child the same way as a real webhook (including route patterns) and merges path params into the child’s `pathParams`. The second decorator argument is the child payload; optional fields on that object include `environment` (`dev` / `prod`), `executionHeaders`, and `remote: true` to skip the in-memory registry and always hit the API. `webhookPath` / `webhookMethod` may be templated with `{{ }}` and are rendered before lookup.
-
-**`@CallWorkflow` by group id** — `@CallWorkflow('my-group-id', payload)` runs the child via **`POST /workflows/:groupId/test/trigger/:triggerId`** (see `client.workflows.run`). Use this when you target a specific group and trigger explicitly. You can combine `workflow_id` with a webhook path in the serialized step only when you need both; the path-only flow above stays independent of group ids.
-
-### Step Types
-
-- `connector(id, action, config)` - REST/API call (optional `connector_version` in `config` for versioned tenant connectors when syncing workflows to Flowsync)
-- `db(engine, action, config)` - MongoDB, MySQL, PostgreSQL, or Redis (optional `connector_version` when relevant)
-- `validator(fields)` - Validate input
-- `condition(expr)` - Branch on expression (use `.then()` and `.else()`)
-- `transform(mapping)` - Map or transform data
-- `call(slug, args)` - Invoke a function
-- `auth(connectorId, action, config)` - Authentication
-- `util(connectorId, action, config)` - Utility (see [Utilities](#utilities))
-- `encrypt(connectorId, action, config)` - Encryption (see [Encryption](#encryption))
-- `responder(type, config)` - Return response (json, http, raw, redirect, empty)
-- `log(message)` - Log message
-- `delay(ms)` - Delay execution
-
-### Branching
-
-Steps that can succeed or fail support `.then()` and `.else()`:
-
-```javascript
-.step('validate', s => s.validator({ amount: '{{ trigger.body.amount }}' })
-  .then('process')
-  .else('error'))
-.step('check', s => s.condition('{{ stepResults.validate.amount > 0 }}')
-  .then('create')
-  .else('invalid'))
-```
-
-### Decorator Workflows
-
-You can define workflows using TypeScript decorators instead of the fluent `.workflow().step()` builder.
-
-1. Enable decorators in your consuming project's `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true
-  }
-}
-```
-
-2. Define a workflow class and decorate it with `@Workflow()` and `@Http()` (or `@Job()` / `@Schedule()`).
-
-3. Decorate class methods to create steps. By default, the step ID is the method name.
-
-4. Build and register the workflow with `buildWorkflowFromClass()` or `flosync.registerFromClass()`.
-
-5. Optional: add JavaScript inside the decorated method body.
-
-If a decorated method contains non-empty code, the SDK uses it based on the step decorator option `stage`:
-
-- `stage: "pre"` (default): injects an extra `code` step right before the decorated step. The injected code receives `ctx` with:
-
-- `ctx.input` (previous step output, or trigger data for the first step)
-- `ctx.trigger` (trigger payload)
-- `ctx.steps` (all previous `stepResults`)
-- `ctx.vars` (workflow vars, including anything set via `setVars`)
-
-To pass values to later steps, return an object with `setVars`:
-
-```typescript
-return { setVars: { limit: 10 } };
-```
-
-Later templates can read them via `v.vars("limit")` (resolves to `{{ vars["limit"] }}`) or `{{ vars.limit }}`.
-
-- `stage: "post"`: executes the method body after the decorated step finishes, and allows overriding the decorated step output directly.
-
-In this mode, return:
-
-```typescript
-return { out: <newOutput>, setVars?: { ... } };
-```
-
-The overridden output becomes the value of `v.stepResult("<stepId>")` for subsequent steps.
-
-In `stage: "post"`, `ctx.input` is the decorated step output produced by the connector/function call.
-
-#### `stage: "post"` in depth
-
-`post` is the hook that runs **after** the decorated step’s primary work finishes. For `@Connector`, `@Db`, and other steps that call out to a runtime implementation, the sequence is: resolve inputs → run the connector or database action (or built-in executor) → take the returned payload as the step output → **then** run your method body with `ctx.input` set to that output. Anything you return as `{ out }` replaces what gets stored in `stepResults` for that step id, so the rest of the workflow sees your transformed value. Use `setVars` in the same return value to publish workflow variables without changing the step output. Failures and HTTP error handling still apply to the primary step; the post hook is for normalization (mapping provider DTOs to your domain shape), redacting fields, enriching derived properties, or turning awkward API responses into a stable contract for later steps and responders. `@Step` defaults to `stage: "post"` so standalone code steps behave like “compute output from prior context” without injecting an extra predecessor code step.
-
-### `WorkflowContext<TInput, TSteps, TVars>`
-
-Instead of using `ctx: any`, you can type the context object passed to step methods. Import `WorkflowContext` from `cliodot`:
-
-```typescript
-import type { WorkflowContext } from "cliodot";
-```
-
-`WorkflowContext` is generic with three optional type parameters:
-
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `TInput` | `Record<string, any>` | Shape of `ctx.input` (previous step output or trigger data) |
-| `TSteps` | `Record<string, any>` | Shape of `ctx.steps` (accumulated step results) |
-| `TVars` | `Record<string, any>` | Shape of `ctx.vars` (workflow-level variables) |
-
-The full context object includes:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `input` | `TInput` | Input data for this step |
-| `trigger` | `any` | Raw trigger payload |
-| `steps` | `TSteps` | All step results keyed by step ID |
-| `vars` | `TVars` | Workflow variables (read/write via `setVars`) |
-| `headers` | `Record<string, string>` | HTTP headers from the request |
-| `params` | `Record<string, any>` | Merged query + route params |
-| `pathParams` | `Record<string, any>` | URL path parameters |
-| `query` | `Record<string, any>` | Query string parameters |
-| `body` | `any` | Raw request body |
-| `env` | `Record<string, string>` | Environment variables |
-
-The interface also has an index signature (`[key: string]: any`) so users can attach custom properties.
-
-### `StepOutput<T>`
-
-The return type for step methods that produce output. Import from `cliodot`:
-
-```typescript
-import type { StepOutput } from "cliodot";
-```
-
-```typescript
-export interface StepOutput<T = any> {
-  /** The output payload — stored in stepResults[stepId] */
-  out: T;
-  /** Optional: update workflow variables */
-  setVars?: Record<string, any>;
-}
-```
-
-Usage:
-
-```typescript
-@Connector(MyStore.id, MyStore.actions.list, {}, { order: 0, stage: "post" })
-list(ctx: WorkflowContext<{ items: Item[] }>): StepOutput<{ sorted: Item[] }> {
-  const sorted = [...ctx.input.items].sort((a, b) => a.id - b.id);
-  return { out: { sorted } };
-}
-```
-
-> **Note:** `StepOutput` is different from the `StepResult` exported by `WorkflowBuilder` (which is the builder-pattern return type with `.then()` / `.else()` chaining). Use `StepOutput` for decorator workflow method return types.
-
-### `@Step` — Custom Step Decorator
-
-`@Step` is a generic decorator for writing custom workflow step logic without needing to pair it with a connector, database, or other built-in step type. The method body is extracted at build time and executed as a code step with access to the full `WorkflowContext`.
-
-```typescript
-import { Workflow, Http, Step, Responder, buildWorkflowFromClass, v } from "cliodot";
-import type { WorkflowContext, StepOutput } from "cliodot";
-```
-
-**Options** (same as other step decorators):
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `id` | `string` | method name | Custom step ID |
-| `order` | `number` | auto | Execution order |
-| `stage` | `"pre" \| "post"` | `"post"` | When the method body runs |
-| `then` | `string` | — | Step ID to jump to on success |
-| `else` | `string` | — | Step ID to jump to on failure |
-
-**Basic example:**
-
-```typescript
-@Workflow("greet-user", "Greet User")
-@Http("POST", "/greet")
-class GreetWorkflow {
-  @Step({ order: 0 })
-  greet(ctx: WorkflowContext<{ name: string }>): StepOutput<{ greeting: string }> {
-    const name = ctx.input.name || "World";
-    return { out: { greeting: `Hello, ${name}!` } };
-  }
-
-  @Responder("json", { body: { message: v.stepResult("greet", "greeting") } }, { order: 1 })
-  respond() {}
-}
-
-export const greetWorkflow = buildWorkflowFromClass(GreetWorkflow);
-```
-
-**With `setVars` and branching:**
-
-```typescript
-@Workflow("process-order", "Process Order")
-@Http("POST", "/orders/process")
-class ProcessOrderWorkflow {
-  @Step({ order: 0, then: "finalize", else: "reject" })
-  validate(ctx: WorkflowContext<{ amount: number; currency: string }>): StepOutput<{ valid: boolean }> {
-    const { amount, currency } = ctx.input;
-    const valid = amount > 0 && ["USD", "EUR", "GBP"].includes(currency);
-    return {
-      out: { valid },
-      setVars: { processedAt: new Date().toISOString() },
-    };
-  }
-
-  @Responder("json", { body: { ok: true, processedAt: v.vars("processedAt") } }, { order: 1 })
-  finalize() {}
-
-  @Responder("json", { statusCode: 400, body: { ok: false, error: "Invalid order" } }, { order: 2 })
-  reject() {}
-}
-```
-
-**Combining `@Step` with other decorators:**
-
-`@Step` can be freely combined with `@Connector`, `@Db`, `@Condition`, `@Responder`, etc. in the same workflow class:
-
-```typescript
-@Workflow("mixed-workflow", "Mixed Workflow")
-@Http("POST", "/mixed")
-class MixedWorkflow {
-  @Step({ order: 0 })
-  prepare(ctx: WorkflowContext<{ email: string }>): StepOutput<{ normalized: string }> {
-    return { out: { normalized: ctx.input.email.toLowerCase().trim() } };
-  }
-
-  @Db("mongodb", "findOne", { collection: "users", query: { email: v.stepResult("prepare", "normalized") } }, { order: 1 })
-  findUser() {}
-
-  @Condition(v.expr("stepResults.findUser != null"), { then: "found", else: "notFound", order: 2 })
-  check() {}
-
-  @Responder("json", { body: { user: v.stepResult("findUser") } }, { order: 3 })
-  found() {}
-
-  @Responder("json", { statusCode: 404, body: { error: "User not found" } }, { order: 4 })
-  notFound() {}
-}
-```
-
-### Decorator example: list todos with typed context
-
-```typescript
-import { flosync, v, Workflow, Http, Connector, Condition, Responder, buildWorkflowFromClass, defineCustomConnector } from "cliodot";
-import type { WorkflowContext, StepOutput } from "cliodot";
-
-const CarrierStore = defineCustomConnector("carrier.store", {
-  listTodos: "listTodos",
-});
-
-interface TodoItem {
-  title?: string;
-  completed?: boolean;
-  createdAt?: string;
-  [key: string]: any;
-}
-
-interface ListInput {
-  todos?: TodoItem[];
-  [key: string]: any;
-}
-
-interface ListOutput {
-  todos: Array<TodoItem & { title_upper: string; completed_label: string }>;
-  completedTodos: TodoItem[];
-  pendingTodos: TodoItem[];
-  stats: { total: number; completed: number; pending: number };
-}
-
-@Workflow("todos-list-decorators", "Todos List (Decorators)")
-@Http("GET", "/todos")
-class TodosListDecoratorsWorkflow {
-  @Connector(
-    CarrierStore.id,
-    CarrierStore.actions.listTodos,
-    { params: { limit: 10 } },
-    { order: 0, stage: "post" }
-  )
-  list(ctx: WorkflowContext<ListInput>): StepOutput<ListOutput> {
-    const input = ctx?.input ?? {};
-    const todos = Array.isArray(input.todos) ? input.todos : [];
-    const sorted = [...todos].sort((a, b) =>
-      new Date(b?.createdAt ?? 0).getTime() - new Date(a?.createdAt ?? 0).getTime()
-    );
-    const completedTodos = sorted.filter((t) => Boolean(t?.completed));
-    const pendingTodos = sorted.filter((t) => !Boolean(t?.completed));
-
-    const decoratedTodos = sorted.map((t) => {
-      const title = String(t?.title ?? "").trim();
-      return {
-        ...t,
-        title,
-        title_upper: title.toUpperCase(),
-        completed_label: t?.completed ? "done" as const : "todo" as const,
-      };
-    });
-
-    return {
-      out: {
-        ...input,
-        todos: decoratedTodos,
-        completedTodos,
-        pendingTodos,
-        stats: {
-          total: sorted.length,
-          completed: completedTodos.length,
-          pending: pendingTodos.length,
-        },
-      },
-    };
-  }
-
-  @Condition(v.stepResult("list", "valid"), { then: "ok", else: "unauth", order: 1 })
-  check() {}
-
-  @Responder("json", { body: { todos: v.stepResult("list", "todos") } }, { order: 2 })
-  ok() {}
-
-  @Responder("json", { statusCode: 401, body: { error: "Unauthorized" } }, { order: 3 })
-  unauth() {}
-}
-
-const workflow = buildWorkflowFromClass(TodosListDecoratorsWorkflow);
-flosync.register(workflow);
-```
-
-If you prefer direct registration:
-
-```typescript
-flosync.registerFromClass(TodosListDecoratorsWorkflow);
-```
-
-### Decorator workflow: validation, MongoDB, string utilities, shaped JSON
-
-This pattern matches what many APIs do: validate input, derive a slug with `utility.string`, write to MongoDB, return a single JSON object with nested `note` metadata (not a flat dump of raw step outputs).
-
-Configure the database once:
-
-```javascript
-flosync.configure({
-  connectors: {
-    "mongodb.system": { uri: process.env.MONGO_URI, database: "myapp" },
   },
 });
 ```
 
-Workflow (imports: `flosync`, `v`, `Workflow`, `Http`, `Validator`, `Util`, `Db`, `Responder`, `buildWorkflowFromClass`, `ConnectorId`):
-
-```typescript
-import {
-  flosync,
-  v,
-  Workflow,
-  Http,
-  Validator,
-  Util,
-  Db,
-  Responder,
-  buildWorkflowFromClass,
-  ConnectorId,
-} from "cliodot";
-
-@Workflow("notes-create-decorators", "Notes create (decorators)")
-@Http("POST", "/decorators/notes")
-class NotesCreateDecoratorsWorkflow {
-  @Validator(
-    { title: v.body("title"), body: v.body("body") },
-    { order: 0, then: "slugify", else: "validationError" }
-  )
-  validate() {}
-
-  @Util(
-    ConnectorId.Utility.String,
-    "slugify",
-    { string: v.body("title") },
-    { order: 1 }
-  )
-  slugify() {}
-
-  @Db(
-    "mongodb",
-    "insertOne",
-    {
-      collection: "notes",
-      document: {
-        title: v.body("title"),
-        body: v.body("body"),
-        slug: v.stepResult("slugify", "value"),
-      },
-    },
-    { order: 2 }
-  )
-  persist() {}
-
-  @Responder(
-    "json",
-    {
-      statusCode: 201,
-      body: {
-        ok: true,
-        note: {
-          id: v.stepResult("persist", "insertedId"),
-          title: v.body("title"),
-          slug: v.stepResult("slugify", "value"),
-          body: v.body("body"),
-        },
-      },
-    },
-    { order: 3 }
-  )
-  created() {}
-
-  @Responder(
-    "json",
-    {
-      statusCode: 400,
-      body: {
-        ok: false,
-        error: "validation_failed",
-        details: v.stepResult("validate", "errors"),
-      },
-    },
-    { order: 4 }
-  )
-  validationError() {}
-}
-
-const notesDecoratorsWorkflow = buildWorkflowFromClass(NotesCreateDecoratorsWorkflow);
-flosync.register(notesDecoratorsWorkflow);
-```
-
-Example request:
-
-```http
-POST /decorators/notes
-Content-Type: application/json
-
-{
-  "title": "Ship checklist",
-  "body": "Pack boxes, print labels, hand off to carrier."
-}
-```
-
-Example success response body:
-
-```json
-{
-  "ok": true,
-  "note": {
-    "id": "65a1b2c3d4e5f6789012345",
-    "title": "Ship checklist",
-    "slug": "ship-checklist",
-    "body": "Pack boxes, print labels, hand off to carrier."
-  }
-}
-```
-
-Example validation failure response body:
-
-```json
-{
-  "ok": false,
-  "error": "validation_failed",
-  "details": {
-    "title": "Field is required"
-  }
-}
-```
-
-`@Util` is typed the same way as `s.util(ConnectorId.Utility.String, "slugify", { ... })` in the fluent builder. `@Db` supports the `mongodb` and `mysql` engines (see [Database](#database)). Step IDs in `v.stepResult("slugify", "value")` refer to the **method name** you put on each decorated step (after sanitization, dots and hyphens in custom IDs become underscores).
-
-### Decorator Connectors
-
-For ultimate flexibility, you can define your own **Connectors** using class-based decorators instead of using the generic `defineCustomConnector` pattern. 
-
-Use the `@ConnectorClass` decorator and map endpoints instantly without rewriting HTTP loops or complex REST logic!
-
-```typescript
-import { ConnectorClass, ActionEndpoint, ActionCustom, buildConnectorFromClass, flosync } from "cliodot";
-
-// You can pass configuration mimicking flosync REST definition payloads directly into the class decorator:
-@ConnectorClass("paystack", "Paystack Integrations", {
-  type: "REST",
-  base_url: "https://api.paystack.co",
-  auth: { type: "bearer", token: process.env.PAYSTACK_SECRET_KEY }
-})
-export class Paystack {
-  
-  // Handled entirely by Flosync's underlying REST connector automatically!
-  @ActionEndpoint("initializeTransaction", "POST", "/transaction/initialize", {
-     headers: { "Content-Type": "application/json" }
-  })
-  initializeTransaction() {}
-
-  // Paths parameter resolution happens completely implicitly via the REST connector.
-  @ActionEndpoint("verifyTransaction", "GET", "/transaction/verify/:reference")
-  verifyTransaction() {}
-  
-  // Or, run a completely custom code execution if you need SDKs or Database integrations
-  @ActionCustom("generateSignature")
-  async generateSignature(payload: any) {
-     const crypto = require("crypto");
-     return { signature: crypto.createHmac('sha512', process.env.SECRET).update(payload.body.data).digest('hex') };
-  }
-}
-
-// Convert class into standard flosync connector schema
-export const paystackConfig = buildConnectorFromClass(Paystack);
-
-export const PaystackConnector = {
-  id: PaystackImplementation.id,
-  actions: PaystackImplementation.actions
-};
-
-// Register it natively just like any built-in module
-flosync.registerConnector(paystackConfig.id, paystackConfig);
-```
-
-#### Authentication Options
-
-Flosync supports built-in, natively executed REST authentication blocks inside the `@ConnectorClass` config object. You do not need to write boilerplate header injection code!
-
-1. **Bearer Token (*Default*)**
-   ```typescript
-   auth: { type: "bearer", token: "your-token", header_name: "Authorization", prefix: "Bearer " }
-   ```
-2. **API Key**
-   ```typescript
-   auth: { type: "api_key", api_key: "your-api-key", key_name: "x-api-key" }
-   ```
-3. **No Auth**
-   ```typescript
-   auth: { type: "none" }
-   ```
-
-Then hook it right into your workflows! This example uses `@Validator` for type-safe input checking, generates a unique payment reference using the built-in `utility.random` connector, and passes it to the Paystack API:
-
-```typescript
-import { Workflow, Http, Connector, Responder, Validator, v } from "cliodot";
-
-@Workflow("payment-initialize", "Initialize Payment")
-@Http("POST", "/payment/initialize")
-export class PaymentInitializeWorkflow {
-
-  @Validator([
-    {
-      fields: [v.body("email")],
-      validators: [{ name: "required" }, { name: "is_email" }]
-    },
-    {
-      fields: [v.body("amount")],
-      validators: [{ name: "required" }]
-    }
-  ], { order: 0, then: "generateReference", else: "invalid" })
-  validate() {}
-
-  @Responder("json", { 
-    statusCode: 400,
-    body: { 
-      ok: false,
-      message: "Validation failed", 
-      errors: v.stepResult("validate", "errors") 
-    } 
-  }, { order: 1 })
-  invalid() {}
-
-  @Connector("utility.random", "random_uuid", {}, { order: 2 })
-  generateReference() {}
-
-  @Connector(
-    PaystackConnector.id, 
-    PaystackConnector.actions.initializeTransaction, 
-    { 
-      body: { 
-        email: v.body("email"), 
-        amount: v.body("amount"),
-        reference: v.stepResult("generateReference", "value"),
-      } 
-    },
-    { order: 3 }
-  )
-  initialize() {}
-
-  @Responder("json", { body: { message: "Payment initialized successfully", data: v.stepResult("initialize") } }, { order: 4 })
-  respond() {}
-}
-```
-
-### Custom `execute` connector plus decorators (catalog sample)
-
-For behavior that is not a REST template (in-memory demo data, your own SDK, legacy SOAP adapter, etc.), register a connector with an `execute` function, then call it from decorators with `@Connector` exactly like a built-in connector. This mirrors the `carrier.store` pattern: actions such as `listProducts` and `createProduct`, `options.body` / `options.params` / `options.pathParams` passed from the step config.
-
-Define typed action names and the connector:
-
-```typescript
-import { flosync, defineCustomConnector } from "cliodot";
-
-type CatalogProduct = { id: string; name: string; price: number };
-
-const Catalog = defineCustomConnector("acme.catalog", {
-  listProducts: "listProducts",
-  createProduct: "createProduct",
-});
-
-const catalogProducts: CatalogProduct[] = [
-  { id: "p_static_1", name: "Starter", price: 0 },
-  { id: "p_static_2", name: "Pro", price: 49 },
-];
-
-flosync.registerConnector(Catalog.id, {
-  _id: Catalog.id,
-  type: "system",
-  name: "Acme Catalog",
-  meta: { category: "catalog" },
-  auth: { type: "none" },
-  execute: async (action, options) => {
-    const body = (options.body ?? {}) as Record<string, unknown>;
-    const params = (options.params ?? {}) as Record<string, unknown>;
-    const pathParams = (options.pathParams ?? {}) as Record<string, unknown>;
-    const merged = { ...params, ...pathParams };
-
-    if (action === Catalog.actions.listProducts) {
-      const limitRaw = merged.limit;
-      const limit =
-        limitRaw === undefined || limitRaw === ""
-          ? catalogProducts.length
-          : Math.max(0, Number(limitRaw));
-      const slice = catalogProducts.slice(0, Number.isFinite(limit) ? limit : catalogProducts.length);
-      return { ok: true, products: slice, count: slice.length };
-    }
-
-    if (action === Catalog.actions.createProduct) {
-      const name = String(body.name ?? "").trim();
-      const price = Number(body.price);
-      if (!name || Number.isNaN(price)) {
-        return { ok: false, error: "name_and_price_required" };
-      }
-      const id = `p_${Date.now()}`;
-      const product: CatalogProduct = { id, name, price };
-      catalogProducts.push(product);
-      return { ok: true, product };
-    }
-
-    return { ok: false, error: "unknown_action" };
-  },
-});
-```
-
-List products with decorator `stage: "post"` to shape the payload (add `price_display`, clamp list) before the responder runs:
-
-```typescript
-import {
-  flosync,
-  v,
-  Workflow,
-  Http,
-  Connector,
-  Responder,
-  buildWorkflowFromClass,
-} from "cliodot";
-
-@Workflow("acme-catalog-list-decorators", "Catalog list (decorators)")
-@Http("GET", "/decorators/catalog/products")
-class CatalogListDecoratorsWorkflow {
-  @Connector(
-    Catalog.id,
-    Catalog.actions.listProducts,
-    { params: { limit: v.query("limit") } },
-    { order: 0, stage: "post" }
-  )
-  list(ctx: WorkflowContext<{ products?: CatalogProduct[]; [k: string]: any }>): StepOutput<{ products: any[]; count: number }> {
-    const input = ctx?.input ?? {};
-    const items = Array.isArray(input.products) ? input.products : [];
-    const withLabels = items.map((p) => ({
-      ...p,
-      price_display: `$${Number(p.price).toFixed(2)}`,
-    }));
-    return { out: { ...input, products: withLabels, count: withLabels.length } };
-  }
+For remote runs against your Cliodot account, set `apiKey` and `apiSecret`. `baseUrl` defaults to `http://localhost:8080` when omitted.
 
-  @Responder(
-    "json",
-    {
-      body: {
-        ok: true,
-        count: v.stepResult("list", "count"),
-        products: v.stepResult("list", "products"),
-      },
-    },
-    { order: 1 }
-  )
-  respond() {}
-}
-```
-
-Create product with the same connector; the method body flags bad input and normalizes the successful response:
-
-```typescript
-@Workflow("acme-catalog-create-decorators", "Catalog create (decorators)")
-@Http("POST", "/decorators/catalog/products")
-class CatalogCreateDecoratorsWorkflow {
-  @Connector(
-    Catalog.id,
-    Catalog.actions.createProduct,
-    { body: { name: v.body("name"), price: v.body("price") } },
-    { order: 0, stage: "post" }
-  )
-  save(ctx: WorkflowContext<{ ok?: boolean; product?: CatalogProduct; [k: string]: any }>): StepOutput<any> {
-    const input = ctx?.input ?? {};
-    if (!input.ok) return { out: input };
-    const p = input.product as CatalogProduct;
-    return {
-      out: {
-        ...input,
-        product: { ...p, price_display: `$${Number(p.price).toFixed(2)}` },
-      },
-    };
-  }
-
-  @Responder(
-    "json",
-    {
-      statusCode: 201,
-      body: {
-        ok: true,
-        product: v.stepResult("save", "product"),
-      },
-    },
-    { order: 1 }
-  )
-  respond() {}
-}
-```
-
-Example `POST /decorators/catalog/products` JSON body:
-
-```json
-{
-  "name": "Enterprise",
-  "price": 199
-}
-```
-
-Example `201` response body:
-
-```json
-{
-  "ok": true,
-  "product": {
-    "id": "p_1711286400000",
-    "name": "Enterprise",
-    "price": 199,
-    "price_display": "$199.00"
-  }
-}
-```
-
-Example `GET /decorators/catalog/products?limit=1` response body:
-
-```json
-{
-  "ok": true,
-  "count": 1,
-  "products": [
-    { "id": "p_static_1", "name": "Starter", "price": 0, "price_display": "$0.00" }
-  ]
-}
-```
-
-Register both workflows with `buildWorkflowFromClass` / `flosync.register` or `flosync.registerFromClass`. Use `flosync.run("<workflow-id>", { body: { ... } })` with the `@Workflow` string ID (the engine also registers the same workflow under `__rawId` when you use kebab-case IDs).
-
-## Functions
-
-```javascript
-const validatePayment = flosync.function('validate-payment')
-  .input({ amount: 'number', currency: 'string' })
-  .step('validate', s => s.validator({ amount: '{{ args.amount }}', currency: '{{ args.currency }}' }))
-  .step('format', s => s.transform({ valid: '{{ stepResults.validate.valid }}', amount: '{{ args.amount }}' }))
-  .outputFrom('format')
-  .build();
-
-flosync.registerFunction(validatePayment);
-
-const result = await flosync.runFunction('validate-payment', { amount: 100, currency: 'USD' });
-```
-
-## Run by ID (remote)
-
-When configured with `apiKey`, `apiSecret`, and `baseUrl`, you can run workflows and functions by ID without registering them locally. They are assumed to exist on your account.
-
-```javascript
-flosync.configure({ apiKey, apiSecret });
-
-await flosync.run('workflow-id-from-account', { body: { amount: 100 } });
-await flosync.runById('workflow-id', { body: { ... } }, { triggerId: 'trigger' });
-await flosync.runByWebhook('/orders', 'POST', { body: { ... } });
-
-await flosync.runFunction('function-id-from-account', { amount: 100 });
-await flosync.runFunctionById('function-id', { amount: 100 });
-```
-
-If a workflow/function is registered locally, `run` / `runFunction` use the local version. If not found and the client is configured, they run remotely. Pass `{ remote: false }` to disable remote fallback.
-
-### Connector versioning (REST connectors)
-
-Tenant REST connectors can have **published semver snapshots**. The SDK and API use that version when loading connector definitions for workflow runs and for direct execute calls.
-
-**Workflow steps (fluent builder and `@Connector` config)**  
-Include an optional semver string on the step config so pushed workflows pin the same snapshot the runner expects:
-
-```typescript
-s.connector("paystack_conn_id", "initializeTransaction", {
-  connector_version: "1.2.0",
-  body: { email: v.body("email"), amount: v.body("amount") },
-});
-```
-
-Event triggers can pin the source connector the same way on the workflow object: `trigger.source_connector_id` and `trigger.source_connector_version` (see types in `IWorkflowTrigger`).
-
-**`flosync.runConnector` (remote)**  
-Pass `connector_version` in the options object. Non-owners must match their **installed** version; owners may use other published versions or `draft` per API rules.
-
-```typescript
-await flosync.runConnector(Paystack, "initializeTransaction", {
-  connector_version: "1.2.0",
-  body: { email: "a@b.com", amount: 100 },
-});
-```
-
-**`FlosyncClient`** (after `configure` with `apiKey` / `apiSecret`):
-
-- `client.connectors.get(connectorId, { semver: "1.2.0" })` or `{ version: "1.2.0" }` — same query params as the Flowsync GET connector API.
-- `client.connectors.install(connectorId, { auth, base_url, version: "latest" })` — `version` is optional (body or query on the server).
-- `client.connectors.execute(connectorId, action, { connector_version: "1.2.0", body, params, ... })` — sent as `connector_version` on the execute request body.
-
-Workflows built with `WorkflowBuilder` / decorators serialize `connector_version` onto nodes when you `workflows.push`, so pulls round-trip the field.
-
-## Database
-
-Use `s.db(engine, action, config)` or `s.connector(connectorId, action, config)` with built-in database connectors.
-
-| Connector | Engine | Actions |
-|-----------|--------|---------|
-| `mongodb.system` | mongodb | insertOne, insertMany, findOne, find, updateOne, deleteOne |
-| `mysql.system` | mysql | query |
-| `postgres.system` | postgres | query |
-| `redis.system` | redis | redis.get, redis.set, redis.delete, redis.hset, redis.hget, redis.lpush, redis.lpop, redis.zadd, redis.create_hash, redis.delete_key |
-
-```javascript
-s.db('mongodb', 'insertOne', { collection: 'orders', document: v.body() });
-s.db('mysql', 'query', { query: 'SELECT * FROM users WHERE id = ?', params: [v.body('id')] });
-s.db('postgres', 'query', { query: 'SELECT * FROM users', params: [] });
-s.db('redis', 'redis.set', { key: 'cache:user:1', value: v.stepResult('fetch'), ttl: 3600 });
-```
-
-Configure in `flosync.configure({ connectors: { 'postgres.system': { uri, database }, 'redis.system': { url } } })`.
-
-## Utilities
-
-Use `s.util(connectorId, action, config)` with built-in utility connectors. Use `ConnectorId.Utility` and `ConnectorActions` or `getConnectorActions(connectorId)` for autocomplete and suggestions.
-
-| Connector | Actions |
-|-----------|---------|
-| `utility.date_time` | get_current_date, get_current_time, get_current_datetime, format, format_date, parse_date, add_time, subtract_time, diff_between_dates, start_of_day, end_of_day, start_of_week, end_of_week, start_of_month, end_of_month, start_of_year, end_of_year, convert_timezone, get_timezone, list_timezones, is_leap_year, get_unix_timestamp, from_unix_timestamp |
-| `utility.string` | concat, split, join, replace, replace_all, trim, trim_start, trim_end, to_uppercase, to_lowercase, capitalize, substring, length, contains, starts_with, ends_with, remove_whitespace, slugify, pad_start, pad_end, reverse, encode_base64, decode_base64, encode_uri, decode_uri, after, after_last, before, before_last, between, between_first, camel, char_at, chop_start, chop_end, contains_all, doesnt_contain, doesnt_start_with, doesnt_end_with, deduplicate, excerpt, finish, start, headline, is, is_ascii, is_json, is_ulid, is_url, is_uuid, is_empty, is_match, kebab, snake, studly, title, lcfirst, ucfirst, ucwords, ucsplit, limit, mask, match, match_all, pad_both, plural, singular, position, random, remove, repeat, replace_array, replace_first, replace_last, replace_matches, replace_start, replace_end, squish, substr, substr_count, substr_replace, swap, take, word_count, word_wrap, words, wrap, unwrap, uuid, ulid, strip_tags, ascii, apa, class_basename |
-| `utility.math` | add, subtract, multiply, divide, modulo, power, round, floor, ceil, abs, min, max, average, sum, clamp, random_between, percentage, percentage_of, sqrt, log |
-| `utility.random` | random_int, random_float, random_string, random_uuid, uuid, random_boolean, random_choice, random_password, random_hex, random_alphanumeric, random_date, random_color, shuffle_array |
-| `utility.compare` | diff_objects, diff_arrays, compare_strings, compare_numbers, compare_dates, is_changed, is_equal, is_not_equal, is_greater_than, is_less_than, is_between, is_empty, is_null_or_undefined, is_same_type, deep_equal, shallow_equal, similarity_score, array_intersection, array_union, array_difference |
-| `utility.geo` | calculate_distance, point_in_polygon, get_bounding_box, reverse_geocode, geocode, convert_coordinates |
-
-```javascript
-import { ConnectorId, ConnectorActions, getConnectorActions } from 'cliodot';
-
-s.util(ConnectorId.Utility.String, 'slugify', { string: 'Hello World' });
-s.util(ConnectorId.Utility.Math, 'clamp', { number: 150, min: 0, max: 100 });
-s.util(ConnectorId.Utility.Compare, 'diff_objects', { object1: v.stepResult('prev'), object2: v.body() });
-s.util(ConnectorId.Utility.Geo, 'calculate_distance', { lat1: 0, lon1: 0, lat2: 1, lon2: 1 });
-
-const stringActions = getConnectorActions(ConnectorId.Utility.String);
-```
-
-## Responders
-
-Use `s.responder(type, config)` with built-in responder types.
-
-| Type | Description |
-|------|-------------|
-| json | JSON response (default content-type: application/json) |
-| http | Same as json, supports custom headers |
-| raw | Plain text with custom contentType |
-| redirect | 302/301 redirect with Location header |
-| empty | 202 with no body |
-
-```javascript
-s.responder('json', { body: v.stepResult('data') });
-s.responder('raw', { body: 'OK', contentType: 'text/plain' });
-s.responder('redirect', { location: 'https://example.com', statusCode: 301 });
-s.responder('empty', { statusCode: 202 });
-```
-
-## Validation
-
-The `@Validator` decorator provides type-safe input validation for workflow steps. Validators use a `ValidationRule` union type that gives you full IDE auto-completion for all available rules and their configuration options.
-
-### Basic usage
-
-```typescript
-import { Validator, v } from "cliodot";
-
-@Validator([
-  {
-    fields: [v.body("email")],
-    validators: [{ name: "required" }, { name: "is_email" }]
-  },
-  {
-    fields: [v.body("amount")],
-    validators: [{ name: "required" }, { name: "is_number" }]
-  }
-], { order: 0, then: "process", else: "error" })
-validate() {}
-```
-
-### Available validators
-
-| Validator | Config | Description |
-|-----------|--------|-------------|
-| `required` | `{ message? }` | Field must be present and non-null |
-| `not_empty` | `{ message? }` | Field must not be empty |
-| `is_empty` | `{ message? }` | Field must be empty |
-| `is_email` | `{ message? }` | Valid email format |
-| `is_number` | `{ message? }` | Must be a number |
-| `is_string` | `{ message? }` | Must be a string |
-| `is_boolean` | `{ message? }` | Must be a boolean |
-| `is_array` | `{ message? }` | Must be an array |
-| `is_object` | `{ message? }` | Must be an object |
-| `is_url` | `{ message? }` | Valid URL format |
-| `is_date` | `{ message? }` | Valid date format |
-| `is_uuid` | `{ message? }` | Valid UUID (v1-v5) |
-| `is_cuid` | `{ message? }` | Valid CUID |
-| `is_jwt` | `{ message? }` | Valid JWT structure (`header.payload.signature`) |
-| `is_json` | `{ message? }` | Valid parseable JSON string |
-| `is_alphanumeric` | `{ message? }` | Letters and numbers only |
-| `is_alpha` | `{ message? }` | Letters only |
-| `is_numeric_string` | `{ message? }` | Numeric digits only |
-| `is_hex_color` | `{ message? }` | Valid hex color (`#FFF` or `#123456`) |
-| `is_base64` | `{ message? }` | Valid base64 encoded string |
-| `is_credit_card` | `{ message? }` | Valid credit card (Luhn algorithm) |
-| `is_lowercase` | `{ message? }` | Must be all lowercase |
-| `is_uppercase` | `{ message? }` | Must be all uppercase |
-| `is_slug` | `{ message? }` | Valid URL slug (`my-cool-slug`) |
-| `is_mac_address` | `{ message? }` | Valid MAC address |
-| `is_port` | `{ message? }` | Valid TCP/UDP port (0-65535) |
-| `is_currency` | `{ message? }` | Valid currency format |
-| `is_latitude` | `{ message? }` | Valid latitude (-90 to 90) |
-| `is_longitude` | `{ message? }` | Valid longitude (-180 to 180) |
-| `is_strong_password` | `{ minLength?, minLowercase?, minUppercase?, minNumbers?, minSymbols?, message? }` | Configurable password strength |
-| `is_ip` | `{ version?: 4 \| 6, message? }` | Valid IPv4 or IPv6 address |
-| `is_phone` | `{ pattern?, message? }` | Phone number format |
-| `is_address` | `{ minLength?, maxLength?, message? }` | Address string checks |
-| `contains` / `not_contains` | `{ search, caseSensitive?, message? }` | String contains/excludes a value |
-| `begins_with` | `{ prefix, caseSensitive?, message? }` | String starts with prefix |
-| `ends_with` | `{ suffix, caseSensitive?, message? }` | String ends with suffix |
-| `is_in` / `not_in` | `{ values: any[], caseSensitive?, message? }` | Value is/isn't in a list |
-| `length` | `{ min?, max?, exact?, message? }` | String/array length bounds |
-| `range` | `{ min?, max?, message? }` | Numeric range bounds |
-| `matches` | `{ pattern, flags?, message? }` | Regex pattern match |
-| `equals` / `not_equals` | `{ value, message? }` | Strict equality check |
-| `greater_than` / `less_than` | `{ value: number, message? }` | Numeric comparison |
-| `greater_than_or_equal` / `less_than_or_equal` | `{ value: number, message? }` | Inclusive numeric comparison |
-
-### Configurable validators
-
-Some validators accept rich configuration objects with IDE autocomplete:
-
-```typescript
-// Strong password with custom constraints
-@Validator([
-  {
-    fields: [v.body("password")],
-    validators: [{
-      name: "is_strong_password",
-      config: { minLength: 12, minUppercase: 2, minSymbols: 1 }
-    }]
-  }
-], { order: 0, then: "register", else: "invalid" })
-validatePassword() {}
-
-// IP address with version lock
-@Validator([
-  {
-    fields: [v.body("server_ip")],
-    validators: [{ name: "is_ip", config: { version: 4 } }]
-  }
-], { order: 0, then: "connect", else: "invalid" })
-validateIP() {}
-
-// Range + custom message
-@Validator([
-  {
-    fields: [v.body("age")],
-    validators: [{
-      name: "range",
-      config: { min: 18, max: 120, message: "Age must be between 18 and 120" }
-    }]
-  }
-], { order: 0, then: "proceed", else: "invalid" })
-validateAge() {}
-```
-
-### Validation branching
-
-Use `then` and `else` to route the workflow based on validation results:
-
-```typescript
-@Validator([
-  { fields: [v.body("email")], validators: [{ name: "required" }, { name: "is_email" }] }
-], { order: 0, then: "process", else: "validationError" })
-validate() {}
-
-@Responder("json", {
-  statusCode: 400,
-  body: { ok: false, errors: v.stepResult("validate", "errors") }
-}, { order: 1 })
-validationError() {}
-```
-
-When validation fails, the `errors` object is populated with field-level error messages that the responder can return to the client.
-
-## Debug Mode
-
-Flosync includes a built-in debug mode that injects a `_debug` object into workflow responses, containing the full `stepResults` map of every step that executed. This is invaluable for development and troubleshooting without adding `console.log` statements.
-
-### Enabling debug
-
-**1. Global (via config)** — applies to all workflow runs:
-
-```typescript
-flosync.configure({
-  debug: true,
-  connectors: { ... },
-});
-```
-
-**2. Per-request (via header)** — enable for a single call:
-
-```bash
-curl -X POST http://localhost:3384/payment/initialize \
-  -H "Content-Type: application/json" \
-  -H "x-flosync-debug: true" \
-  -d '{"email": "user@example.com", "amount": 5000}'
-```
-
-**3. Per-request (via query param):**
-
-```bash
-curl "http://localhost:3384/books?debug=true"
-```
-
-### Debug output
-
-When debug mode is active, a `_debug` key is appended to the response body:
-
-```json
-{
-  "message": "Payment initialized successfully",
-  "data": {
-    "authorization_url": "https://checkout.paystack.com/abc123",
-    "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
-  },
-  "_debug": {
-    "stepResults": {
-      "validate": { "valid": true },
-      "generateReference": { "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
-      "initialize": {
-        "authorization_url": "https://checkout.paystack.com/abc123",
-        "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
-      }
-    }
-  }
-}
-```
-
-When debug mode is **off** (default), the `_debug` key is completely absent — zero overhead and no payload pollution.
-
-> **Note:** Debug mode works for both local workflow execution (`flosync.run()`) and remote execution via `client.workflows.run()` / `client.workflows.runByWebhook()`.
-
-## Encryption
-
-Use `s.encrypt(connectorId, action, config)` with built-in encryption connectors. All use Node `crypto`; Argon2 and bcrypt require optional packages.
-
-| Connector | Actions |
-|-----------|---------|
-| `base64.encryption` | `base64.encode`, `base64.decode` |
-| `hash.encryption` | `hash`, `hash.md5`, `hash.sha1`, `hash.sha256`, `hash.sha512` |
-| `aes.encryption` | `aes.encrypt`, `aes.decrypt`, `aes.generate_key`, `aes.generate_iv` |
-| `rsa.encryption` | `rsa.generate_keypair`, `rsa.encrypt`, `rsa.decrypt`, `rsa.sign`, `rsa.verify` |
-| `hmac.encryption` | `hmac.create`, `hmac.verify` |
-| `password.encryption` | `password.argon2_hash`, `password.argon2_verify`, `password.pbkdf2_hash`, `password.pbkdf2_verify`, `password.scrypt_hash`, `password.scrypt_verify`, `password.bcrypt_hash`, `password.bcrypt_verify`, `password.generate_salt` |
-
-**Examples:**
-
-```javascript
-s.encrypt('hash.encryption', 'hash', { data: v.body('payload'), algorithm: 'sha256' });
-s.encrypt('base64.encryption', 'base64.encode', { data: v.stepResult('prev') });
-s.encrypt('aes.encryption', 'aes.encrypt', { data: v.body('secret'), key: v.vars('key') });
-s.encrypt('rsa.encryption', 'rsa.sign', { data: v.body('payload'), private_key: v.vars('privateKey') });
-s.encrypt('hmac.encryption', 'hmac.create', { data: v.body('message'), key: v.vars('secret') });
-s.encrypt('password.encryption', 'password.argon2_hash', { password: v.body('password') });
-```
-
-**Optional packages:** `password.argon2_hash` / `password.argon2_verify` need `argon2`; `password.bcrypt_hash` / `password.bcrypt_verify` need `bcrypt`. Install with `npm install argon2 bcrypt` if you use those actions.
-
-## Connector Registry
-
-Use `ConnectorId` and `ConnectorActions` for built-in connectors, or `defineCustomConnector` for your own. This gives you autocomplete and avoids typos.
-
-### Built-in connectors
-
-```javascript
-import { flosync, ConnectorId, ConnectorActions, getConnectorActions, listBuiltInConnectors } from 'cliodot';
-
-// Database
-s.db('mongodb', 'insertOne', { collection: 'orders', document: {} });
-s.db('mysql', 'query', { query: 'SELECT 1', params: [] });
-s.db('postgres', 'query', { query: 'SELECT 1', params: [] });
-s.db('redis', 'redis.set', { key: 'key', value: 'value' });
-
-// Auth
-s.auth(ConnectorId.Auth.Bearer, ConnectorActions[ConnectorId.Auth.Bearer][0], { token: '{{ headers.authorization }}' });
-
-// Utility - use ConnectorActions or getConnectorActions for autocomplete
-s.util(ConnectorId.Utility.DateTime, 'get_current_datetime', {});
-s.util(ConnectorId.Utility.String, 'slugify', { string: 'Hello World' });
-s.util(ConnectorId.Utility.Math, 'add', { numbers: [10, 20] });
-s.util(ConnectorId.Utility.Random, 'random_uuid', {});
-s.util(ConnectorId.Utility.Compare, 'diff_objects', { object1: {}, object2: {} });
-s.util(ConnectorId.Utility.Geo, 'calculate_distance', { lat1: 0, lon1: 0, lat2: 1, lon2: 1 });
-
-// Get actions for a connector (for suggestions/autocomplete)
-const stringActions = getConnectorActions(ConnectorId.Utility.String);
-
-// List all built-in connectors and their actions
-console.log(listBuiltInConnectors());
-```
-
-### Custom connectors
-
-Define your connector with typed actions for autocomplete:
-
-```javascript
-import { defineCustomConnector } from 'cliodot';
-
-const MyStore = defineCustomConnector('my.store', {
-  login: 'login',
-  listItems: 'listItems',
-  createItem: 'createItem',
-});
-
-flosync.registerConnector(MyStore.id, myStoreConnector);
-
-s.connector(MyStore.id, MyStore.actions.login, { body: { email: '{{ body.email }}' } });
-s.connector(MyStore.id, MyStore.actions.listItems, {});
-```
-
-For a simple list of action names:
-
-```javascript
-import { defineCustomConnectorFromList } from 'cliodot';
-
-const MyStore = defineCustomConnectorFromList('my.store', ['login', 'listItems', 'createItem']);
-```
-
-### Typed connectors (for remote connectors)
-
-When using remote connectors, you do not have the implementation locally. `defineTypedConnector` lets you define per-action schema so TypeScript can infer request/response shapes across decorators, builder calls, and `runConnector`.
-
-```typescript
-import { defineTypedConnector } from "cliodot";
-
-const Paystack = defineTypedConnector("paystack", {
-  initializeTransaction: "Initialize Transaction",
-  verifyTransaction: "Verify Transaction",
-  listTransactions: "List Transactions",
-}, {
-  initializeTransaction: {
-    body: {} as { email: string; amount: number; reference?: string; callback_url?: string },
-    headers: {} as { "Idempotency-Key"?: string },
-    vars: {} as { traceId?: string },
-    response: {} as { authorization_url: string; access_code: string; reference: string },
-  },
-  verifyTransaction: {
-    pathParams: {} as { reference: string },
-    response: {} as { status: string; amount: number; currency: string; paid_at: string },
-  },
-  listTransactions: {
-    params: {} as { page?: number; perPage?: number; status?: string },
-    response: {} as { data: Array<{ reference: string; amount: number; status: string }> },
-  },
-});
-```
-
-Schema fields:
-
-| Field | Description |
-|-------|-------------|
-| `body` | Shape of request body |
-| `params` | Shape of query/params |
-| `pathParams` | Shape of URL path params |
-| `headers` | Shape of custom headers |
-| `vars` | Shape of step-level vars merged before execution |
-| `response` | Shape of expected response |
-
-Use `{} as YourType` to define each shape without runtime values.
-
-**Extracting types with helper utilities:**
-
-```typescript
-import type {
-  ConnectorBody,
-  ConnectorParams,
-  ConnectorPathParams,
-  ConnectorHeaders,
-  ConnectorVars,
-  ConnectorResponse,
-} from "cliodot";
-
-type InitBody = ConnectorBody<typeof Paystack, "initializeTransaction">;
-type InitHeaders = ConnectorHeaders<typeof Paystack, "initializeTransaction">;
-type InitVars = ConnectorVars<typeof Paystack, "initializeTransaction">;
-type VerifyPath = ConnectorPathParams<typeof Paystack, "verifyTransaction">;
-type ListParams = ConnectorParams<typeof Paystack, "listTransactions">;
-type VerifyResponse = ConnectorResponse<typeof Paystack, "verifyTransaction">;
-```
-
-**Using in decorators (typed action key + typed config):**
-
-```typescript
-import { Workflow, Http, Connector, Responder, v } from "cliodot";
-import type { WorkflowContext, StepOutput, ConnectorResponse } from "cliodot";
-
-type InitResponse = ConnectorResponse<typeof Paystack, "initializeTransaction">;
-
-@Workflow("paystack-init", "Initialize Paystack Payment")
-@Http("POST", "/pay")
-class PaystackInitWorkflow {
-  @Connector(
-    Paystack,
-    "initializeTransaction",
-    {
-      body: { email: v.body("email"), amount: v.body("amount"), callback_url: v.body("callback_url") },
-      headers: { "Idempotency-Key": "{{ trigger.idempotencyKey }}" },
-      vars: { traceId: "{{ trigger.traceId }}" },
-    },
-    { order: 0, stage: "post" }
-  )
-  init(ctx: WorkflowContext<InitResponse>): StepOutput<{ url: string; ref: string }> {
-    return {
-      out: {
-        url: ctx.input.authorization_url,
-        ref: ctx.input.reference,
-      },
-    };
-  }
-
-  @Responder("json", {
-    body: { url: v.stepResult("init", "url"), reference: v.stepResult("init", "ref") },
-  }, { order: 1 })
-  respond() {}
-}
-```
-
-You can still use the classic style (`Paystack.id` + `Paystack.actions.someAction`) if you prefer.
-
-**Typed connectors also work in builder and direct runs:**
-
-```typescript
-// Builder
-workflow.step("init", (s) =>
-  s.connector(Paystack, "initializeTransaction", {
-    body: { email: "{{ trigger.email }}", amount: "{{ trigger.amount }}" },
-    headers: { "Idempotency-Key": "{{ trigger.idempotencyKey }}" },
-  })
-);
-
-// Direct connector execution
-await flosync.runConnector(Paystack, "verifyTransaction", {
-  pathParams: { reference: "ref_123" },
-});
-```
-
-Template strings are accepted in typed request fields (`body`, `params`, `pathParams`, `headers`, `vars`) so workflow expressions continue to work with strong typing.
-
-Available type helpers:
-
-| Helper | Description |
-|--------|-------------|
-| `ConnectorBody<TDef, TAction>` | Extracts `body` type |
-| `ConnectorParams<TDef, TAction>` | Extracts `params` type |
-| `ConnectorPathParams<TDef, TAction>` | Extracts `pathParams` type |
-| `ConnectorHeaders<TDef, TAction>` | Extracts `headers` type |
-| `ConnectorVars<TDef, TAction>` | Extracts `vars` type |
-| `ConnectorResponse<TDef, TAction>` | Extracts `response` type |
-| `ConnectorActionRequest<TDef, TAction>` | Extracts full request shape |
-| `ConnectorTypedRequestConfig<TDef, TAction>` | Typed decorator/builder request config |
-
-Examples-first guide:
-
-- [`Typed Connector End-to-End Samples`](./TYPED_CONNECTOR_EXAMPLES.md)
-
-## Connectors by ID
-
-Use `s.connector(connectorId, action, config)` with any connector ID. For remote runs, connectors are resolved from your account. For local runs, register connectors first with `flosync.registerConnector(id, connector)` or pass config in `configure({ connectors: { 'connector-id': { ... } } })`.
-
-## API Client
-
-When configured with `apiKey`, `apiSecret`, and `baseUrl`:
-
-```javascript
-const client = flosync.getClient();
-
-await flosync.push(workflow);
-const wf = await flosync.pull(groupId);
-
-const { workflowGroups, pagination } = await client.workflows.list({ status: 'active', page: 1, limit: 20 });
-await client.workflows.run(groupId, triggerId, { payload: { ... } });
-await client.workflows.runByWebhook('/orders', 'POST', { body: { ... } });
-
-const functions = await client.functions.list();
-await client.functions.push(fn);
-const fn = await client.functions.pull(functionId);
-await client.functions.invoke(functionId, { args: { ... } });
-
-await client.projects.create({ name: 'My Project' });
-const projects = await client.projects.list();
-```
-
-### Run connector from online
-
-Execute connectors stored in your Cliodot account:
-
-```javascript
-const result = await flosync.runConnector('paystack', 'Initialize Transaction', {
-  body: { email: 'user@example.com', amount: 5000, reference: 'ref_123' },
-});
-
-const { connectors, pagination } = await client.connectors.list();
-const { installations } = await client.connectors.installed();
-const connector = await client.connectors.get('paystack');
-const data = await client.connectors.execute('paystack', 'Verify Transaction', {
-  pathParams: { reference: 'ref_123' },
-});
-```
-
-| Method | Description |
-|--------|-------------|
-| `flosync.runConnector(id, action, options, { remote? })` | Run connector (local if registered, else remote) |
-| `client.connectors.get(id)` | Get connector definition |
-| `client.connectors.list(options?)` | List connectors (type, status, category, page, limit) |
-| `client.connectors.search(options?)` | Search public connectors |
-| `client.connectors.push(connector)` | Create or update connector (by `_id` or `slug`) |
-| `client.connectors.installed(options?)` | List installed connectors |
-| `client.connectors.install(id, { auth?, base_url? })` | Install connector |
-| `client.connectors.uninstall(id)` | Uninstall connector |
-| `client.connectors.execute(id, action, options)` | Execute connector action remotely |
-
-### Workflows
-
-| Method | Description |
-|--------|-------------|
-| `client.workflows.push(workflow)` | Create or update workflow |
-| `client.workflows.pull(groupId)` | Fetch workflow as IWorkflow |
-| `client.workflows.list(options?)` | List workflow groups |
-| `client.workflows.run(groupId, triggerId, payload)` | Run by trigger ID (payload may include `environment: "dev" \| "prod"`) |
-| `client.workflows.runByWebhook(path, method, payload)` | **`POST /workflows/test/webhook`** — run the workflow whose HTTP trigger matches `path` and `method` (no group id in the request). Payload may include `environment`, `executionHeaders`, and the child body fields (merged into `payload` for the API). |
-| `client.workflows.promote(groupId)` | Promote to production |
-
-See [Workflows](../docs/WORKFLOWS.md) for full documentation. See [Building and Pushing Custom Connectors](../docs/BUILDING_CONNECTORS.md) for connectors.
-
-## Custom Connectors
-
-See [Building and Pushing Custom Connectors](../docs/BUILDING_CONNECTORS.md) for full samples of JSON, ConnectorBuilder, and custom execute connectors.
-
-### REST connectors
-
-```javascript
-flosync.registerConnector('my-connector', {
-  _id: 'my-connector',
-  type: 'REST',
-  base_url: 'https://api.example.com',
-  auth: { type: 'bearer', token: process.env.MY_API_KEY },
-  endpoints: [
-    { name: 'GetUser', method: 'GET', path: '/users/:id' },
-  ],
-});
-```
-
-### Custom execute connector
-
-For full control, provide an `execute` function. The engine calls it with `(action, options, context)`.
-
-**Connector definition**
-
-```javascript
-flosync.registerConnector('my.auth', {
-  _id: 'my.auth',
-  type: 'system',
-  name: 'My Auth',
-  meta: { category: 'authentication' },
-  auth: { type: 'none' },
-  execute: async (action, options, context) => { ... },
-});
-```
-
-Import types for TypeScript: `ConnectorExecuteOptions`, `ConnectorContext`, `ConnectorExecuteFn` from `cliodot`.
-
-**Execute signature**
-
-```typescript
-execute(
-  action: string,
-  options: ConnectorExecuteOptions,
-  context: ConnectorContext
-): Promise<unknown>
-```
-
-**Options** (from workflow step config):
-
-| Field | When used | Description |
-|-------|-----------|-------------|
-| `body` | API, auth, db, encrypt | Request body or payload |
-| `params` | API | Query params |
-| `pathParams` | API | Path params (e.g. `:id` in `/users/:id`) |
-| `headers` | API | Extra headers |
-| `database` | DB | Database name override |
-| `connection_id` | DB | Connection ID override |
-
-**Context** (from run state):
-
-| Field | Description |
-|-------|-------------|
-| `headers` | HTTP headers from the trigger |
-| `connectorConfig` | Per-connector config from `configure({ connectors: { 'id': {...} } })` |
-| `env` | Environment overrides |
-| `trigger` | Trigger payload (body, pathParams, params, etc.) |
-| `stepResults` | Results of previous steps |
-| `vars` | Workflow variables |
-
-**Discovering IDs and actions**
-
-- Built-in: `ConnectorId`, `ConnectorActions`, `getConnectorActions(connectorId)`, `listBuiltInConnectors()`
-- Custom: `defineCustomConnector(id, actions)` or `defineCustomConnectorFromList(id, ['action1', 'action2'])`
-
-**REST endpoint shape**
-
-```typescript
-{
-  name: string;           // Action name (matches s.connector(id, name, config))
-  action?: string;        // Alias for name
-  method: string;        // GET, POST, PUT, DELETE, etc.
-  path: string;          // e.g. '/users/:id' or '/orders'
-  headers?: Record<string, string>;
-  body_schema?: object;
-  response_mapping?: Record<string, string>;  // { "userId": "data.id" }
-  timeout_ms?: number;
-}
-```
+## Documentation
 
-**Return format**
+All guides, API references, and examples live on **[docs.cliodot.com](https://docs.cliodot.com)**:
 
-- API/DB/Encrypt: `{ raw, mapped }` or any object (engine uses `mapped ?? raw`)
-- Auth: `{ valid: boolean, token?, user?, error? }` for success/failure branching
+| Topic | Docs |
+|-------|------|
+| Getting started | [docs.cliodot.com/getting-started](https://docs.cliodot.com/getting-started) |
+| SDK overview | [docs.cliodot.com/sdk](https://docs.cliodot.com/sdk) |
+| Workflows | [docs.cliodot.com/workflows](https://docs.cliodot.com/workflows) |
+| Functions | [docs.cliodot.com/functions](https://docs.cliodot.com/functions) |
+| Connectors | [docs.cliodot.com/connectors](https://docs.cliodot.com/connectors) |
+| Gateway Surface | [SURFACE.md](./SURFACE.md) |
+| Surface internals | [SURFACE_INTERNALS.md](./SURFACE_INTERNALS.md) |
+| Typed connectors | [TYPED_CONNECTOR_EXAMPLES.md](./TYPED_CONNECTOR_EXAMPLES.md) |
+| API client | [docs.cliodot.com/api-client](https://docs.cliodot.com/api-client) |
+| OAuth apps | [docs.cliodot.com/oauth-apps](https://docs.cliodot.com/oauth-apps) |
+| Auth apps (MFA) | [docs.cliodot.com/auth-apps](https://docs.cliodot.com/auth-apps) |
+| Event Apps | [EVENTS.md](./EVENTS.md) |
 
 ## License