CLAUDE.md

1# integrations — the framework-recipe registry (`caveman sdk` data)
2 
3Declarative routing recipes for AI SDKs/frameworks: each recipe is the one-line
4base-URL shape that points a framework at the byte-safe gateway, with `{{baseURL}}`
5(gateway origin) and `{{app}}` (the `/w/<app>` attribution slug) left as render-time
6templates. Recipes are DATA, not code — the collapse decision applied to app frameworks.
7 
8## Layout
9- `recipes/*.json` — one recipe per framework (12 today: openai-ts/py, anthropic-ts/py,
10  google-genai, vercel-ai-sdk, langchain, litellm, crewai, pydantic-ai, openai-agents, curl).
11  Fields: `id`, `display_name`, `lang` (`ts`/`python`/`bash`), `wire_protocol`, `note`, `code`.
12- `compile.mjs` — zero-dep build-time compiler: validates every recipe (fail-closed) and
13  emits `recipes.json` (published registry) + two EMBEDDED copies —
14  `../cli/src/recipes.generated.ts` (the CLI stays zero-runtime-dep) and
15  the web app's embedded copy (cloud may consume public data; the reverse import is forbidden).
16- `recipes.json` — generated; do not hand-edit.
17 
18## Conventions
19- **fail-closed**: an unknown `lang` or `wire_protocol` fails the compile — never a guessed
20  protocol (no-placeholder rule). Allowed protocols are the 4 the proxy speaks natively
21  (anthropic-messages · openai-chat · openai-responses · gemini-generatecontent) plus
22  `multi` for frameworks that fan out behind one config.
23- Output is deterministic (recipes sorted by id); re-running on unchanged input is a no-op.
24- Run from the CLI build/test: `node ../integrations/compile.mjs`. The generated files are
25  committed and must stay in sync — change a recipe and regenerate all three artifacts.
26 
27See ../../CLAUDE.md (root) · ../agents/CLAUDE.md (the agent twin) · ../cli/CLAUDE.md
28