@hotmeshio/long-tail 0.1.21 → 0.2.0

package/docs/api/http/agents.md

@@ -0,0 +1,201 @@
+# Agents API
+
+CRUD operations for agents — autonomous personas that react to events and run workflows on schedules. Each agent has an identity, motivation (goals/rules), event subscriptions, cron schedules, and a knowledge domain.
+
+All endpoints require authentication.
+
+## List agents
+
+```
+GET /api/agents?status=active&knowledge_domain=system-health&limit=25&offset=0
+```
+
+Returns agents with subscription counts and topic lists (via JOIN).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `status` | `string` | No | Filter by status: `active`, `inactive`, `paused`, `error` |
+| `knowledge_domain` | `string` | No | Filter by knowledge domain |
+| `limit` | `number` | No | Max results (default: 50) |
+| `offset` | `number` | No | Pagination offset |
+
+**Response 200:**
+
+```json
+{
+  "agents": [
+    {
+      "id": "uuid",
+      "name": "health-monitor",
+      "description": "Watches for workflow failures",
+      "status": "active",
+      "knowledge_domain": "system-health",
+      "behaviors": { "schedules": [{ "cron": "*/5 * * * *", "workflow_type": "basicEcho" }] },
+      "subscription_count": 4,
+      "sub_topics": ["workflow.failed", "activity.failed", "app.*.*.error", "task.failed"],
+      "last_run_at": "2026-05-15T04:24:58.351Z",
+      ...
+    }
+  ],
+  "total": 3
+}
+```
+
+## Get agent
+
+```
+GET /api/agents/:id
+```
+
+Returns an agent with aggregated stats (knowledge entry count, escalation count).
+
+**Response 200:**
+
+```json
+{
+  "id": "uuid",
+  "name": "health-monitor",
+  "stats": { "knowledge_count": 3, "escalation_count": 0 },
+  ...
+}
+```
+
+## Create agent
+
+```
+POST /api/agents
+```
+
+**Body:**
+
+```json
+{
+  "name": "health-monitor",
+  "description": "Watches for workflow failures and schema drift",
+  "goals": "Detect failures early, capture diagnostics",
+  "rules": "Never auto-restart failed workflows",
+  "status": "active",
+  "knowledge_domain": "system-health",
+  "behaviors": {
+    "schedules": [
+      { "cron": "*/5 * * * *", "workflow_type": "basicEcho", "envelope": {} }
+    ]
+  }
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | Yes | Unique kebab-case identifier |
+| `description` | `string` | No | One-sentence summary |
+| `goals` | `string` | No | Agent's primary motivation |
+| `rules` | `string` | No | Guardrails and constraints |
+| `status` | `string` | No | `active`, `inactive`, `paused`, `error` (default: `inactive`) |
+| `user_id` | `string` | No | Service account UUID |
+| `knowledge_domain` | `string` | No | Knowledge domain to own |
+| `behaviors` | `object` | No | `{ schedules?: AgentSchedule[] }` |
+
+**Response 201:** The created agent.
+
+## Update agent
+
+```
+PUT /api/agents/:id
+```
+
+Partial update — only include fields to change. Changing `status` or `behaviors` automatically restarts event subscriptions and cron schedules.
+
+**Response 200:** The updated agent.
+
+## Delete agent
+
+```
+DELETE /api/agents/:id
+```
+
+Permanently removes the agent. Event subscriptions are cascade-deleted. Cron schedules are stopped. Knowledge entries and workflow history are preserved.
+
+**Response 200:** `{ "deleted": true }`
+
+---
+
+## Agent Subscriptions
+
+Subscriptions wire events to workflows. When an event matches the topic pattern, the agent invokes the configured workflow.
+
+### List subscriptions
+
+```
+GET /api/agents/:agentId/subscriptions
+```
+
+**Response 200:**
+
+```json
+{
+  "subscriptions": [
+    {
+      "id": "uuid",
+      "agent_id": "uuid",
+      "topic": "workflow.failed",
+      "filter": { "status": 422 },
+      "reaction_type": "durable",
+      "workflow_type": "basicEcho",
+      "input_mapping": { "data": { "error": "{event.data.error}" } },
+      "execute_as": null,
+      "enabled": true
+    }
+  ]
+}
+```
+
+### Create subscription
+
+```
+POST /api/agents/:agentId/subscriptions
+```
+
+**Body:**
+
+```json
+{
+  "topic": "workflow.failed",
+  "reaction_type": "durable",
+  "workflow_type": "basicEcho",
+  "input_mapping": { "data": { "error": "{event.status}" } },
+  "filter": { "status": 422 },
+  "enabled": true
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `topic` | `string` | Yes | Event topic pattern. Supports `*` (one token) and `>` (rest of subject). |
+| `reaction_type` | `string` | Yes | `durable`, `pipeline`, or `mcp_query` |
+| `workflow_type` | `string` | For durable | Registered workflow name |
+| `pipeline_id` | `string` | For pipeline | YAML workflow UUID |
+| `mcp_prompt` | `string` | For mcp_query | Dynamic query prompt |
+| `input_mapping` | `object` | No | Maps event fields to workflow envelope. Templates: `{event.data.field}` |
+| `filter` | `object` | No | Shallow key-value match against `event.data` |
+| `execute_as` | `string` | No | Identity override for this subscription |
+| `enabled` | `boolean` | No | Default: `true` |
+
+**Response 201:** The created subscription.
+
+### Update subscription
+
+```
+PUT /api/agents/:agentId/subscriptions/:subId
+```
+
+Partial update.
+
+**Response 200:** The updated subscription.
+
+### Delete subscription
+
+```
+DELETE /api/agents/:agentId/subscriptions/:subId
+```
+
+**Response 200:** `{ "deleted": true }`

package/docs/api/sdk/agents.md

@@ -0,0 +1,138 @@
+# lt.agents
+
+Agent operations — create, configure, and manage autonomous event-driven agents.
+
+## list
+
+List agents with optional filters.
+
+```typescript
+const result = await lt.agents.list({ status: 'active', limit: 25 });
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `status` | `string` | No | Filter: `active`, `inactive`, `paused`, `error` |
+| `knowledge_domain` | `string` | No | Filter by knowledge domain |
+| `limit` | `number` | No | Max results (default: 50) |
+| `offset` | `number` | No | Pagination offset |
+
+**Returns:** `LTApiResult<{ agents: LTAgent[], total: number }>`
+
+Each agent includes `subscription_count` and `sub_topics[]` from a JOIN on `lt_agent_subscriptions`.
+
+## get
+
+Get a single agent with stats.
+
+```typescript
+const result = await lt.agents.get({ id: 'uuid' });
+```
+
+**Returns:** `LTApiResult<LTAgent & { stats: LTAgentStats }>`
+
+## create
+
+Create an agent.
+
+```typescript
+const result = await lt.agents.create({
+  name: 'health-monitor',
+  description: 'Watches for workflow failures',
+  goals: 'Detect failures early',
+  rules: 'Never auto-restart',
+  status: 'active',
+  knowledge_domain: 'system-health',
+  behaviors: {
+    schedules: [
+      { cron: '*/5 * * * *', workflow_type: 'basicEcho' },
+    ],
+  },
+});
+```
+
+**Returns:** `LTApiResult<LTAgent>`
+
+## update
+
+Partial update. Changing `status` or `behaviors` automatically restarts event subscriptions and cron schedules.
+
+```typescript
+await lt.agents.update({ id: 'uuid', status: 'paused' });
+```
+
+**Returns:** `LTApiResult<LTAgent>`
+
+## delete
+
+Delete an agent. Stops subscriptions and schedules. Knowledge and workflow history preserved.
+
+```typescript
+await lt.agents.delete({ id: 'uuid' });
+```
+
+**Returns:** `LTApiResult<{ deleted: true }>`
+
+## listSubscriptions
+
+List event subscriptions for an agent.
+
+```typescript
+const result = await lt.agents.listSubscriptions({ agentId: 'uuid' });
+```
+
+**Returns:** `LTApiResult<{ subscriptions: AgentSubscription[] }>`
+
+## createSubscription
+
+Create an event subscription.
+
+```typescript
+const result = await lt.agents.createSubscription({
+  agentId: 'uuid',
+  topic: 'workflow.failed',
+  reaction_type: 'durable',
+  workflow_type: 'basicEcho',
+  input_mapping: {
+    data: { error: '{event.status}', workflowId: '{event.workflowId}' },
+  },
+});
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agentId` | `string` | Yes | Agent ID |
+| `topic` | `string` | Yes | Event topic pattern (`*` = one token, `>` = rest) |
+| `reaction_type` | `string` | Yes | `durable`, `pipeline`, or `mcp_query` |
+| `workflow_type` | `string` | For durable | Workflow name |
+| `pipeline_id` | `string` | For pipeline | YAML workflow UUID |
+| `mcp_prompt` | `string` | For mcp_query | Query prompt |
+| `input_mapping` | `object` | No | Event-to-envelope field mapping |
+| `filter` | `object` | No | Shallow match against `event.data` |
+| `execute_as` | `string` | No | Identity override |
+
+**Returns:** `LTApiResult<AgentSubscription>`
+
+## updateSubscription
+
+Partial update of a subscription.
+
+```typescript
+await lt.agents.updateSubscription({
+  agentId: 'uuid',
+  subId: 'uuid',
+  topic: 'app.vendor.*.error',
+});
+```
+
+**Returns:** `LTApiResult<AgentSubscription>`
+
+## deleteSubscription
+
+Delete a subscription.
+
+```typescript
+await lt.agents.deleteSubscription({ agentId: 'uuid', subId: 'uuid' });
+```
+
+**Returns:** `LTApiResult<{ deleted: true }>`

package/docs/story.md

@@ -1,157 +1,180 @@
-# The Long Tail Story
+# Long Tail — The Story
 
-## Infrastructure That Learns
+## What It Feels Like
 
-Most software you deploy stays exactly as capable as the day you shipped it. It doesn't get smarter. It doesn't absorb what your team knows. It runs the same logic on day one thousand that it ran on day one.
+You open the dashboard. There's a quiet hum of activity — processes running, knowledge accumulating, agents doing their work. You didn't write most of this. You described what you needed. The system figured out how.
 
-Long Tail is different. Every problem solved through it becomes a permanent capability. The first time, an LLM reasons through it. A human reviews the result. The system compiles the solution into a deterministic tool. The next occurrence runs without AI, without human intervention, without cost. The tool inventory grows. The need for reasoning shrinks. The system gets cheaper and more capable simultaneously.
+A notification appears: your retirement account agent found a deadline. It read your Gmail, extracted the action item, organized the context in your knowledge store, and created a task for you with a link, a summary, and a phone number to call. You review, make the call, mark it done. The agent learns that this type of deadline requires a phone call and adjusts.
 
-This document walks through what happens when an organization adopts Long Tail, told from the perspective of what accumulates over time.
+Nobody wrote that workflow. Nobody will maintain it. It emerged from a conversation you had on a Tuesday afternoon, and it's been running every hour since.
 
 ---
 
-## The Starting Point
+## Three People, One Platform
 
-You have Postgres and a problem. Maybe it's content review, document processing, customer onboarding, incident response — any operational workflow where human judgment is currently the bottleneck.
+### Maya — Product Manager
 
-You install the package, point it at your database, and start it up. The system creates its schema, registers the built-in MCP servers, and opens the dashboard. Two container types from one codebase: API servers serve the dashboard and REST endpoints; workers execute workflows. Both read from Postgres.
+Maya doesn't write code. She writes requirements, talks to customers, and needs things to happen across systems she doesn't control.
 
-That's the entire infrastructure story. No message queues to configure. No object stores to provision. No separate orchestration service. Postgres is the durable execution engine, the tool registry, the escalation queue, and the audit log.
+**Her journey:**
 
----
+She opens the dashboard and types into the prompt bar: *"Check our support inbox every morning for emails mentioning 'cancellation'. Summarize each thread, tag the customer's sentiment, and create a task for the retention team with the full context."*
 
-## The First Tool
+The system discovers the capabilities it needs — Gmail search, thread summarization, sentiment analysis, knowledge storage, task creation. It runs the sequence dynamically, shows Maya the result. She adjusts: *"Include the customer's subscription tier from our database."* It re-runs, incorporating the schema exchange tool to query the customer API.
 
-The system ships with MCP servers for common capabilities: browser automation, file storage, document vision, database queries, HTTP requests. You can add your own — npm packages, remote services, custom TypeScript — and their tools immediately appear in the designer and compiler.
+Maya clicks **Compile**. The dynamic exploration becomes a deterministic pipeline — no AI in the loop, no token cost, sub-second execution. She schedules it for 7 AM daily. An agent is born.
 
-Open the MCP Tool Designer. Describe what you need in natural language:
+Two weeks later, the customer API changes a field name. The pipeline fails. The agent escalates to Maya's team. An engineer resolves it, the pipeline recompiles. Maya never knew it happened.
 
-> *"Screenshot every page in the admin panel and flag any that return errors."*
+**What Maya sees:** Agents, processes, escalations. She lives in outcomes.
 
-The system discovers the relevant tools across registered servers, plans the execution, and runs it. The browser server navigates pages. The vision server inspects screenshots. The file server stores results. Each step is a durable activity — if the process crashes mid-run, it resumes from the last completed step, not from the beginning.
+### Dev — Product Engineer
 
-The result lands in your dashboard: a structured output with screenshots, error flags, and metadata. It worked. But it cost tokens, took time, and required an LLM to reason through each step.
+Dev writes code when it makes sense and uses the platform when it's faster. He understands both worlds and moves between them.
 
-This is the dynamic path. It's powerful and flexible. It's also the most expensive way to run anything.
+**His journey:**
 
----
+Dev is building an integration with a new vendor. He registers a schema exchange endpoint — paste the API docs, define request/response schemas. The system creates a validated, self-testing MCP tool automatically.
 
-## The Compilation Moment
+He could write a durable workflow in TypeScript to orchestrate the vendor calls. Instead, he opens the pipeline builder and describes the sequence: authenticate → fetch orders → validate → store in knowledge → escalate anomalies. The builder compiles it to a deterministic YAML DAG.
 
-This is the pivot — the point where Long Tail stops being "an AI tool" and starts being infrastructure.
+But the anomaly detection logic is complex. Dev writes that as a proper activity function — tested, type-safe, version-controlled. He registers it alongside the compiled pipeline. The system doesn't care how the activity was authored. It's a pearl on the string either way.
 
-Open the compiler. It examines the execution trace from the dynamic run: which tools were called, in what order, with what arguments. It identifies what's dynamic (the URL, the credentials, the list of pages) versus what's fixed (the CSS selectors, the wait times, the error-detection logic). It produces a deterministic DAG — a directed acyclic graph that encodes the exact same workflow without any LLM reasoning.
+When Maya's agent needs the vendor data, it discovers Dev's tools and uses them. Maya's conversation-compiled pipeline calls Dev's hand-crafted activity. Neither knows about the other. The capability just exists.
 
-Deploy it. It's now a tool — tagged, versioned, invocable. It has typed inputs and outputs. It runs in milliseconds instead of seconds. It costs nothing in API tokens. And it's just as reliable as the dynamic version, because it was extracted from a successful execution, not written by hand.
+**What Dev sees:** Servers & tools, workflows, pipeline designer, execution traces. He lives in build mode but watches the outcomes.
 
-The compilation step is where operational knowledge crosses the boundary from tacit to executable. Before compilation, the knowledge of "how to screenshot admin pages and check for errors" lived in the LLM prompt and the human who wrote it. After compilation, it lives in the database as a versioned, deterministic tool that anyone — or any other workflow — can invoke.
+### Sam — Platform Engineer
 
----
+Sam owns the infrastructure. She thinks in terms of reliability, observability, and cost.
 
-## The Accumulation
+**Her journey:**
 
-Next week, someone describes a similar task. The router examines the request, searches the compiled tool registry by tags and capability descriptions, and finds a match. It extracts the parameters from the natural language request and routes directly to the compiled tool.
+Sam looks at the capabilities view — every activity the system can perform, sorted by usage, success rate, and cost. She sees that `gmail_search` is called 3,000 times a day across 12 agents. The dynamic path is used 0.2% of the time. 99.8% deterministic. Cost: near zero.
 
-No LLM. No tokens. Sub-second execution.
+She checks the knowledge store. Each agent has its own domain — clean isolation, no cross-contamination. The retirement agent has accumulated 847 entries over six weeks. The support monitoring agent has 12,000.
 
-The tool that was born from one person's request now serves the whole team. And it can be composed. Another workflow can call it as a step. The DAG that screenshots pages becomes an activity inside a larger workflow that audits, compares, and reports across environments.
+An alert fires: a compiled pipeline is failing at a 15% rate. Sam traces the execution timeline — swimlane view shows the `schema_exchange` step timing out. The vendor's API is degrading. She doesn't fix the code. She adjusts the retry policy and timeout on the workflow config. The pipeline adapts.
 
-This is the accumulation effect. Each compiled tool is both an endpoint and a building block. The library of tools grows monotonically — new compilations only add capabilities, never remove them. Workflows that compose multiple tools inherit the reliability and speed of each component.
+A new engineer joins. Sam points them to the boilerplate project: "Clone it, add your activities to `src/activities/`, register your MCP server in `src/mcp-servers/`, declare your workflow config in `start()`. Push. It deploys. The dashboard shows your tools immediately."
 
-Over time, the system develops a vocabulary of operations specific to your organization. Not generic "send HTTP request" primitives, but domain-specific tools like "audit staging environment" or "validate customer document against policy template." These are your operations, encoded in your database, reflecting your team's actual practices.
+**What Sam sees:** Task queues, execution metrics, knowledge usage, DB maintenance, agent health. She lives in the system view.
 
 ---
 
-## The Long Tail
+## The Surface
 
-The name comes from the distribution of problems.
+### Home: What's Alive
 
-Most operational tasks converge to patterns. After a month of use, the common paths — the head of the distribution — are compiled. Content reviews follow templates. Document processing has known formats. Onboarding flows have standard steps. These run deterministically, cheaply, instantly.
+The home page isn't a dashboard of charts. It's a **living view of work in motion**:
 
-What remains is the long tail: novel requests, edge cases, genuine unknowns. A document format nobody's seen before. An admin page with non-standard markup. A customer request that doesn't match any existing workflow.
+- Active processes — grouped by origin, showing progress through multi-step workflows
+- Recent escalations — what needs human attention right now
+- Agent activity — which agents ran, what they found, what they learned
 
-For these, the dynamic path still runs. The LLM reasons through the problem with the full tool inventory available. When it succeeds, the solution is a candidate for compilation. The tail gets shorter.
+No distinction between durable and compiled. No mention of YAML or TypeScript. Just: work happening, knowledge growing, agents running.
 
-When it fails — when the available tools can't solve the problem or the LLM's reasoning produces an incorrect result — the system escalates. RBAC-scoped chains route the problem to the right human based on the credentials, domain, and tool requirements involved. The human resolves it through the dashboard, with full context: what was attempted, what failed, and why.
+### Agents: Who's Working
 
-If the resolution reveals a repeatable pattern, it compiles too. The escalation itself becomes the training data for the next compiled tool.
+Each agent is a card:
 
-This is the dynamic the name describes: the long tail of problems that resist automation. Long Tail doesn't eliminate the tail. It systematically shortens it by converting each solved problem into a permanent, reusable capability.
+```
+┌─────────────────────────────────────────────┐
+│  📧 Retirement Monitor                      │
+│  Checks Gmail hourly for 401k updates       │
+│                                             │
+│  Last run: 12 minutes ago                   │
+│  Knowledge: 847 entries in `retirement`     │
+│  Escalations: 3 pending review              │
+│  Status: ● Active                           │
+│                                             │
+│  [View Knowledge]  [Execution Log]  [Edit]  │
+└─────────────────────────────────────────────┘
+```
 
----
+Click into an agent and see: its knowledge domain (browsable), its execution history (timeline), its escalation feed, its configuration. Everything an agent knows, everything it's done, everything it's waiting on.
 
-## What You Own
+**Creating an agent** is a conversation. The agent builder is the MCP query router with a purpose: instead of executing once, it compiles and schedules. The output is an agent, not a one-shot result.
 
-Long Tail runs on your Postgres. This isn't a philosophical stance about data sovereignty — it's an architectural consequence of using durable execution backed by a database you control.
+### Capabilities: What's Possible
 
-The compiled tools live in your database. The execution history lives in your database. The escalation patterns, the credential flows, the audit trail — all in your database. You can back it up, replicate it, query it with SQL, migrate it to another provider, or inspect it with any tool that speaks Postgres.
+A single searchable view of every activity — not grouped by server or workflow, but by **what it does**:
 
-When the system compiles a workflow, that compiled DAG is a row in a table you own. When a team member resolves an escalation, that resolution is recorded in a schema you can read. The institutional knowledge that accumulates over months of use — the specific ways your organization handles its specific problems — never leaves your infrastructure.
+```
+Communication
+  gmail_search · gmail_read · gmail_draft · send_sms · notify
 
-This matters for a practical reason beyond principle. Operational knowledge is one of the few genuine competitive advantages an organization has. The specific patterns of how your team reviews content, processes documents, responds to incidents — these reflect hard-won expertise. Infrastructure that captures and encodes that expertise should store it where you control access, retention, and usage.
+Analysis  
+  analyze_image · describe_image · translate · sentiment
 
-Two container types scale independently behind a load balancer. Add API servers for dashboard traffic. Add workers for execution throughput. Both connect to the same Postgres. There's no orchestration service to license, no execution platform to subscribe to, no vendor that accumulates your operational patterns as a side effect of providing the service.
+Data
+  store_knowledge · search_knowledge · schema_exchange · http_fetch
 
----
+Automation
+  escalate_and_wait · create_task · capture_page · run_script
+```
+
+Each capability shows who uses it: which agents, which pipelines, which workflows. Click one and see its schema, its compile hints, its execution history. This is the **institutional memory map** — it tells you what your organization has taught this system to do.
 
-## The Pluggable Platform
+### Build: How It Works
 
-MCP servers are the extension mechanism. Each server registers a set of tools with typed inputs, outputs, and descriptive metadata. The system uses this metadata for discovery — both by the LLM during dynamic execution and by the router during compiled tool matching.
+The engineering backstage. Everything that exists today, reorganized:
 
-The built-in servers cover common ground: browser automation for web interaction, file storage for document handling, vision for image analysis, database queries for structured data, HTTP for external API integration. But the real power is in what you add.
+- **Workflows** — durable TypeScript workflows, config, invocation, executions
+- **Pipelines** — compiled YAML DAGs, plan/build/compose, pipeline executions
+- **Servers & Tools** — MCP server registry, tool manifests, try-tool panel
+- **Designer** — the six-step compilation wizard
 
-Install an npm package that exposes an MCP server. Register it. Its tools are immediately available to the designer, the compiler, and the router. A server that wraps your internal API becomes a set of tools that workflows can compose. A server that connects to a third-party service extends the platform's reach without modifying any core code.
+Engineers move freely between these. They see execution traces, YAML DAGs, durable cycle replay, swimlane timelines. Nothing is hidden. The technical depth is the product.
 
-The LLM can even discover what's missing. If a dynamic execution fails because no available tool can perform a required step, the triage system surfaces the gap: "This workflow needs access to [capability] but no registered server provides it." Install the server, register the tools, and re-run. The platform grows in response to the problems it encounters.
+### Storage: What's Remembered
 
-Tags organize the tool space. Servers and tools carry tags that describe their domain and capabilities. The router uses tags to scope discovery — a database analytics query doesn't need to search browser automation tools. As the tool inventory grows, tags keep discovery focused and fast.
+- **Files** — drag-and-drop, signed URLs, image preview
+- **Knowledge** — domain browser, entry editor, JSON drop
+
+These aren't utilities. They're the **memory system**. When an agent stores extracted email data, it appears here. When a pipeline writes a screenshot, it appears here. The knowledge store is the agent's brain, browsable by anyone.
 
 ---
 
-## The Three Execution Tiers
+## The Event Spine
 
-Every request flows through a routing decision:
+Everything that happens publishes to NATS. Every workflow start, every activity completion, every escalation claim, every knowledge write, every agent run. The event feed at the bottom of the dashboard is a live window into this stream.
 
-**Deterministic.** A compiled tool matches the request. Parameters are extracted and the DAG executes directly. No LLM involved. Sub-second. Free.
+But the real power is **subscription**. An agent can trigger on any event:
 
-**Dynamic.** No compiled tool matches, but the available tools can likely solve the problem. The LLM reasons through the execution, calling tools as needed. Durable — survives crashes and restarts. Successful runs are candidates for compilation.
+- A new escalation is created → the triage agent evaluates whether AI can resolve it
+- A file is uploaded → the image analysis agent processes it
+- Knowledge is updated in domain X → the report generator agent recompiles
+- A pipeline fails → the health monitoring agent escalates
 
-**Escalation.** The dynamic path fails or the system determines it can't solve the problem autonomously. RBAC-scoped routing sends it to the right human with full context. The human resolves it through the dashboard. Resolutions that reveal patterns feed back into compilation.
+The event spine is NATS. Clean pub/sub. Topic-based routing. No polling. The dashboard's real-time updates come from the same pipe that agents use to trigger. **One event system for humans and machines.**
 
-The ratio shifts over time. Early on, most requests take the dynamic path. As compilations accumulate, more requests route deterministically. The escalation path handles a shrinking residual. The system is always getting cheaper and faster, with no manual optimization required.
+This is what makes the system feel alive. It's not cron-only (check every hour). It's reactive (respond when something happens). Agents that react are faster, cheaper, and more natural than agents that poll.
 
 ---
 
-## The Workflow Lifecycle
+## The Transition
 
-A workflow in Long Tail has a natural lifecycle:
+The beautiful thing about this system is that it doesn't require a "big bang." It's additive:
 
-**Born dynamic.** Someone describes a need. The LLM orchestrates tools to meet it. The execution is durable — each step is checkpointed in Postgres. If the worker crashes, it resumes from the last completed activity, not from scratch.
+**Week 1:** An engineer adds activities and a workflow. Old school. Works great.
 
-**Reviewed.** The result appears in the dashboard. A human confirms it's correct, flags issues, or provides corrections. This review step is optional but valuable — it's the quality gate that ensures compiled tools encode correct behavior.
+**Week 2:** Someone discovers the pipeline designer. Compiles a dynamic workflow into a tool. Faster, no tokens.
 
-**Compiled.** The successful execution trace is fed to the compiler. The compiler extracts the fixed structure, parameterizes the dynamic inputs, and produces a deterministic DAG. The DAG is deployed as a new tool with typed inputs, outputs, and tags.
+**Week 3:** A product manager creates their first agent from a conversation. It runs on a schedule.
 
-**Composed.** The compiled tool becomes available as an activity for other workflows. A tool that validates a single document can be composed into a workflow that processes a batch. A tool that checks a single page can be composed into a site-wide audit. Composition is how individual capabilities combine into organizational processes.
+**Week 4:** The agent's compiled pipeline uses the engineer's activities alongside AI-compiled ones. No one planned this composition. The capability graph grew organically.
 
-**Evolved.** When the domain changes — new document formats, new page layouts, new policies — the compiled tool may start failing. Failures route to escalation. The human resolution captures the new pattern. A new compilation encodes the updated behavior. The old version remains available for rollback.
+**Month 3:** The system has 40 compiled tools, 8 agents, and 3 active knowledge domains. 94% of executions are deterministic. Cost has dropped. Reliability has increased. The team has institutional memory encoded in executable tools that survive personnel changes.
 
-This lifecycle runs continuously. The system is always compiling, always accumulating, always refining. No migration projects. No "automation initiatives." Just a steady conversion of operational knowledge into executable tools.
+**Month 6:** A new team member asks: "How do we handle the Aetna prior-auth process?" The answer isn't a wiki page. It's a compiled pipeline they can run, inspect, and modify. The knowledge is alive.
 
 ---
 
-## What You're Really Building
-
-Long Tail isn't a workflow engine that happens to use AI. It's a **knowledge compiler** that uses workflows as the intermediate representation.
-
-The input is human expertise and LLM reasoning — the tacit operational knowledge of how your team solves problems. The output is deterministic, versioned, composable tools that run without either.
-
-Every organization has operational patterns that live in people's heads, in runbooks, in tribal knowledge, in the "ask Sarah, she knows how to handle that" moments. These patterns are valuable, fragile, and almost never systematically captured. When someone leaves, the knowledge leaves with them. When a team scales, the patterns dilute.
-
-Long Tail is the machine that extracts those patterns and makes them executable. Not by asking people to document their processes — that rarely works and the documentation immediately drifts from reality. Instead, by observing how problems are actually solved, compiling the successful patterns, and deploying them as tools that anyone can invoke.
+## The Name
 
-The LLM is scaffolding. It provides the initial reasoning capability that bridges the gap between "describe what you need" and "here's a working solution." But scaffolding is temporary by design. As compiled tools accumulate, the LLM handles less. The deterministic tools handle more. The system converges toward a state where the LLM is only needed for genuinely novel problems — the shrinking long tail.
+Long Tail — because it systematically shortens the tail. Every novel problem that gets solved compiles into a permanent capability. The tail of unsolved problems shrinks. The head of automated, reliable, institutional knowledge grows.
 
-The compiled tools are the building--the durable artifact. They're what remains after the LLM has done its work and moved on. They encode your organization's operational knowledge in a form that's versioned, testable, composable, and entirely under your control.
+What starts as "I need someone to check my email" becomes an agent that runs 24/7, learns from every interaction, escalates when uncertain, and evolves when the world changes.
 
-That's the Long Tail.
+That's the story. Activities are permanent. Agents compose them. Humans guide the evolution. The system accumulates.