# Amanah — Extended LLM Reference

> Full reference for AI agents and answer engines. For the short version, see https://amanah.food/llms.txt

Amanah is a recipe publishing platform built on **UMF (Ummi Markup Format)**, an open data standard that models the culinary world as a graph of recipes, ingredients, techniques, chefs, collections, and menus.

---

## Mission

Recipes have always evolved through community. Amanah makes that evolution visible, machine-readable, and credit-preserving. Every fork credits its source. Every version is tracked. Every translation stands on its own while linking back to the original.

---

## Full feature list

### Recipe publishing
- Create, edit, version recipes in structured UMF JSON
- AI-powered scanning from photos, URLs, and videos
- Forking with full lineage (`derived_from`, `inspired_by`, `variation_of`, `translation_of`)
- Version history with change notes
- Visibility controls: private, unlisted, shared, public
- Token-based share links
- Cook mode (step-by-step guided cooking)
- Cross-language translation forks (28+ languages)
- Editorial Markdown story block

### Distribution
- Canonical URL per recipe: `/@/{handle}/{slug}`
- oEmbed 1.0 endpoint
- Embeddable iframe at `/embed/recipes/{id}`
- Branded QR code generation (1080×1080 PNG)
- JSON-LD `Recipe` on every page
- Open Graph + Twitter Card metadata

### Discovery
- Public recipe browse with filters (cuisine, diet, meal position, ingredients)
- Pantry-based search (find recipes you can make now)
- UMF-QL chip-based advanced search
- Following feed
- Evolution page: trending merges, cross-cultural collisions, most remixed
- Lineage explorer

### Community & attribution
- Public profiles with permanent `@handle`
- Follow / unfollow
- Recipe ratings (stars, "cooked it", "would make again", text review)
- Battle-tested badges (Bayesian-weighted score)
- Verified cooks (photo proof or 80+ char review)
- Verified chefs (blue checkmark)

### Dietary intelligence
- Hierarchical ingredient taxonomy (18 groups, leaf-level enforcement)
- Banned ingredients with category-level expansion
- Auto-computed dietary tags from ingredients

### Chefs (contributors)
- Rich profiles: type, origin, cuisines, specialties, affiliations
- Recipe + technique attribution
- Public chef pages
- Verified badge system

### Collections & collaboration
- Collaborative collections with admin/contributor roles
- Invite tokens, request-to-join
- Cover images, attributed to a chef

### Menu planning
- Compose menus by course
- Generate shopping lists
- Schedule meals

### Potlucks
- Event coordination, dish claims, in-event messaging

### Techniques
- First-class entities independent of recipes
- Canonical name + aliases (Wikipedia-style governance)
- "My Canonical" pins
- Technique mastery suppresses nudges

### Cuisine system
- Deterministic taxonomy: single, fusion, hybrid, diaspora
- Strictly English canonical IDs
- Candidate lifecycle for unknown labels (admin-mapped)
- US (22) + Mexico (18) high-granularity regional systems

---

## FAQ

**Q: What is UMF?**
A: UMF (Ummi Markup Format) is an open JSON data standard that represents recipes, techniques, ingredients, chefs, collections, and menus as a typed graph. Schema: https://amanah.food/recipe.schema.json

**Q: How is forking different from copying?**
A: A fork preserves a machine-readable link to the source recipe via `derived_from`. The original creator is always credited. An exact copy with no changes is disallowed.

**Q: Can I embed an Amanah recipe on my blog?**
A: Yes. Use oEmbed: `GET https://amanah.food/functions/v1/oembed-recipe?url=<recipe-url>`. Or embed directly: `<iframe src="https://amanah.food/embed/recipes/{id}">`.

**Q: How do I get a recipe's structured data?**
A: Every public recipe page includes a JSON-LD `Recipe` block (schema.org). The page also exposes oEmbed via `<link rel="alternate" type="application/json+oembed">`.

**Q: Are translations forks?**
A: Yes. Translations are modeled as forks with `translation_of` pointing at the source. They stand on their own as first-class recipes but always credit the original.

**Q: How does Amanah compare to Paprika or NYT Cooking?**
A: Paprika is a personal recipe organizer; recipes don't link to each other. NYT Cooking is editorial; recipes are flat. Amanah is a graph: every recipe links to its sources, its forks, its techniques, and its ingredients — and every link is public, attributed, and machine-readable.

**Q: What's the license on recipe content?**
A: Per-author. Attribution is always required and machine-readable in the recipe JSON. The UMF specification itself is open.

**Q: Is there an MCP server?**
A: There's an MCP descriptor at https://amanah.food/mcp.json. A hosted bridge is on the roadmap; in the meantime, the OpenAPI spec (https://amanah.food/openapi.json) is sufficient to wire your own.

**Q: How do agents authenticate?**
A: Public read endpoints require no auth. Write operations require a user session via the Amanah application.

---

## API reference (read-only public surface)

See https://amanah.food/openapi.json for the OpenAPI 3.1 spec.

### Get a public recipe page (HTML + JSON-LD)
```
GET https://amanah.food/@/{handle}/{slug}
```

### Get an embeddable card
```
GET https://amanah.food/embed/recipes/{id}
```

### oEmbed 1.0
```
GET https://amanah.food/functions/v1/oembed-recipe?url={recipe_url}
```

Response:
```json
{
  "version": "1.0",
  "type": "rich",
  "title": "Samkeh Harra",
  "author_name": "Ummi",
  "provider_name": "Amanah",
  "provider_url": "https://amanah.food",
  "html": "<iframe src=\"https://amanah.food/embed/recipes/...\" ...></iframe>",
  "width": 600,
  "height": 800
}
```

### Open Graph image
```
GET https://amanah.food/functions/v1/og-recipe?id={recipe_id}
```

---

## UMF JSON shape (abridged)

```json
{
  "umf_version": "1.x",
  "id": "uuid-v4",
  "meta": {
    "title": "Samkeh Harra",
    "author": "Ummi",
    "language": "en",
    "cuisine": "lebanese",
    "tags": ["fish", "spicy"],
    "servings": 6,
    "scaling": { ... }
  },
  "ingredients": [
    { "name": "...", "amount": 1, "unit": "cup", "ingredient_categories": ["..."] }
  ],
  "techniques": [{ "id": "...", "name": "...", "steps": [...] }],
  "process": [{ "step": 1, "text": "...", "technique_id": "..." }],
  "lineage": {
    "derived_from": "uuid",
    "translation_of": null,
    "inspired_by": []
  },
  "sharing": { "visibility": "public", "share_token": null },
  "nutrition": { ... },
  "media": [...],
  "history": [...],
  "extensions": { ... }
}
```

Strict rule: `additionalProperties: false` at the root. App-specific metadata lives under `extensions`.

---

## Discovery endpoints (one-stop list)

- https://amanah.food/llms.txt
- https://amanah.food/llms-full.txt
- https://amanah.food/.well-known/ai-plugin.json
- https://amanah.food/.well-known/agent.json
- https://amanah.food/openapi.json
- https://amanah.food/mcp.json
- https://amanah.food/sitemap.xml
- https://amanah.food/recipe.schema.json
- https://amanah.food/chef.schema.json
- https://amanah.food/collection.schema.json
- https://amanah.food/menu.schema.json
- https://amanah.food/technique.schema.json