@hotmeshio/long-tail 0.20.0 → 0.21.0

package/docs/design-principles.md

@@ -1,245 +0,0 @@
-# Design Principles
-
-The design system behind the dashboard and every generated x-lt-* form. One
-token vocabulary, one value discipline, one form doctrine — the built-in pages
-and the forms customers author render from the same rules.
-
----
-
-## 1. Tokens are the system
-
-Every color, size, radius, and spacing knob flows through a `--lt-*` CSS
-variable declared in `dashboard/src/styles/globals.css`. Nothing paints a raw
-hex. A registered stylesheet (`branding.customCss` / `branding.themes` in
-`start()`) can therefore restyle the entire product — including full dark
-themes — with zero source changes. Midnight is the standing proof: if a color
-escapes the token system, it glows in the dark.
-
-Deliberate exceptions, each carrying a stated constraint in code: the
-signature pad (the exported PNG is a document — ink on white), customer
-iframes (their HTML assumes a white canvas), OAuth brand marks, theme-picker
-swatches, and overlay scrims.
-
-## 2. Color — the value discipline
-
-Chroma is spent, not spread.
-
-- **Surfaces are near-neutral; lines carry the hue.** Hover fills and section
-  bands stay a whisper off-neutral, but the thin structure — borders,
-  dividers, outlines, field rules — carries a clear, light tint of the accent
-  so the frame reads as thematic. Chroma never lands on a large rectangle — a
-  colored slab makes every real accent invisible — but a hairline may glow.
-- **One elevation logic, both polarities.** The page carries the base wash
-  (a light theme tint by day, the deep shade at night); sections and sheets
-  are distinct surfaces on it (white paper by day, the deeper well at
-  night); fields are wells that step AWAY from their surface (darker than
-  white by day, lighter than the shade at night). Light is Midnight
-  inverted — never a flat white page with white sections.
-- **The accent appears in small doses**: links, buttons, checks, pills,
-  section labels, focus states. Because it is scarce, it reads as "act here."
-  Icon links follow the same rule in every theme: clickable glyphs (toolbar
-  icons, view toggles) render through the `.icon-link` recipe — muted accent
-  at rest, full accent on hover — never a neutral text tone, which reads as
-  a static mark.
-- **Dark themes are the same principle, inverted** — near-black neutral
-  surfaces, the identical accent discipline. Midnight is not a different
-  design; it is the same design at night.
-- **Status is information, not decoration.** Text-safe status tokens
-  (≥4.5:1) for words; brighter `-graphic` variants for dots, bars, and
-  charts (≥3:1).
-- **The focus fill is the one ambient accent moment** — entering a field
-  earns the tint.
-
-## 3. Text — black speaks, color acts
-
-- One neutral near-black ramp shared by every light theme: `#171717` body,
-  `#373737` labels, `#646464` helper, `#8C8C8C` low-emphasis meta. Labels are
-  never theme-colored — a tinted label is indistinguishable from a link.
-  If it's colored, it must be clickable.
-- **11px floor.** No informative text below `text-2xs`. Quaternary tone is
-  reserved for large or decorative text (≥3:1).
-- **Headings**: near-black (`#333333`), small caps, weight 300, generous
-  sizes — `heading-1` (2.125rem) / `heading-2` (1.5rem) / `heading-3`
-  (1.25rem). The size carries hierarchy; the light weight keeps it elegant.
-  Mono identifiers (role keys, workflow types, topics) stay code-styled,
-  never small-caps.
-
-## 4. Fields and controls
-
-- **One recipe** (`.field/.input/.select/.textarea`): white body, a light
-  accent-tinted border, soft radius (`--lt-radius-field`), border deepens to
-  accent and fill takes the theme tint on focus. Every field-like control uses
-  the recipe or the tokens — no bespoke field styling.
-- **Width follows content, capped by the measure:**
-  - Generated forms hold a readable measure (`max-w-form`, 56rem). A wide
-    monitor gets margin, never a 2000px input.
-  - Selects size to their content, floored at 16rem for presence — a
-    one-word choice never stretches across the page. The floor yields to
-    the cell (`min(16rem, 100%)`): CSS lets min-width beat max-width, so
-    a bare floor would overflow a narrow column.
-  - Number and date inputs hold a hand-sized width (12rem; datetimes
-    16rem) — fixed-length values never stretch to the measure.
-  - Text, textarea, email, and url fill their cell — prose-length content
-    deserves the measure.
-  - Widgets follow the same split. Prose surfaces (code editor, markdown,
-    rich text, uploads) fill the cell. The signature pad holds its natural
-    document proportion (25rem, the 400×150 export) — the PNG is the
-    artifact, and stretching the pad stretches the document.
-- **Decisions are never checkboxes.** A decision is an option list opening
-  on an explicit disabled **Choose…** placeholder, a Yes/No pair included.
-  The user picks; nothing is an implicit first option, and there is no way
-  back to unchosen unless the field declares `x-lt-nullable`.
-- Checkboxes exist only inside checklists and multi-selects, and as the
-  single confirmation box — confirmations of work, not choices.
-- **Item length and selection mode determine list geometry.**
-  Sentence-length require-all *rituals* read top-down, one per row — the
-  vertical stack is deliberate. Short pick-any *tags* (reasons, categories)
-  flow horizontally as selectable chips: thumb-sized pills that wrap,
-  selection in solid accent. Never stack six two-word items into six
-  full-width rows — endless y with an empty x is a dead layout.
-- **Required is marked, everywhere.** Every required input — text, select,
-  number, upload, checkbox, or checkbox group — carries the red asterisk at
-  its label. A require-all checklist is required by definition and marked
-  like the rest. Required or optional is never a guess.
-
-## 5. Layout — the canonical shell
-
-```
-┌──────────────── Header (full width) ────────────────┐
-│ left nav │        main viewport        │ right panel │
-└──────────────── EventFeed (full width) ─────────────┘
-```
-
-- Header and event-stream footer span the full width. The left nav and the
-  global right SlidePanel are flex siblings of the main viewport — content
-  narrows when either opens; nothing overlays it. Pages fill the right panel
-  via `useShellPanel()`. The DocsDrawer is the full-screen overlay for
-  markdown.
-- iPad (768–1366) is the floor target: page padding clamps down, the sidebar
-  auto-collapses below 1024, nothing depends on hover alone.
-- Structure comes from typography, whitespace, and divider lines — never
-  rounded-bordered cards, never gradient fades. Sections sit on a barely
-  sunken band with an accent left rule.
-
-## 6. The form doctrine
-
-The reference implementation is `examples/workflows/acme-stations` — mimic it.
-
-1. **Facts first, as a dictionary.** Read-only work-item facts render as a dense
-   label/value spec sheet (`x-lt-display: "dictionary"`), not form rows.
-2. **One explicit decision** gates the form. Until it is made the page shows
-   facts, the decision, nothing else — even sign-off waits.
-3. **Linear reveals.** Each outcome fades in exactly the section it needs
-   (`x-lt-showIf` value matches). The enter animation makes the
-   cause-and-effect visible in time: click Reject, watch the report arrive.
-4. **The left/right law.** Left and Right always render side by side, Left
-   first — as dictionary pairs (two-column dictionaries fill row by row, so
-   consecutive items share a row) and as inputs (`x-lt-column-group` pairs
-   them in one cell, the 2×2).
-5. **Checklists**: standard confirmations may arrive pre-checked
-   (formDefaults) — the standard is the default and the resolver unchecks
-   what isn't true. The work item's own custom work arrives unchecked; those
-   clicks are the record. `x-lt-require-all` guards completion.
-6. **Every input carries a `title` and one instructional `description`
-   line — no input goes without.** The anatomy is fixed and identical for
-   every input kind: label, instruction, control, in that order. The
-   anatomy is a declared column, never an accident of width — the label is
-   a block, so a narrow control (a number, a short select) can never ride
-   sideways beside it when the instruction line is absent. Inputs that
-   share a row carry instructions of similar length so their controls align
-   across the row; a bare input beside an instructed one is a consistency
-   defect, in both content and alignment. The WHY — reference tables,
-   consequences, vocabulary — lives in `x-lt-help` beside the form.
-7. **Sign-off last.** A short audit note with a live counter.
-8. Hidden conditional fields still submit their defaults; resolver contracts
-   treat empty as absent.
-
-## 7. Copy — the economist tone
-
-The escalation `description` is the detail page's title: a short noun
-phrase naming the artifact — "Final QA — ACME-1042 · wgt-8127" —
-never a sentence, never an instruction, never a status report.
-
-Say what to do. Speak to the actor, in the imperative, always: "Pick Reject
-to file a report" — never "Reject files a report." The system is never the
-subject of an instruction, and passive voice never appears. One line per
-instruction; consequences ride the same sentence ("Resolve — the widget moves
-on to assembly"). Reference tables over paragraphs. Never preachy, never
-motivational, never "you're the first human — do well." State what a thing is
-and does, never what it lacks.
-
-## 8. Motion
-
-Motion explains causality; it never decorates. Reveals fade in tied to the
-choice that caused them (200–300ms enter). Errors shake once and settle.
-Panels slide as flex siblings so content reflows rather than being covered.
-Nothing loops, nothing floats.
-
-## 9. Accessibility floors
-
-- Body and label text ≥4.5:1; large/meta text and graphics ≥3:1.
-- Every input is label-associated; errors and helpers ride
-  `aria-describedby`; the errors panel click-focuses the field
-  (`data-field-key` is a contract).
-- Disabled forms use `inert` — out of the tab order, not just grayed.
-- `color-scheme` follows the theme so native controls match the surface.
-
-## 10. Responsive — geometry follows the container
-
-1. **Geometry follows the container, not the viewport.** Side panels, the
-   facet drawer, and the nav rail narrow containers below any viewport
-   breakpoint — a `md:`/`lg:` variant on a content grid is a defect.
-   Viewport variants are lawful only in the shell frame (header, nav rail),
-   where the viewport is the container.
-2. **Thresholds are named container tokens** (tailwind `containers`):
-   `@dict-inline` 22rem · `@grp-cols` 26rem · `@form-cols` 34rem ·
-   `@filters` 72rem · `@dict-pairs` 38rem · `@table` 48rem. Components use
-   the names, never raw rem values. A fold threshold is sized for the
-   HEAVIEST content its component carries — escaping to the condensed
-   format early beats ever letting a bar wrap.
-3. **The dictionary reflow ladder** — the poster child. The same
-   label/value pairs render as: two pairs per row at `@dict-pairs`; one
-   label|value pair per row at `@dict-inline`; label stacked over value
-   below. Pairing order never changes across geometries.
-4. **A table row IS a dictionary.** Below `@table`, tables fold into dense
-   console-style cards — identity columns become the title line, the rest
-   fold into label/value pairs on the dictionary ladder. **Tables never
-   scroll horizontally** — master lists use `layout="fixed"` so a table
-   physically cannot outgrow its container. Fixed columns cut both ways:
-   **cell content never bleeds into a neighbor** — every cell clips
-   (`overflow-hidden` on the `td`) and every text-bearing pill or label
-   truncates with an ellipsis (`max-w-full` + `truncate`), carrying the
-   full value in `title` for hover reveal.
-5. **The column budget, disclosed both ways.** The floor set — identity,
-   owner, urgency, age — always renders. Enrichment columns (workflow,
-   metadata facets) return only when the table's container has room
-   (`showFrom: '@split' | '@wall'`); below that they fold into card pairs.
-   The list is a jumping-off spot: the ELK-style drill the whole product
-   surfaces.
-6. **Refining is a ROW gesture, never a cell tax.** Cells spend their full
-   width on data. One always-visible magnifier per row (or board card)
-   opens the refine dialog: the row's metadata-bound facts as full-width
-   touch rows, multi-select ANDing facets, with filter-in-role /
-   search-everywhere / add-to-filters actions. Per-cell icon pairs are a
-   defect — twelve columns × two icons starves every value into an
-   ellipsis. Hover-only affordances do not exist on the floor.
-7. **Disclosure order**: drop priority-3 columns, fold priority-2 into
-   pairs, keep priority-1 always.
-8. **Touch parity**: every hover-only affordance has a tap equivalent —
-   the iPad floor has no hover.
-9. **The header diet ladder** (below lg): mark-only logo, icon+count links,
-   secondary actions fold into the user menu, the nav rail becomes a
-   drawer behind a menu button.
-10. **Sticky elements are never containers** — `container-type` breaks
-   `position: sticky` on the same element; wrap the geometry element
-   instead.
-
-## 11. Never
-
-Raw hex in components. Chroma on large surfaces. Theme-colored labels.
-Text below 11px. Decisions as checkboxes. Implicit select defaults.
-Full-width one-word inputs. Tag lists stacked as rows. Unmarked required
-fields. Inputs without instruction lines. Passive voice or system-voice
-copy. Horizontal scroll. Viewport breakpoints on content grids. Cards and
-gradient fades. "Back to X" links. Polling. Preachy copy. Customer names —
-the showcase brand is always Acme.

package/docs/schema-exchange.md

@@ -1,173 +0,0 @@
-# Surfacing Any API
-
-## The Gap Between Plumbing and Domain
-
-Long Tail ships with built-in MCP servers. Browser automation for navigating web interfaces. File storage for persisting artifacts. Vision for analyzing images. Knowledge for accumulating structured state. An admin server for the platform to look inward — list its own workflows, manage its own configuration, query its own execution history.
-
-These are plumbing. They solve cross-cutting problems that every deployment shares. But they don't know anything about your domain. They don't know what Epic's FHIR API returns for a `ServiceRequest` resource. They don't know the shape of Stripe's charge response. They don't know that your internal inventory service returns `{ items: [...], cursor: string }` and paginates with cursor-based tokens.
-
-Traditionally, closing this gap meant writing an MCP server. Define the tools. Map each one to an API call. Handle serialization, error cases, pagination. Register the server. Tag it. Write compile hints so the builder knows how to wire it. A week of engineering per external service.
-
-The schema-exchange primitive eliminates that week.
-
----
-
-## The Principle: Endpoint + Schema
-
-The `exchange` tool doesn't know HTTP from Playwright. It knows three things: where to send data, what the data should look like going out, and what it should look like coming back.
-
-```
-endpoint:        where
-request_schema:  what leaves
-response_schema: what returns
-```
-
-Transport is an implementation detail. Today it's Node.js `fetch`. Tomorrow it could be a browser automation step that fills a form, submits, and scrapes the result. Or a gRPC call. Or a SOAP envelope. The consumer doesn't know and doesn't care.
-
-What the consumer gets is a contract. The request is validated before it leaves the system. The response is validated when it arrives. If either validation fails, the failure is structural and specific — "the response is missing the `resourceType` field" — not a vague 500 error three layers deep.
-
-This is the difference between a fetch call and a schema-driven exchange. A fetch call succeeds or fails. An exchange succeeds, fails, or *detects drift* — the call succeeded but the shape changed. That third state is what makes API integrations maintainable over time.
-
----
-
-## From Spec to Toolset
-
-Open the Pipeline Designer. Choose Build mode. Paste:
-
-```
-Stripe Charges API (base: https://api.stripe.com/v1)
-
-POST /charges
-  Headers: Authorization: Bearer {api_key}
-  Request: { amount: number, currency: string, source: string, description?: string }
-  Response: { id: string, amount: number, currency: string, status: string, created: number }
-
-GET /charges/{id}
-  Headers: Authorization: Bearer {api_key}
-  Response: { id: string, amount: number, currency: string, status: string, created: number }
-```
-
-The planner decomposes this into two leaf tools. The builder discovers the `exchange` tool in its inventory, reads the compile hints, and constructs each workflow:
-
-- **`create_charge`** — trigger accepts `api_key`, `amount`, `currency`, `source`. Worker calls `exchange` with the request schema embedded as a static value. Response schema validates the charge object. If Stripe changes the response shape, `validated` flips to `false` and the error names the exact field that changed.
-
-- **`get_charge`** — trigger accepts `api_key`, `charge_id`. Worker calls `exchange` with the charge ID interpolated into the URL. Response schema validates the same shape.
-
-Both deploy under a server namespace: `stripe`. They're compiled, versioned, invocable. They have typed inputs and outputs. They compose into larger workflows — a refund pipeline, an invoicing process, a reconciliation job.
-
-The engineer didn't write an MCP server. They didn't write any code. They pasted two endpoint descriptions and got two schema-validated tools that will catch API drift the moment Stripe changes a field.
-
----
-
-## Schema Drift: The Silent Killer
-
-APIs change. Fields get renamed. Required properties appear. Types shift from strings to objects. These changes are rarely announced in time, rarely caught by tests that don't run against live endpoints, and rarely surfaced until a downstream consumer produces wrong results.
-
-The response schema embedded in each compiled tool is a contract. It doesn't enforce — it detects. When the contract breaks, the tool reports exactly what changed:
-
-```
-response: (root): must have required property 'source' ({"missingProperty":"source"})
-```
-
-Not "API error." Not "unexpected response." The structural diff, in human-readable text, identifying the exact field.
-
-Schedule the tool on cron against a staging or dev endpoint. Every midnight, it calls the API and validates the response. If the schema matches, nothing happens. If it doesn't, the system knows before production does. The team fixes the tool, updates the schema, redeploys. No customer impact.
-
-This is what makes compiled API tools self-maintaining. The schema is both the integration logic and the regression test. They're the same artifact.
-
----
-
-## The Request Gate
-
-Schema enforcement works in both directions. The request schema validates outbound data before it leaves the system. If a caller passes `{ amount: "fifty" }` to `create_charge`, the exchange tool rejects it immediately:
-
-```
-request: /amount: must be number ({"type":"number"})
-```
-
-The request never hits Stripe. The error is instant, specific, and local. No network round-trip. No API rate limit consumed. No partial state created on the remote service.
-
-This matters in compiled workflows where one tool's output feeds another's input. A data-mapping error in step 3 of a 7-step pipeline is caught at step 3, not when Stripe returns a 400 in step 5. The failure is close to the cause.
-
----
-
-## Growing a Toolset
-
-The Pipeline Designer organizes tools into sets — collections of related tools that share a namespace and evolve together. You start with two Stripe endpoints. Next week you add `list_charges` and `create_refund`. The following month, `get_balance` and `list_payouts`.
-
-Each addition goes through the same flow: paste the spec, the planner builds the tool, it deploys into the existing namespace. The server version increments. All tools in the namespace are redeployed together. Active workflows don't stop — the new version activates atomically.
-
-The set is the workbench. It preserves the full specification history — every endpoint description that was pasted, in order. It's the source of truth for what the toolset covers and how it evolved.
-
-Over time, the set becomes a complete API surface. Not hand-written bindings. Not auto-generated client code that drifts from the spec. Compiled tools with embedded schemas that validate on every call.
-
----
-
-## Composition: Tools Built From Tools
-
-Individual API tools are building blocks. A compiled tool that calls `create_charge` can be composed with one that calls `get_customer` and one that calls `send_receipt`. The composition is itself a compiled tool — a pipeline that executes the three steps in sequence, wiring the charge ID from step 1 to the receipt in step 3.
-
-The schema exchange is invisible at the composition level. The composer sees tools with typed inputs and outputs. It doesn't know — or need to know — that these tools validate their data against schemas before every call. The validation is infrastructure, not application logic.
-
-This is where the Epic story begins. The FHIR endpoints are individual tools — `get_patient`, `search_coverage`, `create_task`. Each validates its request and response. Linda's intake process composes them into a pipeline that encodes her institutional knowledge: which checks to run, in what order, with what branching logic. The individual tools handle the API contract. The composition handles the business process. Neither knows about the other's concerns.
-
----
-
-## What This Replaces
-
-Without schema-driven exchange, wrapping an external API requires:
-
-1. Writing an MCP server (TypeScript, tool definitions, error handling)
-2. Registering it with the platform
-3. Writing compile hints so the builder knows how to use it
-4. Maintaining it when the API changes
-5. Repeating for every external service
-
-With schema-driven exchange, wrapping an external API requires:
-
-1. Pasting the endpoint specs into the Pipeline Designer
-
-The MCP server is the `exchange` tool. The compile hints are on the `exchange` tool. The schema validation is in the `exchange` tool. The only thing that changes per API is the spec the engineer pastes — the endpoints, the schemas, the auth pattern.
-
-This is what makes the Epic story practical. The engineering team doesn't spend a week writing a FHIR MCP server. They paste the endpoint descriptions and get compiled tools that speak FHIR with schema enforcement. The week they would have spent on plumbing is spent with Linda instead, capturing the institutional knowledge that makes the tools valuable.
-
----
-
-## The Reflexive Case
-
-Long Tail wraps its own API using the same primitive. The platform's REST endpoints — login, list servers, list workflows — are compiled tools in the `longtailapi` namespace. They validate their own response shapes. They detect drift in their own API surface.
-
-This isn't a special case. It's a proof point. The same `exchange` tool that wraps Epic's FHIR server wraps Long Tail's own REST API. The same schema enforcement that catches Stripe's field changes catches Long Tail's own field changes. The platform doesn't have a privileged self-knowledge path. It discovers its own capabilities the same way it discovers any external service — through endpoints and schemas.
-
-The admin server (`long-tail-admin`) still exists for operations that require internal access — managing workflows, modifying configuration, operations that go beyond data exchange. But for anything that's "call an endpoint, validate the response, return the data" — the schema exchange primitive is the universal answer. Internal or external. FHIR or REST. Stripe or self.
-
----
-
-## Identity: The Third Pillar
-
-Endpoint and schema handle the data contract. The third pillar — identity — handles who's calling.
-
-The `exchange` tool accepts an optional `credential_provider` field. When set, the tool resolves authentication from the platform's connection store using the calling principal's identity. No token input. No manual header wiring. No `get_access_token` step in the workflow.
-
-```
-credential_provider: "stripe"
-```
-
-That single field means: look up the calling user's Stripe credentials from the encrypted connection store, auto-refresh if expired, inject into the request headers. The credential never appears in the workflow state, the execution trace, or the YAML. It's resolved at the last mile — inside the tool execution, after the HotMesh event log has already been written.
-
-This is how the Epic story works in practice. The engineering team registers their SMART on FHIR credentials as a connection. Every compiled FHIR tool specifies `credential_provider: "epic"`. When the tool runs for Customer A, it gets Customer A's token. When it runs for Customer B, it gets Customer B's. Same compiled tool. Different identities. The routing is invisible.
-
-Three auth patterns, one tool:
-- **credential_provider** — resolve from the connection store. Fresh token, auto-refresh, per-principal. The default for production.
-- **Ephemeral references** — opaque `eph:v1:*` strings in headers, exchanged at the last mile. For workflows that need human-provided credentials with TTL.
-- **Raw headers** — pass `Authorization: Bearer {token}` directly. For testing, one-off calls, or systems where the caller manages tokens externally.
-
----
-
-## What Remains
-
-The schema-exchange tool is plumbing. It doesn't know about healthcare or payments or logistics. It knows about endpoints, schemas, identity, and whether the data matched.
-
-Everything above it — the domain knowledge, the business logic, the institutional expertise — comes from the people who use it. Linda's referral intake rules. Maria's document requirements. The Stripe integration team's charge flow. The ops team's self-monitoring pipeline.
-
-The platform's job is to make that knowledge executable, composable, and self-testing. The schema exchange is the foundation layer — endpoint, schema, identity. The three pillars that make "paste an API spec, get a validated tool with automatic auth" possible. Everything else builds on top of it. The tools are the building. The exchange is the foundation.

package/docs/self-test.md

@@ -1,106 +0,0 @@
-# The Self-Test: Long Tail Wraps Its Own API
-
-## The Tool That Wanted to Extend Itself
-
-Long Tail ships with a schema-exchange tool — a baseline capability for exchanging data with any external service under schema enforcement. The tool validates requests before sending and responses after receiving. It doesn't know HTTP from Playwright. It knows endpoints, schemas, and whether the data matched.
-
-This is the story of what happened when someone pointed that tool at Long Tail's own API.
-
----
-
-## The Starting Point
-
-Long Tail has a REST API. It has endpoints for authentication, for listing registered MCP servers, for querying compiled workflows. Every deployment uses these endpoints — the dashboard calls them, integrations call them, crons call them.
-
-But nobody had ever formalized what those endpoints return. The shapes were implicit — TypeScript interfaces in the codebase, but nothing the runtime could assert against. If a deployment changed a response shape, you found out when the dashboard broke. Or when a customer's integration broke. Or, worst case, you didn't find out at all because the consumer silently swallowed the new shape and produced wrong results downstream.
-
-The schema-exchange tool exists precisely for this problem. It doesn't care whether the endpoint is Epic's FHIR server or Long Tail's own API. The principle is the same: endpoint + schema + validated exchange.
-
----
-
-## Wrapping the API
-
-An engineer opens Plan Mode in the dashboard and pastes three endpoint specifications:
-
-```
-Long Tail API (base: http://localhost:3000/api)
-
-POST /auth/login
-  Request: { username: string, password: string }
-  Response: { token: string, user: { id: string, external_id: string, display_name: string, roles: [{ role: string, type: string }] } }
-
-GET /mcp/servers (requires Bearer token)
-  Response: { servers: [{ id: string, name: string, description: string, tags: string[], status: string, tool_manifest: [{ name: string, description: string }] }] }
-
-GET /yaml-workflows (requires Bearer token)
-  Response: { workflows: [{ id: string, name: string, app_id: string, status: string, graph_topic: string, tags: string[] }], total: number }
-```
-
-The planner decomposes this into three leaf workflows. The builder discovers the `exchange` tool in the inventory, reads the compile hints, and constructs each workflow as a trigger → exchange → output DAG with embedded schemas.
-
-All three deploy under a server namespace: `longtailapi`.
-
----
-
-## What the Compiled Tools Do
-
-**`login`** — Takes a username and password. Validates the request body (both strings, both required) against the request schema before sending. Calls POST /auth/login. Validates the response (must have `token` string and `user` object with required fields). Returns the token and user profile.
-
-If someone changes the login response — adds a field, removes `display_name`, changes `roles` from an array to a string — the schema validation catches it. `validated: false`, with a human-readable error explaining exactly what changed.
-
-**`list_servers`** — Takes a bearer token. Calls GET /mcp/servers. Validates the response (must be an object with a `servers` array, each server must have `id`, `name`, `tags`). Returns the server list.
-
-This tool can answer the question: "does the schema-exchange server exist?" If `long-tail-schema-exchange` isn't in the returned list, the tool that's asking the question knows its own infrastructure is broken. The snake eating its own tail.
-
-**`list_workflows`** — Takes a bearer token. Calls GET /yaml-workflows. Validates the response (must be an object with `workflows` array and `total` number). Returns the compiled tool inventory.
-
-This tool can check whether the `longtailapi` tools themselves are deployed and active. It can verify that the very workflows it belongs to are in the list. Self-referential validation — the compiled tool confirms its own existence.
-
----
-
-## The Composition: Self-Health-Check
-
-The three leaf tools compose into a single workflow: `self_health_check`.
-
-1. **Login** — authenticate with a service account
-2. **List servers** — verify all expected MCP servers are registered
-3. **List workflows** — verify all expected compiled tools are deployed
-
-Each step validates its response schema. If any step fails validation, the workflow knows exactly what changed — not "the API is down" but "the `servers` response is missing the `tags` field on server objects."
-
-Schedule it on cron. Every midnight, the platform checks its own API surface against the schemas it captured when the tools were compiled. Schema drift is caught within 24 hours, automatically, without a human looking at anything.
-
----
-
-## Why This Matters
-
-This isn't a testing framework. It's the same schema-exchange primitive that wraps Epic's FHIR endpoints or Stripe's payment API or any other external service. The fact that it can wrap Long Tail's own API is a proof point, not a special case.
-
-The proof point is:
-
-1. **Any API surface can be formalized as compiled tools.** Paste the endpoint specs. Get schema-validated, cron-testable tools. No MCP server to hand-write. No integration code. The schema is the integration.
-
-2. **Schema drift detection is automatic.** The response_schema embedded in each compiled tool is the contract. When the contract breaks, the tool reports exactly what changed. Not "500 error" — the actual structural diff.
-
-3. **The tools compose.** Login → use token → check servers → check workflows. Each step is independently testable, independently schedulable, independently versionable. But together they form a health check that validates the entire platform surface.
-
-4. **The platform can extend itself.** The schema-exchange tool is a baseline capability. The compiled API tools are built from it. The health check composes them. Every layer uses the same machinery. New endpoints are absorbed the same way — paste, compile, deploy, schedule.
-
-This is the starting point the Epic story describes: "The engineering team registers a custom MCP server that wraps the FHIR endpoints their referral workflows need." Except here, the engineering team is us, the FHIR endpoints are our own API, and the custom MCP server assembled itself from pasted specs and a schema-exchange primitive.
-
-The SOPs come next. But the plumbing works.
-
----
-
-## The Integration Test
-
-The file `tests/integration/schema-exchange.test.ts` proves this end-to-end:
-
-1. Calls `exchange` to login (POST /auth/login with request + response schema)
-2. Calls `exchange` to list servers (GET /mcp/servers with response schema)
-3. Asserts the schema-exchange server exists in the response
-4. Calls `exchange` to list workflows (GET /yaml-workflows with response schema)
-5. Deliberately uses a wrong schema to prove drift detection
-6. Deliberately sends a malformed request to prove pre-send rejection
-
-If any assertion fails, the schema-exchange tool isn't doing its job. If they all pass, the platform can wrap any API — including its own.