Browser
The planned browser door — stable selectors, addressable URLs, a markdown view of every entity, and an llms.txt index
Mostly not built yet. apps/app currently serves an authenticated shell with Clerk sign-in and
sign-up, and no entity views. There is no /t/:id route, no markdown view of an entity, and no
/llms.txt on the product app. What follows is a proposed shape, taken from
spec/02-agent-interfaces.md.
One part of it does exist: this documentation site serves
/llms.txt and a markdown view of every page. That is described at the bottom.
Humans drive the browser, but agents also drive it over the Chrome DevTools Protocol when no API covers what they need. The design treats that second caller as legitimate rather than as abuse, and the rules below are what make it possible without scraping.
Planned location: apps/app.
Stable selectors
Every interactive element carries a data-testid that is semantic and stable across restyles.
An agent must never rely on a class name or on DOM position. Both change whenever someone touches
the styling, and neither carries meaning. A data-testid is a contract; a Tailwind class is an
implementation detail that happens to be visible.
This is a review gate: new UI elements without a stable data-testid are rejected in
the agent experience checklist.
Deterministic URLs
Every view is addressable and shareable.
/t/tsk_01J...
/projects/:slug?status=in_reviewNo state exists only in memory. If a human can see it, an agent can navigate straight to it, and a link to it can be posted in a comment and still work tomorrow.
Markdown view
Appending .md to any entity URL returns the same content as markdown.
/t/tsk_01J....mdAn agent reads that instead of parsing HTML. Parsing a rendered page for content the server already has in structured form is pure waste — of tokens, and of the agent's chance of getting it right.
/llms.txt
An index of the site for agents, at the web root.
Lists agents must enumerate
No infinite scroll. Cursor pagination with visible controls, matching the REST pagination rules.
Infinite scroll has no stopping condition an agent can detect and no way to resume from the middle. A cursor has both.
Optimistic UI must still surface rejection
The state machine is enforced server-side. When it refuses a write, the interface has to say so and roll the optimistic update back.
Never let an agent believe a write landed when the server refused it. An agent that trusts a stale optimistic render will report success, and a false success is worse than a failure — it is the one outcome nobody goes back to check.
What runs today: this site
The documentation site implements the agent-facing parts of this design already.
| Surface | What it returns |
|---|---|
/llms.txt | An index of every page: title, URL and description, grouped by section. |
/docs/<slug>.md | The full markdown of one page, with its frontmatter. |
/sitemap.md | A semantic overview of the documentation. |
Content negotiation works too: a request for a docs URL with Accept: text/markdown returns the
markdown rather than the HTML page. An agent reading these docs never has to parse the site.