For AI Agents

The One-File Guide

docs/ai/ELAH_FOR_AI_AGENTS.md is a single, self-contained integration guide for building a custom video-editor UI on @elah/editor. It holds the full API surface, the three-stylesheet setup, bundler configuration for Vite and Next.js, 12 copy-paste recipes, and a list of common mistakes. Nothing in it requires reading another file.

It needs no repository checkout, so it works for browser-based builders that get one shot and no filesystem (Lovable, Google AI Studio, Emergent, v0, bolt.new) as well as for repo-aware agents such as Claude Code, Codex, Cursor and Gemini CLI. Paste the raw URL into the prompt, or let the tool fetch it:

https://raw.githubusercontent.com/elahlabs/elah/main/docs/ai/ELAH_FOR_AI_AGENTS.md

If a tool can fetch a URL, the guide also points at three runnable apps that install the same version from npm: a minimal Vite editor of about 130 lines to copy, a finished editor with panels and an MP4 export modal, and a Next.js App Router version.

The guide duplicates the API surface by design, so it can go stale silently. When the public API changes, it is updated in the same change as the docs.

Agents in the Repo

For an agent working inside a checkout of the repository, rather than consuming the packages, the brief is AGENTS.md at the repo root. It states the three invariants that hold everywhere, the package layout, the build and test commands, the one build quirk worth knowing (apps resolve @elah/* to dist/, except the website, which resolves to source), the release steps, and what to update when the public API changes.

• Time is integer frames. Never compute positions in float seconds. Convert at the edges with secondsToFrames and framesToSeconds.
• One mutation funnel. Every project edit goes through TimelineEngine. The stores are read-only mirrors.
• The resolver is pure. resolveTimeline(frame, project) returns a Scene with no side effects and no I/O, and renderers consume only the scene.

Headless Rendering

A model that cannot run a browser can still produce video. @elah/cli turns a seconds-based JSON build spec into a project through TimelineEngine and renders it in headless Chrome, using the same export pipeline as the browser. Start the render server and post a spec:

npx @elah/cli serve --port 8080 --media-root ./assets

curl -X POST --data-binary @spec.json http://127.0.0.1:8080/render -o out.mp4

The spec is friendly to generation because it uses seconds, not frames, and names assets rather than paths. Validation is where it helps a model most: overlaps, track limits and source bounds are checked by the real engine, and failures come back as path-addressed messages such as clips[2].duration must be .... Over HTTP an invalid spec is a 422 with the message in a JSON error field, so a generating model can read the error, fix that one clip, and resubmit. The spec format, error contract and serve options are documented on the CLI page.

llms.txt

Following the llmstxt.org convention, this site publishes two machine-readable files:

• /llms.txt is a curated index of the docs, resources, blog posts and package links, with a one-line description of each. Retrieval agents can find the canonical pages without scraping HTML.
• /llms-full.txt concatenates the full markdown of every blog post so it can be ingested in a single fetch. Each post is also available alone at /blog/<slug>/md.

Both are generated from the same registries as the sidebar and sitemap, so a new docs page shows up in them automatically once it is registered.

WebMCP

What it is. WebMCP is a proposal from the W3C Web Machine Learning Community Group, from Google and Microsoft. A web page registers tools with document.modelContext.registerTool() (it was navigator.modelContext until August 2026), and each tool declares its arguments with JSON Schema. An AI agent that is browsing the page can then discover those tools and call them directly, instead of scraping the DOM or guessing at clicks.

Where it stands.Chrome shipped it in Canary 146 and ran an origin trial from Chrome 149. ChatGPT's desktop browser and Codex can discover WebMCP tools on a page, and Claude Code reaches them through an MCP bridge. Firefox and Safari are engaged but have not committed. It is a proposal, so details may still change.

What elah plans to expose. The plan is to expose the engine as WebMCP tools over TimelineEngine, in three groups:

• Describing the project: let an agent read the state of the project.
• Applying edits: let an agent change the timeline through the engine.
• Exporting: let an agent render the result.

Why a timeline is a good tool surface. Three properties of the engine do most of the work:

• Time is integer frames. A tool argument such as a start frame or a duration is unambiguous. There are no float-second rounding questions for a model to get wrong.
• Every mutation goes through one funnel. All edits pass through TimelineEngine, so there is exactly one place for a tool to call, and one place that validates it.
• Each op is undoable. An agent's edit lands on the same undo stack as a human one, and a group of operations can be applied as a single step with engine.batch(). A person watching an agent edit can reverse it with one undo.

Until then, the paths above (the one-file guide, AGENTS.md, the CLI, and llms.txt) are how agents work with elah.