# 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.

> [!info]
> **Example output.** Claude Code ran the *Design review page* recipe on 30 September 2026 for an open question in the recipes handoff. It read `lib/agentSetup.ts`, `lib/export/markdown.ts` and the public page route before writing. Brad accepted the recommendation the same day.

## 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 |

```mermaid
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"| M
```

*Option C: one published document, two forms. Agent setup links the recipes index, so a new agent can find a recipe before it is connected.*

## Risks

- [ ] 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.

<!-- onecell:block {"date":"2026-09-30","type":"decision","title":"Serve published public documents as Markdown at /p/<slug>.md","status":"accepted","context":"Agents need to fetch recipes before they are connected to onecell, and recipes should have one source, the cell.","decision":"Add a route that serves any published, public document as Markdown at /p/<slug>.md, using the existing documentToMarkdown and the public page's visibility check. Publish the recipes, and link the Start here page from agent-setup/prompt.md.","consequences":"Every public document gains an agent-readable form. Recipes stay editable in onecell only. The route needs a test that private and draft documents return 404."} -->
**Decision: Serve published public documents as Markdown at /p/<slug>.md** (accepted, 2026-09-30, by blondon)
**Context:** Agents need to fetch recipes before they are connected to onecell, and recipes should have one source, the cell.
**Decision:** Add a route that serves any published, public document as Markdown at /p/<slug>.md, using the existing documentToMarkdown and the public page's visibility check. Publish the recipes, and link the Start here page from agent-setup/prompt.md.
**Consequences:** Every public document gains an agent-readable form. Recipes stay editable in onecell only. The route needs a test that private and draft documents return 404.

## 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.