{
  "id": "2026-05-07-codex-recipe-factory-d47a050348",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-05-07-codex-recipe-factory.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.737Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "Codex Recipe Factory Standard",
  "summary": "Codex Recipe Factory Standard Date: 2026 05 07 Purpose The Recipe Factory is the repeatable pattern for turning a Bezel capability into something a fresh Codex session can build from one URL. The standard exists because Personal Brain proved the core motion: Codex read the public recipe, built a local Next.js app, connected it to the hosted Bezel Projects Su...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Codex Recipe Factory Standard",
      "level": 1,
      "body": "Date: 2026-05-07"
    },
    {
      "title": "Purpose",
      "level": 2,
      "body": "The Recipe Factory is the repeatable pattern for turning a Bezel capability into something a fresh Codex session can build from one URL.\n\nThe standard exists because Personal Brain proved the core motion:\n\n```text\nBuild this: https://recipes.bezeliq.ai/personal-brain\n```\n\nCodex read the public recipe, built a local Next.js app, connected it to the hosted Bezel Projects Supabase sandbox, ran build/smoke checks, and returned a working localhost URL."
    },
    {
      "title": "Thesis",
      "level": 2,
      "body": "A recipe URL is a product interface for agents.\n\nA GitHub repo is still useful underneath, but a repo is a builder/developer interface. A recipe URL is what a first-time Codex user, buyer, teammate, or customer can paste into an agent and expect a working capability."
    },
    {
      "title": "Definition",
      "level": 2,
      "body": "A Codex recipe is a URL-addressable capability packet with:\n\n- a human landing page\n- a machine-readable manifest\n- Codex-specific instructions\n- app/API/data/acceptance specs\n- demo inputs when useful\n- troubleshooting notes\n- successful-run evidence\n\nThe canonical host is:\n\n```text\nhttps://recipes.bezeliq.ai/{recipe-slug}\n```"
    },
    {
      "title": "Standard Packet Shape",
      "level": 2,
      "body": "```text\nrecipes/{recipe-id}/\n  recipe.json\n  START_HERE.md\n  codex-instructions.md\n  app-spec/\n    screens.md\n    data-model.md\n    api.md\n    acceptance.md\n  demo/\n    sample-input.json\n  troubleshooting.md\n  future/\n```\n\nThe public URL should expose:\n\n```text\nhttps://recipes.bezeliq.ai/{recipe-slug}\nhttps://recipes.bezeliq.ai/{recipe-slug}/recipe.json\nhttps://recipes.bezeliq.ai/{recipe-slug}/START_HERE.md\nhttps://recipes.bezeliq.ai/{recipe-slug}/codex-instructions.md\n```"
    },
    {
      "title": "Build Process",
      "level": 2,
      "body": "For each new project or capability:\n\n1. Define the capability in plain English.\n2. Choose the golden path for a first-time Codex user.\n3. Decide whether V1 is hosted, private, or local-only.\n4. Write the recipe packet.\n5. Publish it under `recipes.bezeliq.ai`.\n6. Start a fresh Codex session.\n7. Paste only the recipe URL prompt.\n8. Let Codex build the local app or workflow.\n9. Run mechanical verification.\n10. Save the actual successful run as evidence.\n11. Harden the recipe until repeated runs converge."
    },
    {
      "title": "Acceptance Rule",
      "level": 2,
      "body": "A recipe is not considered real until a fresh Codex session can build it from:\n\n```text\nBuild this: https://recipes.bezeliq.ai/{recipe-slug}\n```\n\nwith minimal help.\n\nMinimal help means no extra architecture explanation, no hidden setup steps, and no credentials unless the recipe is explicitly a private-account recipe."
    },
    {
      "title": "Hosted V1 Boundary",
      "level": 2,
      "body": "Hosted V1 exists to remove setup friction.\n\nRules:\n\n- generated apps must not receive service role keys\n- generated apps must not ask for Supabase credentials when the recipe says hosted V1\n- generated apps should talk to a Bezel-hosted API boundary\n- user install tokens should stay server-side when the generated app stack supports it\n- hosted V1 must be clearly labeled as demo/early setup unless privacy/export/deletion terms are published\n\nPersonal Brain follows this model through the Bezel Projects Supabase database and `personal-brain-api`."
    },
    {
      "title": "Evidence Standard",
      "level": 2,
      "body": "Every recipe needs a successful-run note.\n\nCapture:\n\n- prompt used\n- app URL or output location\n- generated screens/flows\n- hosted/private storage mode\n- checks passed\n- warnings/advisories\n- hardening actions\n\nThis evidence is part of the product, not an afterthought. It proves the URL can produce working software in a fresh agent context."
    },
    {
      "title": "Current Reference Implementation",
      "level": 2,
      "body": "Repository:\n\n```text\n/Users/justinking/Vaults/Projects/bezel-recipes\n```\n\nRecipe:\n\n```text\nhttps://recipes.bezeliq.ai/personal-brain\n```\n\nKey implementation facts:\n\n- Cloudflare Pages project: `bezel-recipes`\n- Custom domain: `recipes.bezeliq.ai`\n- Static build script: `scripts/build-site.mjs`\n- First recipe: `recipes/personal-brain-supabase`\n- Successful-run evidence: `docs/successful-runs/personal-brain-2026-05-07.md`"
    },
    {
      "title": "Next Capability Candidates",
      "level": 2,
      "body": "Use this same factory for:\n\n- Gmail/calendar triage\n- AI-first task extraction\n- project setup wizards\n- AD product modules\n- future Personal Brain private Supabase and Obsidian modes\n\nThe next recipe should not start from scratch. It should start from the playbook in `bezel-recipes/docs/recipe-authoring-playbook.md`."
    }
  ],
  "html_path": "artifacts/2026-05-07-codex-recipe-factory-d47a050348.html",
  "json_path": "artifacts/2026-05-07-codex-recipe-factory-d47a050348.json"
}