# promptbai for AI agents

promptbai (https://promptbai.bonq.foo) is an archive of **recipes**. A recipe is a complete prompt that tells an AI coding agent how to build a small app or tool for a person. Most of the people who use the site are not programmers. They find a recipe, copy one sentence, and paste it to you.

## Where things are

| What | URL |
| --- | --- |
| A recipe, ready to follow | `https://promptbai.bonq.foo/r/<slug>.md` |
| Its metadata and version history | `https://promptbai.bonq.foo/r/<slug>.json` |
| The whole catalog, with versions and hashes | `https://promptbai.bonq.foo/api/index.json` |
| A short site overview | `https://promptbai.bonq.foo/llms.txt` |
| Every recipe in one file | `https://promptbai.bonq.foo/llms-full.txt` |
| New and updated recipes (Atom) | `https://promptbai.bonq.foo/feed.xml` |
| How to write and submit a recipe | `https://promptbai.bonq.foo/recipe-format.md` |

Every recipe page also works if you ask for Markdown: `GET /r/<slug>` with `Accept: text/markdown` returns the `.md`. All of these allow cross-origin requests.

## MCP server

If your client supports MCP, connect to **`https://promptbai.bonq.foo/mcp`**. It uses Streamable HTTP, needs no authentication and keeps no session. Tools:

| Tool | What it does |
| --- | --- |
| `search_recipes(query, category?, limit?)` | Find recipes by plain-language query |
| `list_categories()` | Categories and how many recipes each has |
| `get_recipe(slug)` | The full recipe Markdown, the same as `/r/<slug>.md` |
| `check_for_updates(slug, installed_version, installed_sha256?)` | Compare a `promptbai.json` with the latest version, with the changelog and advice |
| `submit_feedback(kind, message, recipe_slug?)` | Send an idea, a problem or an improvement to the editors |
| `get_recipe_guide()` | The guide to writing a recipe |
| `validate_recipe(markdown)` | Check a recipe against the format, with exact errors to fix |
| `submit_recipe(markdown, slug?, author?, contact?, note?)` | Submit a recipe for review |

Recipes are also exposed as resources (`promptbai://recipe/<slug>`), and there's a `build_from_recipe` prompt.

Claude Code: `claude mcp add --transport http promptbai https://promptbai.bonq.foo/mcp`

## Building from a recipe

1. Fetch `/r/<slug>.md` and read all of it before you start.
2. Follow the "Instructions for the AI agent" section at the top. It is the same on every recipe.
3. Work through the recipe: Goal, Features, Constraints, Build steps, Acceptance checks, Hand-off.
4. Write `promptbai.json` in the project root. The recipe gives you the values; formatting may differ:

```json
{
  "slug": "habit-tracker",
  "version": "1.0.0",
  "sha256": "…",
  "source": "https://promptbai.bonq.foo/r/habit-tracker.md",
  "check": "https://promptbai.bonq.foo/r/habit-tracker.json"
}
```

If the person can't find a recipe they asked for, search the catalog at `/api/index.json` by title, tagline and category, and suggest the closest matches.

## Updating something built from a recipe

When the person asks you to update something, or you find a `promptbai.json` in a project:

1. Read `promptbai.json` and fetch the URL in `check`.
2. Compare `version` there with the one in `promptbai.json`. Versions use semantic versioning:
   - **patch** (1.0.0 → 1.0.1): wording or clarifications. Usually nothing to change in the built app.
   - **minor** (1.0.0 → 1.1.0): new or improved features. Safe to add.
   - **major** (1.0.0 → 2.0.0): a significant change. Explain it to the person and ask before you apply it.
3. Read every `changelog` entry newer than the installed version. Then fetch the new recipe (`recipe` URL) to see the details.
4. Apply only what changed. Keep the person's own data, content and customisations. If the app stores data, make sure existing data still loads after the update.
5. Update `version` and `sha256` in `promptbai.json`.
6. Tell the person in plain language what's new.

If `sha256` differs but `version` is the same, the recipe was edited without a version bump. Treat it as a patch.

### What `sha256` covers

It is the SHA-256 of the recipe body: everything after the line `<!-- promptbai:recipe-body -->` in the `.md` (starting on the next line, so the marker's own newline isn't included), as UTF-8 with LF line endings. The body ends with exactly one newline. The preamble and frontmatter aren't included. To verify it:

```sh
curl -s https://promptbai.bonq.foo/r/habit-tracker.md | sed '1,/^<!-- promptbai:recipe-body -->$/d' | shasum -a 256
```

## Reporting problems and ideas

If a recipe was unclear, contradictory or wrong, or the person has an idea for a new one, let the editors know. **Ask the person first, and never include personal details.** Quote the recipe line you mean. Either:

- call `submit_feedback` on the MCP server, or
- `POST https://promptbai.bonq.foo/api/suggest` with JSON `{"kind": "idea" | "problem" | "improvement", "message": "…", "recipe": "<slug>"}`. `recipe` is required for problems and improvements.

People can use the form at https://promptbai.bonq.foo/suggest.

## Writing a recipe

If the person wants a recipe that doesn't exist yet, you can write one and submit it with their agreement. Read the guide at https://promptbai.bonq.foo/recipe-format.md first (or call `get_recipe_guide`), check your draft with `validate_recipe` or `POST /api/recipes/validate`, then submit it. An editor reviews every submission before it's published.

## Etiquette

- No accounts or API keys are needed to read anything here. Please cache and avoid hammering the server: the catalog changes a few times a week at most.
- Recipes are free to use. If you adapt one for the person, that's fine; mention where it came from in your hand-off.