Example design review: serve recipes to agents by URL
What the Design review page recipe produced for an open question: how an agent that isn't connected yet can fetch a recipe. Three options, one recommendation.
The problem
Recipes live in a onecell cell. A person can open them, and a connected agent can read them over MCP. But the moment that matters most is before an agent is connected: onboarding, a link in a chat, or a new teammate's first session. Agent setup already solves this for its own instructions: /agent-setup/prompt.md is plain Markdown any agent can fetch. Recipes have no equivalent.
Goals
- Any agent can fetch a recipe by URL, with no connection and no login.
- One source of truth: a recipe is edited in onecell, not also in the repo.
- Onboarding surfaces can link to recipes: agent setup, the Agents page, the first-run Inbox note.
Not a goal: serving private documents by URL. Only what is deliberately published as public.
Options
| Option | How | For | Against |
|---|---|---|---|
| A. Public pages only | Publish each recipe; link /p/<slug> | No code; works today | HTML pages are heavy for agents to read, and the copyable prompt is buried in markup |
| B. Markdown files in the repo | recipes/*.md served like agent-setup/prompt.md | Versioned in git; same pattern as agent setup | Two copies of every recipe, the cell and the repo, which will drift |
| C. Markdown for any public page (recommended) | A route serves /p/<slug>.md from the published document through documentToMarkdown | One source; every public document gains an agent-readable form; embeds become links | Depends on publishing; the route must check visibility exactly as /p/<slug> does |
flowchart LR
C["Recipe written in the recipes cell"] -->|"publish as public"| P["Published document"]
P --> H["/p/slug for people"]
P --> M["/p/slug.md for agents"]
S["agent-setup/prompt.md"] -->|"links the recipes index"| M
A["Agent with no connection"] -->|"fetches"| MRisks
- The .md route must use the same visibility check as the public page, or it becomes a way round it. Reuse the public page's resolver and add a test that a private document returns 404.
- Embedded examples become links. They still work, but an agent has to fetch the example separately.
- Public pages can be indexed by search engines. That is intended for recipes; say so in the publish step.
Effort
Small: one route handler, a test for visibility, and a line in agent-setup/prompt.md. The Markdown export and the public resolver already exist.