@hotmeshio/long-tail 0.1.4 → 0.1.6

package/docs/auth.md

@@ -0,0 +1,181 @@
+# Authentication
+
+Every API request in Long Tail passes through an authentication adapter before reaching route handlers. The adapter inspects the incoming request, verifies the caller's identity, and returns a structured `AuthPayload`. If verification fails, the adapter returns `null` and the middleware responds with `401 Unauthorized`.
+
+This design decouples identity verification from the rest of the application. The built-in adapter handles JWTs. Teams that rely on OAuth providers, API keys, or session cookies can swap in a custom adapter without modifying any route logic.
+
+## Interface
+
+Two types define the contract between Long Tail and any authentication strategy:
+
+```typescript
+interface LTAuthAdapter {
+  authenticate(req: any): Promise<AuthPayload | null>;
+}
+
+interface AuthPayload {
+  userId: string;
+  email?: string;
+  role?: string;
+  [key: string]: any;
+}
+```
+
+`LTAuthAdapter` requires a single method. It receives the raw request object and returns either a valid `AuthPayload` or `null`. The index signature on `AuthPayload` allows adapters to attach arbitrary claims (tenant ID, permissions bitmask, etc.) without altering the interface.
+
+## Configuration via start()
+
+The simplest way to configure auth is through the `start()` config:
+
+```typescript
+import { start } from '@hotmeshio/long-tail';
+
+// Use the built-in JWT adapter with an explicit secret
+await start({
+  database: { connectionString: process.env.DATABASE_URL },
+  auth: { secret: process.env.JWT_SECRET },
+  workers: [ ... ],
+});
+
+// Or plug in a custom adapter
+await start({
+  database: { connectionString: process.env.DATABASE_URL },
+  auth: { adapter: new GoogleOAuthAdapter() },
+  workers: [ ... ],
+});
+```
+
+When `auth.secret` is provided, Long Tail uses the built-in `JwtAuthAdapter` with that secret. When `auth.adapter` is provided, the custom adapter replaces the JWT adapter entirely. If neither is set, the built-in JWT adapter reads from the `JWT_SECRET` environment variable.
+
+## Built-in JWT Adapter
+
+`JwtAuthAdapter` is the default adapter. It extracts a Bearer token from the `Authorization` header and verifies it against the `JWT_SECRET` environment variable.
+
+A companion utility, `signToken`, generates tokens for use in tests or login endpoints:
+
+```typescript
+import { signToken } from '@hotmeshio/long-tail';
+
+const token = signToken({ userId: '42', email: 'ops@example.com' }, '8h');
+```
+
+The first argument is the payload. The second, optional argument is the expiration duration (defaults vary by configuration). The function uses `JWT_SECRET` internally.
+
+## Middleware
+
+Long Tail's embedded server automatically applies auth middleware to all API routes. The following middleware functions are also exported for advanced use cases.
+
+### createAuthMiddleware
+
+`createAuthMiddleware` accepts any `LTAuthAdapter` and returns Express-compatible middleware. On each request, it calls the adapter's `authenticate` method and attaches the result to `req.auth`. If the adapter returns `null`, the middleware halts the request with a `401` response.
+
+### requireAuth
+
+`requireAuth` is the default auth middleware used by Long Tail's embedded server. It delegates to whatever adapter was configured via `start()`, or falls back to the built-in `JwtAuthAdapter`.
+
+### requireAdmin
+
+`requireAdmin` is a separate middleware that runs after authentication. It checks whether the authenticated user holds superadmin status, either through a database lookup (`isSuperAdmin()`) or by verifying that the JWT `role` claim equals `'admin'`. Requests that fail this check receive a `403 Forbidden` response.
+
+## Custom Adapter Example
+
+The following adapter authenticates requests using Google OAuth ID tokens. It verifies the token with Google's servers, extracts the user's subject identifier and email, and returns them as an `AuthPayload`.
+
+```typescript
+import type { LTAuthAdapter, AuthPayload } from '@hotmeshio/long-tail';
+import { OAuth2Client } from 'google-auth-library';
+
+const google = new OAuth2Client(process.env.GOOGLE_CLIENT_ID);
+
+class GoogleOAuthAdapter implements LTAuthAdapter {
+  async authenticate(req): Promise<AuthPayload | null> {
+    const header = req.headers.authorization;
+    if (!header?.startsWith('Bearer ')) return null;
+    try {
+      const ticket = await google.verifyIdToken({
+        idToken: header.slice(7),
+        audience: process.env.GOOGLE_CLIENT_ID,
+      });
+      const { sub, email } = ticket.getPayload()!;
+      return { userId: sub, email, role: 'member' };
+    } catch {
+      return null;
+    }
+  }
+}
+
+// Pass to start()
+await start({
+  database: { connectionString: process.env.DATABASE_URL },
+  auth: { adapter: new GoogleOAuthAdapter() },
+  workers: [ ... ],
+});
+```
+
+The same pattern applies to any identity provider: extract credentials from the request, verify them against the provider, and return an `AuthPayload` or `null`.
+
+## Development Shortcut
+
+During local development, a no-op adapter that returns a hardcoded payload removes the need for a running identity provider:
+
+```typescript
+import type { LTAuthAdapter, AuthPayload } from '@hotmeshio/long-tail';
+
+class DevAdapter implements LTAuthAdapter {
+  async authenticate(): Promise<AuthPayload> {
+    return { userId: 'dev-user', email: 'dev@localhost', role: 'admin' };
+  }
+}
+
+await start({
+  database: { connectionString: process.env.DATABASE_URL },
+  auth: { adapter: new DevAdapter() },
+  workers: [ ... ],
+});
+```
+
+This adapter grants admin access to every request. Restrict its use to local environments.
+
+## Service Account Authentication
+
+Service accounts are named identities that authenticate with API keys instead of passwords or OAuth. They share the same RBAC system as human users — same roles, same delegation tokens, same credential storage.
+
+### How It Works
+
+Service account API keys are prefixed with `lt_bot_` and validated via bcrypt comparison, following the same pattern as service tokens. The built-in `JwtAuthAdapter` detects the prefix automatically:
+
+```
+Authorization: Bearer lt_bot_a1b2c3d4e5f6...
+```
+
+When a service account API key is validated, the adapter returns an `AuthPayload` with the account's `userId` (from the `lt_users` table). From that point forward, the request is indistinguishable from a human user's — the same middleware, RBAC checks, and identity propagation apply.
+
+### Creating a Service Account
+
+Service accounts are managed via the `/api/bot-accounts` endpoints (admin-only). See the [Service Accounts API](api/service-accounts.md) for full documentation.
+
+```bash
+# Create a service account
+curl -X POST http://localhost:3000/api/bot-accounts \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "ci-bot", "description": "Runs scheduled workflows"}'
+
+# Generate an API key (shown once)
+curl -X POST http://localhost:3000/api/bot-accounts/$BOT_ID/api-keys \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "production", "scopes": ["mcp:tool:call"]}'
+```
+
+### Identity in Workflows
+
+When a service account starts a workflow, its `userId` flows through the same envelope and `ToolContext` path as a human user. Activities that call `getToolContext()` receive a `ToolPrincipal` with `type: 'bot'`, and the task record's `initiated_by` column stores the account's user ID for audit.
+
+## Environment Variables
+
+| Variable     | Required | Description                                      |
+|--------------|----------|--------------------------------------------------|
+| `JWT_SECRET` | Yes      | Signing and verification key for the JWT adapter. |
+
+`JWT_SECRET` must be set when using `JwtAuthAdapter` or `signToken`. Omitting it will cause token verification to fail at runtime. Use a cryptographically random string of at least 32 characters in production.

package/docs/cloud.md

@@ -0,0 +1,272 @@
+# Cloud Deployment
+
+Long Tail embeds its own server. Your application calls `start()` with a config object — that's the entire entry point. In production you typically run two container types that share the same PostgreSQL database: one serves HTTP requests, the other executes workflows. This separation lets each tier scale independently.
+
+## Why Separate
+
+| Concern | API container | Worker container |
+|---------|--------------|-----------------|
+| Purpose | Serve REST endpoints, authenticate requests, start workflows, query tasks and escalations | Execute workflow code, run activities, manage interceptors |
+| Scaling trigger | Request volume | Workflow queue depth |
+| Resource profile | I/O-bound (Postgres reads, HTTP) | Potentially CPU-bound (AI calls, document processing) |
+| Network exposure | Public (behind load balancer) | Private (no inbound traffic) |
+| Deploy cadence | Change routes or auth without touching workers | Update workflow logic without restarting the API |
+
+Both containers install the same packages (`@hotmeshio/long-tail`, `@hotmeshio/hotmesh`) and share the same PostgreSQL connection string. They differ only in what they configure at boot.
+
+## API Container
+
+The API container runs the embedded server and serves REST endpoints. It does not start workers — no workflow execution happens here.
+
+```typescript
+// api.ts — API container entry point
+import { start } from '@hotmeshio/long-tail';
+
+await start({
+  database: { connectionString: process.env.DATABASE_URL },
+  server: { port: Number(process.env.PORT) || 3000 },
+  auth: { secret: process.env.JWT_SECRET },
+});
+```
+
+That's it. Migrations run, the server starts, routes are mounted, auth is configured. The API container needs network ingress (load balancer, domain). It reads and writes Postgres but never processes workflow task queues.
+
+## Worker Container
+
+The worker container registers the LT interceptor, starts workflow workers, and optionally connects telemetry, event, and maintenance adapters. It runs no HTTP server.
+
+```typescript
+// worker.ts — Worker container entry point
+import { start } from '@hotmeshio/long-tail';
+import * as reviewContent from './workflows/review-content';
+import * as verifyDocument from './workflows/verify-document';
+
+await start({
+  database: { connectionString: process.env.DATABASE_URL },
+  server: { enabled: false },
+  workers: [
+    { taskQueue: 'long-tail', workflow: reviewContent.reviewContent },
+    { taskQueue: 'long-tail-verify', workflow: verifyDocument.verifyDocument },
+  ],
+  telemetry: process.env.HONEYCOMB_API_KEY
+    ? { honeycomb: { apiKey: process.env.HONEYCOMB_API_KEY } }
+    : undefined,
+  events: process.env.NATS_URL
+    ? { nats: { url: process.env.NATS_URL } }
+    : undefined,
+  logging: { pino: { level: 'info' } },
+});
+```
+
+The worker container needs no inbound network access. It connects outbound to PostgreSQL (and optionally NATS, Honeycomb, etc.) and polls task queues via the HotMesh engine.
+
+## Architecture Diagram
+
+```
+                    ┌──────────────────────────────────┐
+                    │          Load Balancer           │
+                    └───────────────┬──────────────────┘
+                                    │
+                    ┌───────────────▼───────────────────┐
+                    │       API Containers (N)          │
+                    │                                   │
+                    │  start({ server, database })      │
+                    │  Embedded Express + Auth + Routes │
+                    │  No workers, no interceptors      │
+                    └───────────────┬───────────────────┘
+                                    │
+                    ┌───────────────▼──────────────────┐
+                    │          PostgreSQL              │
+                    │                                  │
+                    │  Workflow state (HotMesh)        │
+                    │  lt_tasks, lt_escalations        │
+                    │  lt_users, lt_config_*           │
+                    └───────────────▲──────────────────┘
+                                    │
+                    ┌───────────────┴──────────────────┐
+                    │     Worker Containers (M)        │
+                    │                                  │
+                    │  start({ workers, telemetry })   │
+                    │  Workflow execution + activities │
+                    │  Telemetry, events, maintenance  │
+                    │  No HTTP, no public ingress      │
+                    └──────────────────────────────────┘
+```
+
+API containers and worker containers scale independently. N and M need not be equal.
+
+## AWS ECS
+
+Two ECS services in one cluster, both in the same VPC with access to the same RDS PostgreSQL instance.
+
+### API service
+
+- Fargate or EC2 launch type
+- Attached to an Application Load Balancer (ALB) target group
+- Health check: `GET /health`
+- Auto-scaling policy: target tracking on `RequestCountPerTarget`
+- Security group: allow inbound 443 from ALB, outbound 5432 to RDS
+
+### Worker service
+
+- Fargate or EC2 launch type
+- **No target group** — no inbound traffic
+- Auto-scaling policy: step scaling on a custom CloudWatch metric for queue depth, or target tracking on CPU utilization
+- Security group: outbound 5432 to RDS, outbound 443 to Honeycomb/NATS as needed, no inbound rules
+
+### Task definitions
+
+Both task definitions use the same Docker image. The difference is the `command` override:
+
+```json
+// API task definition
+{
+  "containerDefinitions": [{
+    "command": ["node", "dist/api.js"],
+    "portMappings": [{ "containerPort": 3000 }]
+  }]
+}
+
+// Worker task definition
+{
+  "containerDefinitions": [{
+    "command": ["node", "dist/worker.js"]
+  }]
+}
+```
+
+### RDS
+
+- PostgreSQL 15+ (gen_random_uuid requires pgcrypto or Postgres 13+)
+- Multi-AZ for production
+- Both services connect via the same `DATABASE_URL` endpoint
+
+## GCP Cloud Run
+
+### API service
+
+```bash
+gcloud run deploy long-tail-api \
+  --image gcr.io/PROJECT/long-tail:latest \
+  --command node,dist/api.js \
+  --port 3000 \
+  --allow-unauthenticated \
+  --add-cloudsql-instances PROJECT:REGION:INSTANCE \
+  --set-env-vars DATABASE_URL=...,JWT_SECRET=...
+```
+
+### Worker service
+
+```bash
+gcloud run deploy long-tail-workers \
+  --image gcr.io/PROJECT/long-tail:latest \
+  --command node,dist/worker.js \
+  --no-allow-unauthenticated \
+  --min-instances 1 \
+  --add-cloudsql-instances PROJECT:REGION:INSTANCE \
+  --set-env-vars DATABASE_URL=...,HONEYCOMB_API_KEY=...
+```
+
+Workers need `--min-instances 1` (or higher) because they must stay warm to poll task queues. Cloud Run scales to zero by default, which would stop all workflow processing.
+
+### GKE alternative
+
+For more control over scaling, use two Kubernetes Deployments in the same cluster:
+
+```yaml
+# api-deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: long-tail-api
+spec:
+  replicas: 2
+  template:
+    spec:
+      containers:
+        - name: api
+          image: gcr.io/PROJECT/long-tail:latest
+          command: ["node", "dist/api.js"]
+          ports:
+            - containerPort: 3000
+---
+# worker-deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: long-tail-workers
+spec:
+  replicas: 3
+  template:
+    spec:
+      containers:
+        - name: worker
+          image: gcr.io/PROJECT/long-tail:latest
+          command: ["node", "dist/worker.js"]
+```
+
+The API Deployment sits behind a Service + Ingress. The worker Deployment has no Service — it only makes outbound connections.
+
+## Environment Variables
+
+| Variable | API | Worker | Description |
+|----------|:---:|:------:|-------------|
+| `DATABASE_URL` | yes | yes | PostgreSQL connection string |
+| `PORT` | yes | — | HTTP listen port (default: 3000) |
+| `JWT_SECRET` | yes | — | Secret for verifying and signing JWTs |
+| `HONEYCOMB_API_KEY` | — | yes | Honeycomb telemetry (optional) |
+| `HMSH_TELEMETRY` | — | yes | Span verbosity: `info` or `debug` |
+| `NATS_URL` | — | yes | NATS server for milestone events (optional) |
+| `OPENAI_API_KEY` | — | yes | For workflows that call OpenAI (optional) |
+
+Environment variables serve as fallbacks. When using `start()`, prefer passing config directly — it's explicit and type-checked. The API container does not need telemetry, event, or AI keys — it never executes workflow code. The worker container does not need `JWT_SECRET` or `PORT` — it never serves HTTP.
+
+## Docker
+
+A single Dockerfile with different `CMD` targets:
+
+```dockerfile
+FROM node:20-slim AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-slim
+WORKDIR /app
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/package.json ./
+
+# Override CMD at deploy time:
+#   API:    ["node", "dist/api.js"]
+#   Worker: ["node", "dist/worker.js"]
+CMD ["node", "dist/api.js"]
+```
+
+For local development, docker-compose runs both roles in a single container:
+
+```yaml
+services:
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_DB: longtail
+      POSTGRES_PASSWORD: password
+    ports:
+      - "${LT_PG_PORT:-5432}:5432"
+
+  app:
+    build: .
+    command: node dist/index.js   # combined API + workers
+    environment:
+      DATABASE_URL: postgres://postgres:password@postgres:5432/longtail
+      JWT_SECRET: dev-secret
+    ports:
+      - "${LT_PORT:-3000}:3000"
+    depends_on:
+      - postgres
+```
+
+The combined `index.js` entry point (used in development and the demo) calls `start()` with both server and workers enabled. In production, split them into `api.js` and `worker.js` with different `start()` configs.

package/docs/compilation.md

@@ -0,0 +1,136 @@
+# The Compilation Pipeline
+
+Every AI-driven execution carries cost. An LLM reasons through each step, selects tools, interprets results, and decides what to do next. It works, but it is slow, non-deterministic, and consumes tokens on every run.
+
+Long Tail records what the LLM did, extracts the pattern, and compiles it into a deterministic workflow. The next time the same problem appears, it runs without an LLM — no reasoning, no token cost, same result.
+
+This guide follows a single query through the full lifecycle: dynamic execution, compilation, deterministic replay, and automatic routing. All steps take place in the dashboard's **Pipeline Designer** page (sidebar: **MCP Workflows → Pipeline Designer**).
+
+---
+
+## The Dynamic Execution
+
+Open **Pipeline Designer** from the sidebar. The page lists previous MCP query runs and provides a prompt field to start a new one. Describe what you need in natural language — for example, "Log into the dashboard, discover all navigation pages, and screenshot each one." Optionally constrain which MCP tool tags to search.
+
+When the query is submitted, the `mcpQuery` workflow starts. It discovers available tools by tag (GIN-indexed full-text search), then enters an agentic loop: the LLM selects a tool, calls it, reads the result, and decides the next step. Every tool call is checkpointed by the workflow engine. If the process crashes mid-execution, it resumes from the last checkpoint — no work is lost, no step runs twice.
+
+The run appears in the **Pipeline Designer** list once it completes. Click into it to open the **Compilation Wizard**.
+
+---
+
+## The Compilation Wizard
+
+The wizard has six steps, shown as numbered circles in a sticky bar at the top of the page. Each step represents one stage of converting the dynamic execution into a deployable deterministic workflow:
+
+1. **Describe**
+2. **Discover**
+3. **Compile**
+4. **Deploy**
+5. **Test**
+6. **Verify**
+
+Steps unlock sequentially — you must complete each before advancing.
+
+### 1. Describe
+
+**Subtitle:** *Dynamic LLM-orchestrated execution — the discovery run*
+
+The first panel displays what the LLM produced: the input envelope on the left and the structured output on the right. Duration is shown. This is the reference point — whatever the compiled workflow produces will be compared against it.
+
+### 2. Discover
+
+**Subtitle:** *Activity swimlane showing tool calls and their durations*
+
+A swimlane visualization of the execution. Each row is an MCP server, each block is a tool call, positioned on a time axis. The pattern is visible at a glance: the LLM logged in, extracted navigation links, then looped through each page to capture a screenshot.
+
+### 3. Compile
+
+**Subtitle:** *Define the deterministic workflow tool from this execution*
+
+The workflow needs an identity. This panel presents a form with:
+
+- **Namespace** — a required alphanumeric identifier for the workflow's application scope.
+- **Tool Name** — the workflow's MCP tool name for discovery. This is how other agents and workflows will find and invoke it.
+- **Description** — auto-generated from the execution trace. Editable.
+- **Tags** — suggested from the execution trace. Add or remove tags to control discoverability.
+
+An optional **Refine compilation** toggle reveals a feedback textarea where you can provide additional instructions to the compiler.
+
+Clicking **Compile Pipeline** triggers the five-stage compilation pipeline:
+
+1. **Extract** — parse the execution trace into an ordered step sequence
+2. **Analyze** — detect iteration patterns (the screenshot loop), classify inputs as dynamic (user-provided) or fixed (implementation detail)
+3. **Compile** — an LLM produces a blueprint with data-flow edges and session threading, guided by per-server **compile hints** stored in the database (e.g., which output fields to use as transform sources, how to thread browser session handles)
+4. **Build** — generate a deterministic YAML DAG with activity wiring
+5. **Validate** — check for missing wiring, lost session handles, broken iteration boundaries
+
+Once compilation succeeds, the panel switches to a read-only view showing the workflow name, status badge, namespace, topic, description, activity pipeline chain, and tags.
+
+### 4. Deploy
+
+**Subtitle:** *Review configuration, input/output schemas, and YAML definition*
+
+The deploy panel displays the compiled YAML definition, input schema, and output schema. The YAML encodes the DAG: each step names an MCP tool, declares its inputs (either from the user's request or from a prior step's output), and specifies data-flow edges.
+
+Two toggle buttons are available:
+
+- **Recompile with Feedback** — provide notes to the compiler and regenerate the YAML.
+- **Manual Edit** — directly edit the YAML, schemas, or activity manifest.
+
+A version history panel on the right tracks all edits. The step label changes from "Deploy" to "Redeploy" when the workflow is already active.
+
+Clicking **Deploy & Activate** registers the workflow as a live MCP tool — tagged for discovery, versioned, invocable by any agent, workflow, or API call.
+
+### 5. Test
+
+**Header:** *Compare Runs*
+
+The test panel runs the compiled workflow and compares it against the original dynamic execution. Two columns show:
+
+- **Left — Original MCP Query**: the dynamic LLM-orchestrated run with its input, output, and duration.
+- **Right — Compiled Pipeline Run**: the deterministic run with its input, output, and duration. A dropdown allows selecting from multiple test runs.
+
+Click **Run Test** to invoke the compiled workflow with the original input. An invocation modal appears with the pre-populated input schema.
+
+The difference is structural:
+
+| | Dynamic (LLM) | Deterministic |
+|---|---|---|
+| **Tool calls** | N (LLM selects each) | 1 pipeline (pre-wired DAG) |
+| **LLM usage** | Every step | Route + input extraction only |
+| **Determinism** | Varies per run | Identical every time |
+
+The deterministic path is faster because the LLM is used only at the edges — routing the request and extracting structured inputs from the prompt. The DAG itself executes tool calls directly with pre-wired data flow. No per-step reasoning, no tool selection, no interpretation.
+
+### 6. Verify
+
+**Header:** *End-to-End Verification*
+
+The final panel confirms end-to-end routing. The original prompt is pre-filled in an editable textarea on the left. Click **Submit** to send it through the `mcpQueryRouter` — the same entry point any future request would use. A **Reset to original** button restores the prompt if you modify it.
+
+The right column shows the result: a status badge, confidence percentage (when the deterministic path is used), and the full output in a JSON viewer. A **RouterProgressTracker** displays real-time routing progress during execution.
+
+The router performs full-text search and tag matching to find candidate workflows, then uses an LLM judge to confirm scope. When confidence exceeds the threshold, the request goes straight to the compiled workflow.
+
+```
+User prompt → Router → Discovery (FTS + tags) → LLM Judge
+                 │                                    │
+                 │  confidence ≥ 0.7                  │  no match
+                 ▼                                    ▼
+            Deterministic                          Dynamic
+        (compiled DAG, no LLM)                  (agentic loop)
+```
+
+---
+
+## How It Accumulates
+
+The first time a problem appears, the dynamic path runs. An LLM reasons through it — slow and expensive, but it works.
+
+The wizard compiles the solution into a deterministic pipeline. A human reviews the DAG, adjusts if needed, and deploys.
+
+Every subsequent occurrence is routed automatically. A single LLM call extracts structured inputs from the prompt, then the DAG executes without further reasoning.
+
+Each compiled workflow is itself a discoverable MCP tool. Other workflows and agents can invoke it. Solutions compose. The inventory of deterministic pathways grows with every problem the system solves, and the fraction of requests that require LLM reasoning shrinks.
+
+The dynamic path remains for genuinely new problems. But the long tail gets shorter.

package/docs/contributing.md

@@ -0,0 +1,56 @@
+# Contributing
+
+## Running the Demo
+
+The repository includes a working server with example workflows (`reviewContent`, `kitchenSink`, `basicEcho`, and more), Postgres, NATS, and a React dashboard.
+
+### Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/)
+
+### Run
+
+```bash
+git clone https://github.com/hotmeshio/long-tail.git
+cd long-tail
+docker compose up
+```
+
+Postgres, NATS, the API server, and the dashboard start together. The dashboard is built during the Docker image build and served as static assets. Migrations run automatically.
+
+Default ports are `3000` (API), `5432` (Postgres), `4222`/`8222` (NATS). Override any of them:
+
+```bash
+LT_PORT=3001 LT_PG_PORT=5433 LT_NATS_PORT=4223 docker compose up
+```
+
+## Testing
+
+```bash
+# Start Postgres and NATS
+docker compose up -d postgres nats
+
+# Run all tests
+npm test
+
+# Run workflow tests
+npm run test:workflows
+```
+
+## Development Setup
+
+1. Fork the repository and clone your fork
+2. Install dependencies: `npm install`
+3. Start infrastructure: `docker compose up -d postgres nats`
+4. Run tests to verify your setup: `npm test`
+
+## Pull Requests
+
+- Create a feature branch from `main`
+- Keep changes focused — one concern per PR
+- Add or update tests for any new behavior
+- Run `npm test` before submitting
+
+## Issues
+
+Report bugs and request features at [github.com/hotmeshio/long-tail/issues](https://github.com/hotmeshio/long-tail/issues).