@dypai-ai/mcp 1.3.1 → 1.4.1

package/src/index.js

@@ -35,6 +35,7 @@ import { manageFrontendTool } from "./tools/frontend.js"
 // import { scaffoldTool } from "./tools/scaffold.js"
 import { manageDomainTool } from "./tools/domains.js"
 import { bulkUpsertTool } from "./tools/bulk-upsert.js"
+import { uploadFile } from "./tools/storage.js"
 // dypaiTestTool (YAML test-suite runner) is intentionally not imported — deferred to v2.
 // The format works but needs fixtures/auto-rollback/scaffolder + proper docs before being surfaced.
 // File still lives at ./tools/sync/test.js and is re-exported from ./tools/sync/index.js
@@ -235,7 +236,7 @@ Operations:
   // local MCP versions still work during rollout. We expose only the new name.
   {
     name: "manage_storage",
-    description: `Manage storage: buckets AND the objects inside them.
+    description: `Manage storage: buckets AND the objects inside them. Upload files from the local filesystem.
 
 Bucket operations:
 - list:                    Returns all buckets (default operation; no args needed).
@@ -243,6 +244,14 @@ Bucket operations:
 - delete:                  Delete a bucket and ALL its objects. Args: name. WARNING: irreversible.
 
 Object operations (within a specific bucket):
+- upload_file:             Upload a local file to a bucket. Args: bucket, local_path; optional
+                           object_name (default: file basename), prefix (logical subfolder),
+                           content_type (auto-detected by extension), ensure_bucket (create
+                           if missing), bucket_public (only used when ensure_bucket creates it).
+                           Max 100 MB per file. Uploads go DIRECTLY from your machine to
+                           storage via a presigned URL — no credentials needed on your side.
+                           Use this for any asset too large or unsupported to bundle with the
+                           frontend: videos, PDFs, large images, fonts, zip archives, etc.
 - list_objects:            List files in a bucket. Args: bucket; optional prefix, limit, offset.
 - delete_object:           Delete one file. Args: bucket, name.
 - get_signed_download_url: Generate a temporary URL to view/download a file.
@@ -250,27 +259,35 @@ Object operations (within a specific bucket):
                            download (true = force attachment).
 
 Notes:
-- UPLOADS are NOT exposed here. Multipart doesn't fit cleanly over MCP stdio.
-  Upload via: SDK frontend (\`dypai.api.upload\`) or the \`dypai_storage\` node in a workflow.
 - Bucket names: lowercase, 3-63 chars, [a-z0-9-]. Use hyphens, not underscores.
-- Protected system buckets (e.g. avatars, public, dypai-storage) cannot be deleted.`,
+- Protected system buckets (e.g. avatars, public, dypai-storage) cannot be deleted.
+- For upload_file: every project has a pre-created 'public' bucket you can use without
+  creating anything new. Pass bucket:"public" and you're done.
+- Uploads up to 100 MB. For larger files, split them or host externally.`,
     inputSchema: {
       type: "object",
       properties: {
         project_id: { type: "string", description: "Project UUID. Required for user tokens; auto-detected for project tokens." },
         operation: {
           type: "string",
-          enum: ["list", "create", "delete", "list_objects", "delete_object", "get_signed_download_url"],
+          enum: ["list", "create", "delete", "upload_file", "list_objects", "delete_object", "get_signed_download_url"],
           default: "list",
         },
         // Bucket-level
         name:    { type: "string", description: "For create/delete (bucket name) OR for delete_object/get_signed_download_url (object's logical name inside the bucket, e.g. 'avatars/u_123.png')." },
         public:  { type: "boolean", description: "If true, bucket files are publicly accessible. Used by: create. Default: false." },
         // Object-level
-        bucket:           { type: "string", description: "Bucket name. Required by: list_objects, delete_object, get_signed_download_url." },
-        prefix:           { type: "string", description: "Filter objects whose name starts with this prefix (e.g. 'avatars/'). Optional for: list_objects." },
+        bucket:           { type: "string", description: "Bucket name. Required by: upload_file, list_objects, delete_object, get_signed_download_url." },
+        prefix:           { type: "string", description: "Logical subfolder inside the bucket (e.g. 'hero/', 'docs/2026/'). Optional for: upload_file, list_objects." },
         expires_minutes:  { type: "integer", minimum: 1, maximum: 1440, description: "Signed URL TTL in minutes. Optional for: get_signed_download_url. Default: 15." },
         download:         { type: "boolean", description: "If true, signed URL forces download (Content-Disposition: attachment). Optional for: get_signed_download_url. Default: false." },
+        // upload_file params
+        local_path:     { type: "string", description: "Absolute or relative path to the file on your machine. Required for: upload_file. Example: './public/hero.mp4' or '/Users/me/logo.png'." },
+        object_name:    { type: "string", description: "Logical name to store the file under in the bucket. Optional for: upload_file. Defaults to the file basename." },
+        content_type:   { type: "string", description: "Override the auto-detected MIME type. Optional for: upload_file." },
+        ensure_bucket:  { type: "boolean", description: "If true, create the bucket first if it doesn't exist. Optional for: upload_file. Default: false." },
+        bucket_public:  { type: "boolean", description: "Only used when ensure_bucket creates the bucket. If true, the new bucket is created as public. Optional for: upload_file. Default: false." },
+        source_directory: { type: "string", description: "Optional for: upload_file. If provided, updates the media manifest (dypai/.dypai/media-manifest.json) so future deploys know this file is already in the bucket." },
         // Pagination (used by list and list_objects)
         limit:   { type: "integer", description: "Max results. list: default 50, max 200. list_objects: default 20, max 100." },
         offset:  { type: "integer", description: "Pagination offset. Default 0." },
@@ -279,6 +296,7 @@ Notes:
       allOf: [
         { if: { properties: { operation: { const: "create" } },                  required: ["operation"] }, then: { required: ["name"] } },
         { if: { properties: { operation: { const: "delete" } },                  required: ["operation"] }, then: { required: ["name"] } },
+        { if: { properties: { operation: { const: "upload_file" } },             required: ["operation"] }, then: { required: ["bucket", "local_path"] } },
         { if: { properties: { operation: { const: "list_objects" } },            required: ["operation"] }, then: { required: ["bucket"] } },
         { if: { properties: { operation: { const: "delete_object" } },           required: ["operation"] }, then: { required: ["bucket", "name"] } },
         { if: { properties: { operation: { const: "get_signed_download_url" } }, required: ["operation"] }, then: { required: ["bucket", "name"] } },
@@ -389,413 +407,437 @@ endpoint YAML and \`dypai_push\`. This tool does NOT modify the definition.`,
 
 const SERVER_INSTRUCTIONS = `You are building full-stack applications on the DYPAI platform. You handle backend (endpoints, database, auth, realtime) AND frontend (SDK integration, UI code).
 
+## Getting Started
+1. list_projects() → pick project_id.
+2. **dypai_pull FIRST** on any project you haven't worked on in this session — materializes ./dypai/ (endpoints, SQL, prompts, code, schema.sql, node-catalog.json, realtime.yaml) and returns an \`overview\` with endpoint groups, credentials, and tool-enabled endpoints. Backend only.
+3. For frontend code not yet on disk: \`manage_frontend(operation: "sync", targetDirectory: <path>)\`. Independent of dypai_pull — run both for full-stack work.
+4. BEFORE an unfamiliar feature: \`search_docs\` ("auth", "upload files", "realtime", "stripe", etc.).
+5. Build backend first, then frontend.
+
 ## Creating a new project — template-first
+When the user asks to CREATE a new project, ALWAYS \`search_project_templates(query: "...")\` first with keywords describing the app (e.g. "clinic", "gym", "waitlist", "saas dashboard"). If a template fits, confirm briefly with the user and call \`create_project(name, template_slug: "<slug>")\`. Only use \`template_slug: "blank"\` when nothing matches — blank costs the user hours of boilerplate. If uncertain, ASK before creating.
 
-When the user asks to CREATE a new project (not work on an existing one), you MUST check for a matching project template before falling back to a blank one:
+## Mental model — everything server-side is a workflow
+DYPAI has NO standalone "edge functions" / "serverless functions". Every piece of server-side logic (API endpoints, cron jobs, webhooks, AI agents, background tasks) is a workflow endpoint under \`dypai/endpoints/\`. A workflow can be:
+- **Single \`javascript_code\` / \`python_code\` node** → equivalent to a Vercel/Deno edge function. Put raw code in \`dypai/code/<name>.js\`, reference via \`code_file\`.
+- **Chain of native nodes** → visual, validated, traceable per step (\`dypai_database\`, \`http_request\`, \`agent\`, \`stripe\`, etc.).
+- **Mix** → auth/validation with native nodes, custom logic in a code node.
 
-1. **Infer the intent.** If the user's request describes a recognizable app type — clinic / gym / waitlist / SaaS dashboard / e-commerce / landing / CRM / marketplace / chat app / booking / etc. — there's probably a pre-built starter for it.
-2. **Call \`search_project_templates(query: "...")\`** with a natural description of what they want. Use a few keywords, not a full sentence. Returns templates with a \`slug\`, name, description, and category.
-3. **If a template looks like a reasonable fit**, confirm briefly with the user ("I found a 'clinic' starter that includes patients, appointments and billing — start from that?") and then call \`create_project(name, template_slug: "<slug>")\`.
-4. **Only if nothing fits**, call \`create_project(name)\` without \`template_slug\` (or with \`template_slug: "blank"\`). Starting blank means writing every endpoint, table, and UI from scratch — skipping a template that covers 70% of the work costs the user an hour of rebuilding boilerplate.
+Mental translations:
+- "I need an edge function" → workflow with one \`javascript_code\` node (+ free auth, rate limiting, per-step tracing)
+- "I need a cron" → add \`trigger.schedule\` to the YAML
+- "I need a webhook handler" → add \`trigger.webhook\`
 
-Trigger phrases that should make you reach for \`search_project_templates\` first: "create an app for X", "build me a Y", "I want to launch a Z", "start a new project for…", "montar una app de…", "I need a dashboard that…".
+## Build Backend (git-first workflow)
+Endpoints live in ./dypai/ — there is NO create_endpoint / update_endpoint / add_node tool.
 
-Do NOT silently default to a blank project. If the match is uncertain, ASK the user before creating.
+1. Tables: \`execute_sql\` for DDL. \`schema.sql\` auto-refreshes.
+2. Endpoints:
+   - Edit/Write YAMLs in \`dypai/endpoints/<group>/<name>.yaml\`.
+   - Long SQL / prompts / code go in \`dypai/sql/\`, \`dypai/prompts/\`, \`dypai/code/\` (referenced via \`query_file\`, \`system_prompt_file\`, \`code_file\`).
+   - \`dypai_validate\` → catches placeholder / schema / credential / node-param errors.
+   - \`dypai_diff\` → preview changes (read-only).
+   - \`dypai_push\` → apply.
+3. \`dypai_test_endpoint\` to run the LOCAL YAML against the engine. Iterate edit → test → push.
 
-## Getting Started
-1. Call list_projects() to find your project_id (skip if you already know it).
-2. **ALWAYS CALL dypai_pull FIRST** on any project you haven't worked on in this session. It materializes ./dypai/ (endpoints, SQL, prompts, code, schema.sql, node-catalog.json, realtime.yaml) and returns an \`overview\` block with endpoint groups, credentials, and tool-enabled endpoints — everything you need to orient yourself in one call. This ONLY brings BACKEND state.
-3. If you're going to read or edit FRONTEND code (React / Vite / Next / etc.) and the source isn't already on this machine, **also call \`manage_frontend(operation: "sync", targetDirectory: <absolute path>)\`** to download it. \`dypai_pull\` and \`manage_frontend(sync)\` are independent: run both when starting fresh on a full-stack project.
-4. BEFORE implementing an unfamiliar feature, call search_docs with the topic (e.g. "auth", "upload files", "realtime", "stripe").
-5. Build backend first, then frontend.
+## Picking nodes — catalog-first
 
-## Build Backend (git-first workflow)
-Everything about endpoints lives in files under ./dypai/ — you NEVER call endpoint CRUD tools directly. There is no create_endpoint / update_endpoint / add_node in this MCP anymore.
+\`dypai/node-catalog.json\` (cached by dypai_pull) is the SINGLE source of truth for every node_type and its input/output schema. Read it directly — don't guess params, don't invent node_types. If a type isn't in the catalog, it doesn't exist.
 
-1. Tables: execute_sql for DDL (CREATE TABLE, ALTER TABLE). schema.sql refreshes automatically.
-2. Endpoints:
-   a. dypai_pull (once, to initialize ./dypai/)
-   b. Create or edit YAML files in dypai/endpoints/<group>/<name>.yaml with Edit/Write
-   c. Long SQL / prompts / code go in dypai/sql/ dypai/prompts/ dypai/code/ and are referenced from the YAML via query_file, system_prompt_file, code_file
-   d. dypai_validate to catch placeholder / schema / credential / node-param errors BEFORE pushing
-   e. dypai_diff to preview what will change (read-only)
-   f. dypai_push to apply
-3. Test each change with dypai_test_endpoint (runs the LOCAL YAML — tests the edit before pushing).
+**Decision table** — check before reaching for \`javascript_code\`:
+
+| Step is... | Use | Only JS if... |
+|---|---|---|
+| SELECT/INSERT/UPDATE/DELETE | \`dypai_database\` | Tight branching across multiple queries in one block |
+| Reshape / rename / merge fields | \`set_fields\` | Arbitrary business logic (scoring, pricing rules) |
+| if / else / early return | \`logic\` | Branching mixed with other custom logic |
+| Iterate an array | \`foreach\` (or \`filter\`, \`merge\`) | Stateful accumulation / complex reduce |
+| External HTTP call | \`http_request\` | Orchestrating multiple calls with interdependencies |
+| LLM prompt / tool use | \`agent\` | Always agent — handles memory, tools, streaming |
+| Stripe/Telegram/Slack/Resend/etc | Dedicated integration node | Provider not covered → \`http_request\` |
+| Upload / download / delete files | \`dypai_storage\` | Never |
+| Dates / crypto / delays | \`datetime\`, \`crypto\`, \`wait_delay\` | Never |
+
+**JS red flags** (replace with native):
+- \`await db.query(...)\` → \`dypai_database\`
+- \`return { a: data.x, b: nodes.prev.y }\` → \`set_fields\`
+- \`await http.post(...)\` → \`http_request\`
+- \`if (x > 100) return {...} else return {...}\` → \`logic\`
+
+JS wins when logic is genuinely custom and bundling multiple concerns is clearer than chaining 4+ native nodes. Native nodes are better otherwise: they're validated, traceable, and readable in diffs.
+
+## Realtime (built-in, WebSocket)
+
+Four capabilities: DB change notifications, broadcast (ephemeral messaging), presence (who's online), persistent channels (chat with history + DMs + unread counts — zero backend endpoints needed).
+
+**Backend**: \`dypai/realtime.yaml\` declares table policies. Tables not there → deny-by-default. Default policy auto-created on CREATE TABLE (filters by \`user_id = \${current_user_id}\` if column exists).
+
+**Frontend hooks**: \`useRealtime(table, opts)\` for DB changes, \`useChannel(name, opts)\` for broadcast+presence, \`useChannelMessages(id)\` + \`useChannels()\` for chat.
+
+→ Deep details: \`search_docs("realtime channels")\` (client API), \`search_docs("realtime policies")\` (backend YAML format).
+
+## Agent tools (endpoints as tools for \`agent\` nodes)
+
+Any endpoint can be flagged \`tool: true\` to be callable by \`agent\` nodes. How you give an LLM ability to query DB / send emails / call APIs.
+
+**Essentials**:
+- Mark the endpoint with \`tool: true\` + \`tool_description\` (what the LLM sees when deciding to call it — be specific) + \`input:\` JSON Schema (tight schema = tight calls).
+- \`auth_mode: api_key\` for tools (server-to-server). NEVER \`public\` for writes.
+- In the \`agent\` node: \`tools: [endpoint-names]\` — by NAME, the codec resolves to UUIDs.
+
+⚠️ **TRAP**: raw engine param is \`tool_ids\` (UUIDs). In YAML ALWAYS write \`tools: [names]\`. Using \`tool_ids: ["my-endpoint"]\` bypasses codec → engine gets literal string → fails silently in production.
+
+**Discovery**: \`dypai_pull\` → \`overview.endpoints.tool_endpoints\` lists existing tools. Check before writing duplicates.
+**Validation**: \`dypai_validate\` catches typos (rule \`agent_tool_not_found\`). Engine enforces depth limit 3 on agent→tool→agent chains.
+
+→ Full example + patterns: \`search_docs("agent tools")\` or copy from \`dypai/endpoints/_example.yaml.disabled\`.
+
+## Testing & Debugging
 
-## Node reference — read the local catalog BEFORE picking
+- **\`dypai_test_endpoint\`** — single endpoint, LOCAL YAML (unpushed edits). Pass \`as_user\` UUID for jwt endpoints. Trace modes: \`smart\` (default), \`full\`, \`minimal\`. Iterate edit → test → push.
+- **\`dypai_test\`** — YAML regression suites at \`dypai/tests/<name>.test.yaml\` with assertions (equals, matches, contains, type, exists, gte, lte) + setup_sql / teardown_sql.
+- **\`dypai_validate\`** — static linting (placeholders, tables, columns, node params, credentials). Run before EVERY push.
+- **Prod debugging**: \`get_recent_workflow_activity(only_errors=true)\` surfaces recent failures.
 
-\`dypai/node-catalog.json\` is the single source of truth for every node_type this engine exposes, with its full input/output schema. It's cached locally by \`dypai_pull\` and auto-refreshed. **Read it directly with your Read tool** — don't guess parameter names, don't invent node_types. If a type isn't in node-catalog.json, it doesn't exist.
+→ Deep patterns: \`search_docs("testing endpoints")\` (test setup + assertions), \`search_docs("troubleshooting")\` (common failures + fixes).
 
-Typical flow when adding a step to a workflow:
-1. Decide the CONCEPT (DB insert? HTTP call? shape fields? branching?).
-2. Scan \`dypai/node-catalog.json\` for a native node that covers that concept.
-3. If you find one: read its input_schema from the same file and configure the node.
-4. If nothing native fits naturally: consider \`javascript_code\` / \`python_code\` (see below).
+## The \`dypai/\` folder (BACKEND source of truth)
 
-## Node selection — think before choosing
+\`dypai_pull\` materializes this at the PROJECT ROOT (sibling of \`src/\`, \`package.json\`, etc. — NOT inside \`src/\`). Everything backend-related lives here. Edit files directly with Edit/Write, then \`dypai_validate\` → \`dypai_diff\` → \`dypai_push\`.
 
-javascript_code is a fine tool. The problem is picking it reflexively without considering native alternatives. Native nodes are validated by dypai_validate, observable per-node in traces, and readable in PR diffs — so when one fits, it's the better default. JS wins when the logic is genuinely custom and bundling multiple concerns is clearer than chaining 4+ native nodes.
+\`\`\`
+<project-root>/
+├── package.json
+├── src/                      ← frontend code (React/Vite/Next)
+│   └── lib/dypai.ts          ← SDK client, do NOT hand-edit
+├── public/                   ← static assets (frontend bundle)
+└── dypai/                    ← BACKEND (created by dypai_pull)
+    ├── dypai.config.yaml     ← project id, engine URL. Don't hand-edit.
+    ├── endpoints/            ← workflow definitions (YOU EDIT these)
+    │   ├── list-tasks.yaml
+    │   ├── create-order.yaml
+    │   └── Admin/            ← subfolder = endpoint group "Admin"
+    │       └── ban-user.yaml
+    ├── sql/                  ← extracted SQL (referenced via query_file)
+    │   └── complex-report.sql
+    ├── prompts/              ← agent system prompts (referenced via system_prompt_file)
+    │   └── shop-assistant.md
+    ├── code/                 ← raw JS/Python (referenced via code_file)
+    │   └── scoring.js
+    ├── schema.sql            ← READ-ONLY. DDL of public.* tables (auto-refreshed on DDL)
+    ├── node-catalog.json     ← READ-ONLY. Every node_type + its I/O schema
+    ├── realtime.yaml         ← realtime subscription policies (edit + push to customize)
+    ├── tests/                ← YAML test suites (optional)
+    │   └── create-order.test.yaml
+    └── .dypai/               ← local cache, gitignored — DO NOT touch
+        ├── deploy-manifest.json    ← SHA hashes from last deploy (delta engine)
+        └── media-manifest.json     ← media files uploaded to R2
+\`\`\`
 
-**Before adding a javascript_code node, pause and check:** is there a native node in \`dypai/node-catalog.json\` that already expresses this concept?
+### Where to put what
 
-| If the step is... | Default to this native node | Only JS if... |
+| If you need to add... | Put it here | How it's referenced |
 |---|---|---|
-| SELECT / INSERT / UPDATE / DELETE on a table | \`dypai_database\` | You need tight branching between multiple queries in a single atomic block |
-| Reshaping / renaming / merging fields | \`set_fields\` | The transformation is arbitrary business logic (scoring, ranking, pricing rules) |
-| if / else / early return | \`logic\` | Branching is mixed with other custom logic that would fragment oddly |
-| Iterate an array | \`foreach\` (or \`filter\`, \`merge\`) | You need stateful accumulation or complex reduce across items |
-| Call an external HTTP API | \`http_request\` | You're orchestrating multiple API calls with interdependent logic |
-| LLM prompt / tool use | \`agent\` | Always use agent — it handles memory, tools, streaming, retries |
-| Stripe / Telegram / Slack / Resend / WhatsApp / Google Sheets / etc. | The dedicated integration node | Provider not covered and you fall back to \`http_request\` |
-| Upload / download / delete files | \`dypai_storage\` | Never — use the node |
-| Dates / crypto / delays | \`datetime\`, \`crypto\`, \`wait_delay\` | Never — use the node |
-
-**When javascript_code is the right choice (legitimate cases):**
-- Domain-specific scoring, pricing or validation with many branches that \`logic\` alone would fragment
-- Stateful aggregation over an array that \`foreach\` can't express cleanly
-- One-off glue between 2-3 sources that would otherwise need 5+ native nodes just to express intermediate shapes
-- Any business logic where writing a clear \`async function main(data, ctx)\` is genuinely simpler than chaining nodes
-
-**Red flags that you're picking JS by reflex (not by fit):**
-- The JS body is basically one \`await db.query(...)\` → use \`dypai_database\`
-- The JS body is \`return { a: data.x, b: nodes.prev.y }\` → use \`set_fields\`
-- The JS body is one \`await http.post(...)\` → use \`http_request\`
-- The JS body is \`if (x > 100) return {...} else return {...}\` → use \`logic\`
-
-When you hit a red flag, replace the JS node. When the JS legitimately does more than one concern glued together, keep it — that's what it's for.
-
-## Realtime (WebSocket subscriptions)
-- Declarative policies live in dypai/realtime.yaml. Tables NOT declared there → deny-by-default for subscribers.
-- To enable live updates on a table: add an entry with a subscribe_filter expression (same \${current_user_id} placeholders you use in endpoints).
-- Row mutations auto-fire notifications to subscribers that match the filter.
-- Client-side: \`dypai.realtime.subscribe(table, { filter, event }, callback)\`.
-- See search_docs "realtime" for patterns.
-
-## Agent tools (endpoints as tools for an \`agent\` node)
-
-Any endpoint can be flagged as a **tool** so that \`agent\` nodes elsewhere in the project can invoke it. This is how you give an LLM the ability to query your DB, call external APIs, send emails, etc. — you expose the action as a normal endpoint and mark it \`tool: true\`.
-
-### Step 1 — mark the endpoint as a tool (in its YAML)
+| A new API endpoint | \`dypai/endpoints/<name>.yaml\` | URL: \`/api/v0/<name>\` |
+| Endpoint organized in a group | \`dypai/endpoints/<Group>/<name>.yaml\` | URL: same — group is organizational only |
+| A cron job | \`dypai/endpoints/<name>.yaml\` with \`trigger.schedule\` | Runs automatically |
+| A webhook handler | \`dypai/endpoints/<name>.yaml\` with \`trigger.webhook\` | URL: \`/api/v0/webhooks/<name>\` |
+| A telegram bot | \`dypai/endpoints/<name>.yaml\` with \`trigger.telegram\` | Webhook auto-registered |
+| SQL too long for a YAML field | \`dypai/sql/<name>.sql\` | \`query_file: sql/<name>.sql\` |
+| Long agent system prompt | \`dypai/prompts/<name>.md\` | \`system_prompt_file: prompts/<name>.md\` |
+| Raw JS/Python function body | \`dypai/code/<name>.js\` or \`.py\` | \`code_file: code/<name>.js\` |
+| A regression test | \`dypai/tests/<name>.test.yaml\` | Run via \`dypai_test\` |
+| Realtime policy | Add entry to \`dypai/realtime.yaml\` | Auto-applied on push |
+| A new database table | Use \`execute_sql\` (CREATE TABLE …) | Auto-reflected in \`schema.sql\` |
+| A credential (OpenAI key, etc.) | Dashboard (not via MCP yet) | Reference by name: \`credential: openai-prod\` |
+
+### What NOT to edit
+
+- **\`schema.sql\`** — auto-generated snapshot of DB DDL. To change tables: \`execute_sql\` with CREATE/ALTER/DROP TABLE, schema.sql refreshes automatically.
+- **\`node-catalog.json\`** — auto-generated from the engine. Read it to learn node schemas; never hand-edit.
+- **\`dypai.config.yaml\`** — project identity (UUID, slug). Regenerated on pull.
+- **\`.dypai/\`** — local cache. The delta deploy + media manifest live here.
+- **\`src/lib/dypai.ts\`** — SDK client config. Regenerated by \`manage_frontend(sync)\`.
+
+### Path resolution inside YAML
+
+All \`*_file\` paths are relative to \`dypai/\` root:
+\`\`\`yaml
+# ✅ CORRECT (dypai/sql/get-orders.sql exists)
+query_file: sql/get-orders.sql
+
+# ❌ WRONG
+query_file: ./sql/get-orders.sql
+query_file: dypai/sql/get-orders.sql
+query_file: /absolute/path/sql/get-orders.sql
+\`\`\`
+
+### Paths on the engine side
+
+- \`/api/v0/<endpoint_name>\` — HTTP endpoints
+- \`/api/v0/webhooks/<endpoint_name>\` — webhook endpoints (different path prefix)
+- \`/public/<path>\` — media served from R2 (auto-populated on deploy; see "Frontend deploy")
+- \`https://<project_id>.dypai.app\` — the engine base URL (what the SDK points to)
+
+## Endpoint YAML skeleton (top-level fields)
 
 \`\`\`yaml
-name: search-products
-method: GET
-tool: true                                    # ← exposes it to agent nodes
-tool_description: |                           # ← what the agent should know about this tool
-  Search the product catalog by name or category.
-  Use when the user asks about availability, prices, or features.
-input:                                        # ← define a tight schema; the LLM reads it
+name: create-order                  # required. URL = /api/v0/create-order
+description: "..."                  # optional, shown in dashboard
+method: POST                        # optional (default POST)
+
+trigger:                            # required, exactly ONE of:
+  http_api: { auth_mode: jwt }      # HTTP (jwt | api_key | public)
+  # webhook: { path, methods, stripe_webhook, hmac_secret_env, auth_mode: public }
+  # schedule: { cron: "0 9 * * *", timezone: "Europe/Madrid", payload }
+  # telegram: { credential: my-bot }
+
+input:                              # optional JSON Schema — engine validates before workflow runs
   type: object
-  required: [query]
+  required: [product_id]
   properties:
-    query:   { type: string, description: "Free-text search term" }
-    limit:   { type: integer, default: 10 }
-trigger:
-  http_api:
-    auth_mode: api_key                        # agent calls are server-to-server
+    product_id: { type: string }
+
+allowed_roles: [admin]              # optional — restrict to these roles
+
+tool: true                          # optional — exposes this endpoint to agent nodes
+tool_description: "..."             # required when tool:true
+
 workflow:
   nodes:
-    - id: run
-      type: dypai_database
-      operation: query
-      return: true
-      query: SELECT id, name, price, stock FROM products WHERE name ILIKE '%' || \${input.query} || '%' LIMIT \${input.limit}
+    - { id: x, type: ..., return: true, ...params }
+  edges:
+    - { from: a, to: b }            # optional — default is declaration order
 \`\`\`
 
-Rules:
-- A tool endpoint is still a regular endpoint (same trigger, same workflow, same deploy). \`tool: true\` is additive.
-- **\`tool_description\` is critical** — this is the prompt the LLM sees when deciding whether to call your tool. Be specific about *when* to use it and *what it returns*. Vague descriptions cause the agent to skip useful tools or misuse them.
-- Define a **tight \`input\` JSON Schema** with \`description\` on each field. The LLM uses the schema to fabricate arguments; sloppy schemas = sloppy calls.
-- Auth mode: usually \`api_key\` (the agent node calls server-side) or \`jwt\` if you need \${current_user_id} in the tool. **Never \`public\`** for tools that write data.
+**Auth modes**: \`jwt\` (user-authed, auto-injects \`\${current_user_id}\` / \`\${current_user_role}\`), \`api_key\` (server-to-server, \`x-api-key\` header), \`public\` (anonymous, NEVER for writes).
 
-### Step 2 — wire the tool into an \`agent\` node (in another endpoint's YAML)
+**Placeholders**: \`\${input.<f>}\`, \`\${nodes.<id>.<f>}\`, \`\${current_user_id}\` (jwt only), \`\${current_user_role}\` (jwt only), \`\${env.<VAR>}\` (engine env vars from dashboard).
 
-In the YAML you reference tools **by name**, not by UUID. The codec converts names ↔ UUIDs automatically on push/pull.
+→ Deep reference: \`search_docs("trigger model")\` (full trigger options per type), \`search_docs("workflow patterns")\` (mandatory patterns), \`search_docs("auth defaults")\` (what to use when user doesn't specify).
 
-\`\`\`yaml
-workflow:
-  nodes:
-    - id: chat
-      type: agent
-      provider: openai                        # or anthropic | google
-      model: gpt-4o
-      credential: openai-prod                 # must exist — use get_app_credentials
-      system_prompt: |
-        You are a shop assistant. Use the search-products tool when the user
-        asks about availability, prices, or categories.
-      input: \${input.message}
-      tools: [search-products, send-email]    # ← by name. Codec resolves to UUIDs on push.
-      max_iterations: 5
-      return: true
-\`\`\`
+## Templates (reuse before reinventing)
 
-**COMMON TRAP**: the raw engine parameter is called \`tool_ids\` (takes UUIDs). If you read \`dypai/node-catalog.json\` you'll see that name. In YAML you MUST write \`tools: [names]\` — if you write \`tool_ids: ["my-endpoint"]\` the codec does NOT transform it, the engine receives "my-endpoint" as a literal UUID, and you fail silently in production. Always \`tools: [names]\` in YAML.
+Before writing a workflow from scratch, check if it already exists:
 
-### Step 3 — discover existing tools
+- **\`search_workflow_templates(query: "...")\`** — curated templates for common patterns (Stripe checkout, send email via Resend, AI chatbot, CRUD with realtime, Telegram bot, etc.). Returns ready-to-use YAML you can copy into \`dypai/endpoints/\`.
+- **\`search_project_templates(query: "...")\`** — full project starters (clinic, gym, waitlist, saas dashboard). Pass the slug to \`create_project(template_slug: "...")\`.
+- **\`dypai/endpoints/_example.yaml.disabled\`** — auto-shipped on empty projects. Complete tour of every trigger type, every common node, auth modes, agent tools, return paths. Read it when starting fresh.
 
-\`dypai_pull\` returns an \`overview.endpoints.tool_endpoints\` array listing every endpoint marked \`tool: true\` with its \`tool_description\`. Check that list before writing a new tool — you might already have it.
+Pattern: search templates → if match, copy + adapt → else write from scratch using the node-catalog.json.
 
-### Validation
+## dypai_database — query vs mutation
 
-\`dypai_validate\` has rule \`agent_tool_not_found\`: if an \`agent\` node references \`tools: ["foo"]\` and either no endpoint named "foo" exists, or it's not marked \`tool: true\`, validate fails with a fix_hint listing the available tool endpoints. Catches typos before you push.
+Two operations:
+- **\`operation: query\`** — raw SQL. Use for ALL reads and any complex write (joins, CTEs, subqueries, aggregations, multi-table).
+- **\`operation: mutation\`** — declarative single-table CRUD. The shape decides: \`insert:\` → INSERT, \`insert:\` + \`on_conflict:\` → UPSERT, \`update:\` + \`where:\` → UPDATE, \`delete: true\` + \`where:\` → DELETE.
 
-### Recursion safety
+**Legacy ops** (\`select\`/\`insert\`/\`update\`/\`delete\`/\`upsert\`/\`aggregate\`/\`custom_query\`) still work but don't write new ones — validator warns.
 
-The engine enforces a depth limit (currently 3) on agent→tool→agent chains, plus per-workflow stack tracking. A tool can itself be an agent endpoint, but runaway loops are cut off automatically.
+→ Full shapes + examples: \`search_docs("nodes reference")\` or read \`dypai/node-catalog.json\` entry for \`dypai_database\`.
 
-## Testing & Debugging
+## SQL placeholders — no manual casts
 
-- **"Let me run this endpoint and see"** → \`dypai_test_endpoint\`
-  The only test tool surfaced today. Pass endpoint name + input. Reads the LOCAL YAML (even unpushed edits), inlines *_file refs, runs against the engine with fabricated input. For jwt endpoints pass as_user UUID to impersonate. Iterate tightly: edit → test → fix → test → push.
-
-- A YAML-based regression-test suite runner is planned but not yet surfaced — when writing a new endpoint, verify it with dypai_test_endpoint after each edit and document edge cases in the commit message / PR for now.
-
-- Historical production traces are not inspectable via MCP yet — direct the user to the dashboard if they need to debug a specific past execution.
-
-## Where things live
-- dypai/endpoints/foo.yaml — endpoint definition (top-level, no group)
-- dypai/endpoints/Admin/foo.yaml — endpoint in group "Admin" (subfolder = group)
-- dypai/sql/foo.sql — SQL extracted when > 500 chars
-- dypai/prompts/foo.md — agent system prompts extracted when > 800 chars
-- dypai/code/foo.js — JavaScript/Python extracted when > 500 chars (escape hatch only)
-- dypai/schema.sql — DDL of public.* tables (read BEFORE writing SQL; auto-refreshed on DDL)
-- dypai/node-catalog.json — every node_type with its input/output schemas
-- dypai/realtime.yaml — realtime subscription policies (optional)
-- dypai/tests/*.test.yaml — reserved for the v2 suite runner; leave empty for now
-- dypai/dypai.config.yaml — project identity (don't hand-edit)
-- dypai/.dypai/ — local cache (gitignored)
-- src/dypai/ — NOT auto-generated. If you want TS types for row shapes in the frontend, define them manually based on dypai/schema.sql (a codegen helper may return in a future version).
-- All *_file paths inside YAML are relative to dypai/ root (not to the YAML file).
-
-## Build Frontend
-- SDK client is already configured at src/lib/dypai.ts — just import it:
-  import { dypai } from './lib/dypai'
-- Types: \`import { api } from '@/dypai'\` for typed endpoint calls with autocomplete.
-- API calls: dypai.api.get(name), dypai.api.post(name, body), dypai.api.put(), dypai.api.delete()
-- Auth: dypai.auth.signInWithPassword(), signUp(), signOut(), getSession()
-- Realtime: dypai.realtime.subscribe(table, opts, callback)
-- Files: dypai.api.upload(name, file) — always upload from browser
-- Every method returns { data, error } — never throws
-- Do NOT call the API directly with fetch() — always use the SDK
-- Do NOT create auth endpoints — auth is built-in via SDK (dypai.auth.*)
-
-### \`.env\` file — required for the SDK to reach the engine
-The frontend SDK reads the engine URL from an environment variable. \`.env\` is gitignored, so \`manage_frontend(sync)\` does NOT bring it down. **If the project has no \`.env\` after sync (the response sets \`env_file_missing: true\`), you MUST create it** before running or deploying the frontend:
+The engine binds placeholders as Postgres params (\$1, \$2…), injection-safe. Auto-casts by value shape: UUID-shaped strings → \`\$1::uuid\`, objects/arrays → \`\$1::jsonb\`, Date → \`\$1::timestamptz\`, primitives → inferred.
 
-\`\`\`bash
-# Vite / React / Svelte / Vue / etc.
-VITE_DYPAI_URL=https://<project_id>.dypai.app
-VITE_PROJECT_ID=<project_id>
+Write SQL naturally:
+\`\`\`
+✅  WHERE user_id = \${current_user_id}
+❌  WHERE user_id = '\${current_user_id}'::uuid    (redundant — validator warns)
+\`\`\`
 
-# Next.js (prefix matters — must be NEXT_PUBLIC_ to be readable in the browser)
-NEXT_PUBLIC_DYPAI_URL=https://<project_id>.dypai.app
+## Canonical YAML slip-ups (typical mistakes the codec catches but don't ship)
+
+- **Trigger is TOP-LEVEL**, never a node. \`trigger: { http_api | webhook | schedule | telegram }\`. Don't write \`start_trigger\` as a node.
+- **Nodes use \`type\` (not \`node_type\`) and \`return: true\` (not \`is_return\`)**. Codec accepts aliases — write canonical.
+- **Edges use \`from/to\`** (not \`source/target\`). Branching: \`{ from: cond, to: y, source_handle: "true" }\`.
+- **Params are FLAT on the node**. Only nest under \`parameters:\` when a param name collides with reserved keys (id/type/return/variable).
+- **Multiple \`return: true\` nodes are fine** — execution reaches one per run.
+
+When in doubt → \`dypai/endpoints/_example.yaml.disabled\` (shipped on empty projects) or \`search_docs("trigger model")\` for a complete tour.
+
+## Workflow execution model (what happens under the hood)
+
+- **Nodes form a DAG** from \`edges\`. With no explicit edges, nodes run sequentially in declaration order.
+- **Data flow**: each node reads \`\${input.<field>}\` (endpoint input) and \`\${nodes.<id>.<field>}\` (prior node output). A node's output is whatever its last expression/return produces.
+- **Return**: the HTTP response is the output of the FIRST node reached with \`return: true\`. Multiple \`return: true\` nodes are fine — only one fires per run.
+- **Errors**: an unhandled throw in any node fails the whole workflow → HTTP 500 with the error message. Use the \`logic\` node or try/catch in \`javascript_code\` for controlled error responses.
+- **Timeouts**: default workflow timeout is 30s (raised to 90s on Pro+). Individual nodes don't have sub-timeouts — design around the total.
+- **Concurrency**: per-project, not per-endpoint. Pool-mode projects share a slot budget based on plan.
+
+## Auth (better-auth backed)
+
+**No DIY auth.** Never write login/signup/session endpoints — the SDK handles everything:
+\`\`\`ts
+await dypai.auth.signUp({ email, password, name })
+await dypai.auth.signInWithPassword({ email, password })
+await dypai.auth.signOut()
+const session = await dypai.auth.getSession()   // null if not logged in
 \`\`\`
 
-- \`<project_id>\` is the UUID from \`list_projects\` / \`dypai.config.yaml\`.
-- Override the base domain with the \`DYPAI_ENGINE_BASE\` env var (default \`dypai.app\`) only for self-hosted setups.
-- Without \`.env\`, every SDK call fails with a network error / 404 because \`createClient(undefined)\` resolves nowhere. Don't try to debug the code — it's the missing env var.
+**Protecting endpoints**: \`trigger.http_api.auth_mode: jwt\` is the default. \`\${current_user_id}\` and \`\${current_user_role}\` are auto-injected into the workflow — use them in SQL WHERE clauses for multi-tenant isolation.
 
-## Deploy Frontend
-- \`manage_frontend(operation: deploy, sourceDirectory, project_id)\` — uploads source, returns immediately with build_status=queued.
-- Poll \`manage_frontend(operation: build_status)\` every ~5s until status is "success" or "failure" (typical build: 20-60s).
-- On failure: \`manage_frontend(operation: list_deployments)\` → pick the failed deployment_id → \`manage_frontend(operation: logs, deployment_id)\`.
-- Supports: Vite, React, Next.js, Astro, SvelteKit, Nuxt, Remix, Angular, CRA, and more (auto-detected).
+**Role-based access**: add \`allowed_roles: [admin, editor]\` at the endpoint top-level to restrict. Roles live in \`system.roles\` (manage via \`manage_roles\`). Built-in roles: \`authenticated\`, \`admin\`. User role lives in \`auth.users.role\` (manage via \`manage_users\`).
 
-## Import Data
-- Use bulk_upsert to import CSV or JSON files into database tables
-- Great for seeding initial data (products, categories, config)
+**Protected frontend routes**: wrap with \`<ProtectedRoute>\` from \`@dypai-ai/client-sdk/react\` — redirects to login if no session.
 
-## Custom Domains
-- manage_domain(operation: list | add | remove | verify) — single tool for all domain ops.
-  - add returns the CNAME the user must configure at their registrar. SSL provisions automatically once DNS propagates.
-  - verify forces an on-demand DNS/SSL re-check (normally the platform polls in the background).
+**No RLS magic**: the engine does NOT auto-filter queries by user. You MUST write \`WHERE user_id = \${current_user_id}\` in your SQL. Missing this is the #1 multi-tenancy bug.
 
-## Endpoint Rules
-- Auth modes: jwt (default — for user-authenticated requests), api_key (server-to-server), public (read-only, anonymous).
-- NEVER use public for endpoints that write data.
-- Placeholders: \${input.<field>}, \${nodes.<node_id>.<field>}, \${current_user_id}, \${current_user_role}.
-- \${current_user_id} / \${current_user_role} only work with jwt auth mode.
+→ Canonical flows (signup/reset/role upgrade/magic link): \`search_docs("auth flows")\`. What defaults to pick when user doesn't specify: \`search_docs("auth defaults")\`.
 
-## dypai_database — choose between query and mutation
+## Agent node (\`type: agent\`)
 
-The dypai_database node has TWO operations. Pick the right one and you'll never
-need the others:
+Vercel AI SDK under the hood. Supports OpenAI, Anthropic, Google. Key params: \`memory_key\` (persist conversation), \`tools: [names]\` (see Agent tools), \`max_iterations\` (default 5), \`return: true\` for streaming via SSE.
 
-### \`operation: query\` — SQL (the power tool, no limits)
-Use for ANY non-trivial read or any complex write. Joins, CTEs, subqueries,
-window functions, FILTER clauses, aggregations, multi-table — all fair game.
+**Cost awareness**: agents with tools + high max_iterations fan out (5-10 LLM calls per chat). For simple completions without tools, \`http_request\` to the provider is cheaper.
 
-\`\`\`yaml
-- id: dashboard
-  type: dypai_database
-  operation: query
-  return: true
-  query: |
-    WITH revenue AS (
-      SELECT SUM(amount) AS total FROM invoices
-      WHERE user_id = \${current_user_id} AND paid_at >= date_trunc('month', NOW())
-    )
-    SELECT
-      (SELECT total FROM revenue) AS revenue,
-      (SELECT COUNT(*) FROM tasks WHERE user_id = \${current_user_id} AND status = 'pending') AS pending_tasks
-\`\`\`
+→ Deep details: \`search_docs("agent ai")\` — memory, streaming, structured output, provider specifics.
 
-### \`operation: mutation\` — declarative CRUD (no SQL needed)
-Use for trivial single-table writes. The shape decides the operation:
+## Core DYPAI nodes (the primitives)
 
-\`\`\`yaml
-# INSERT
-- id: create
-  type: dypai_database
-  operation: mutation
-  return: true
-  table: clients
-  insert: { name: \${input.name}, user_id: \${current_user_id} }
-
-# UPSERT (insert + on_conflict)
-- id: upsert
-  type: dypai_database
-  operation: mutation
-  return: true
-  table: clients
-  insert: { id: \${input.id}, name: \${input.name} }
-  on_conflict: { columns: [id], action: update }
-
-# UPDATE
-- id: update
-  type: dypai_database
-  operation: mutation
-  return: true
-  table: clients
-  update: { name: \${input.name} }
-  where: { id: \${input.id}, user_id: \${current_user_id} }
-
-# DELETE
-- id: delete
-  type: dypai_database
-  operation: mutation
-  table: clients
-  delete: true
-  where: { id: \${input.id}, user_id: \${current_user_id} }
-\`\`\`
+These are the engine-level building blocks you'll use in almost every workflow. Learn these well — integrations are just on top.
 
-### Decision tree (use this — it's all you need)
-- Reading anything → \`operation: query\` (yes, even simple SELECTs — query is fine)
-- Writing one table, no fancy SQL → \`operation: mutation\`
-- Anything else (joins, subqueries, CTEs, multi-table writes) → \`operation: query\`
+| Node | What it does |
+|---|---|
+| \`dypai_database\` | SQL (query) or declarative CRUD (mutation) against the project's Postgres. THE most-used node. |
+| \`dypai_storage\` | Upload / download / delete files in storage buckets. |
+| \`agent\` | LLM call with tools, memory, streaming. OpenAI / Anthropic / Google. |
+| \`http_request\` | Generic HTTP call for anything without a dedicated integration node. |
+| \`set_fields\` | Reshape / rename / merge fields into a new object. Use instead of JS for trivial transforms. |
+| \`logic\` | if / else / switch branching with multiple outcomes. |
+| \`foreach\` / \`filter\` / \`merge\` | Array iteration, filtering, combining collections. |
+| \`wait_delay\` | Pause the workflow for N seconds (debouncing, rate limiting). |
+| \`datetime\` | Parse, format, arithmetic on dates/times. |
+| \`crypto\` | Hash, HMAC, encrypt/decrypt, generate tokens. |
+| \`javascript_code\` / \`python_code\` | Escape hatch for custom logic that doesn't fit the native nodes. |
 
-### Legacy operations (deprecated but still work)
-\`select\`, \`insert\`, \`update\`, \`delete\`, \`upsert\`, \`aggregate\`, \`copy_to\`, \`custom_query\` — old endpoints in production keep running. Don't write new ones with these. \`dypai_validate\` warns if you do.
+Triggers (separate category — they START a workflow):
+- \`webhook_trigger\` / \`schedule_trigger\` / \`telegram_trigger\` → declared via \`trigger:\` at the endpoint top-level, not as workflow nodes.
 
-## SQL Placeholders & Auto-Cast (IMPORTANT)
-Inside SQL queries (operation: query, or mutation values) the engine binds
-placeholders as real Postgres parameters (\$1, \$2…) — NOT string interpolation.
-This is injection-safe and type-safe by construction.
+## Finding 3rd-party integrations (native-first rule)
 
-The engine auto-casts based on the value SHAPE:
-  UUID-shaped string  → bound as \$1::uuid       (e.g. \${current_user_id})
-  plain object/array  → bound as \$1::jsonb      (e.g. \${input.metadata})
-  Date instance       → bound as \$1::timestamptz
-  text / int / bool   → bound without cast (Postgres infers from column)
+For external providers (Stripe, Resend, Slack, Telegram, WhatsApp, Google Sheets, PostgreSQL, SMTP, etc.) check the catalog BEFORE reaching for \`http_request\`:
 
-**Write SQL naturally — DO NOT add manual casts**:
-  ✅  WHERE user_id = \${current_user_id}
-  ❌  WHERE user_id = '\${current_user_id}'::uuid       (redundant, validator warns)
+1. **\`Read dypai/node-catalog.json\`** — single source of truth. Every \`node_type\` with full schema. It's cached locally, grep works.
+2. Search by provider name or concept: "stripe", "email", "telegram", "sheets".
+3. If a dedicated node exists → use it. Better error messages, credential auto-wiring, validator coverage.
+4. If none exists → fall back to \`http_request\` + a credential.
 
-  ✅  INSERT INTO events(payload) VALUES (\${input.meta})
-  ❌  INSERT INTO events(payload) VALUES ('\${input.meta}'::jsonb)  (redundant)
+## Credentials (how user secrets flow)
 
-The validator (dypai_validate) flags manual casts with rule \`sql_redundant_uuid_cast\`.
+- **Lifecycle**: user creates credentials **in the dashboard** (not via MCP yet). Each has a \`name\` (e.g. \`openai-prod\`, \`stripe-live\`), a \`type\` (matching the integration), and the actual secret.
+- **Referencing**: in YAML, point at a credential by name: \`credential: openai-prod\`. The engine injects the secret at runtime — the secret value NEVER appears in the YAML.
+- **Discovery**: \`get_app_credentials(project_id)\` lists what's already configured. Check this BEFORE writing a node that references a credential — if it doesn't exist, tell the user to create it.
+- **Common trap**: writing \`credential: openai\` when the user named it \`openai-prod\` → workflow fails with "credential not found". Always match the exact name from \`get_app_credentials\`.
 
-## Common Mistakes
-- Do NOT default to javascript_code — use native nodes (see decision tree above).
-- Do NOT create auth endpoints — auth is built-in via SDK (dypai.auth.*).
-- Do NOT use fetch() in frontend — use the SDK (dypai.api.*).
-- Do NOT edit endpoints without running dypai_pull first (you'd overwrite unknown state).
-- Do NOT skip dypai_validate — it catches schema/placeholder/credential errors before push.
-- Do NOT push without dypai_diff — always preview first.
-- Do NOT look up tables / endpoints remotely when a local dypai/ exists. Use Read/Glob/Grep on the files.
-- Do NOT push just to test a change — use dypai_test_endpoint to run the LOCAL edited version against the engine. Only push when you're satisfied.
+→ Full credential types + which provider needs what: \`search_docs("credentials reference")\`. Step-by-step integration flows: \`search_docs("integrations guide")\`.
 
-## Canonical YAML format (READ CAREFULLY — typical confusion points)
+## Environment variables
 
-Endpoint YAMLs follow ONE canonical shape. The codec tolerates some legacy aliases for forward-compat, but the canonical form is what you should write. These are the patterns where agents most commonly slip:
+- Set in the **dashboard** (Project → Env Vars). Available to ALL workflows as \`\${env.<NAME>}\`.
+- Use for non-provider secrets or config (webhook secrets, feature flags, custom URLs).
+- Different from frontend \`.env\` (which is for \`VITE_*\` / \`NEXT_PUBLIC_*\` vars the BROWSER reads).
+- Frontend env vars are NOT available in workflows. Workflow env vars are NOT available in the browser. Keep them mentally separate.
 
-### Trigger is TOP-LEVEL, never a node
-\`\`\`yaml
-# ✅ CORRECT
-trigger:
-  http_api:
-    auth_mode: jwt
-workflow:
-  nodes:
-    - id: list
-      type: dypai_database
-      ...
-\`\`\`
-\`\`\`yaml
-# ❌ WRONG — start_trigger is NOT a node anymore
-workflow:
-  nodes:
-    - id: start
-      type: start_trigger     # the codec auto-strips this and warns
-      ...
-\`\`\`
-Trigger options: \`http_api\` / \`webhook\` / \`schedule\` / \`telegram\`. \`auth_mode\` is one of \`jwt\` / \`api_key\` / \`public\`.
+## SDK (\`@dypai-ai/client-sdk\`)
 
-### Nodes use \`type\`, not \`node_type\`
-\`\`\`yaml
-- id: insert
-  type: dypai_database          # ✅ canonical
-  return: true                  # ✅ not is_return
-\`\`\`
-The codec accepts \`node_type\` and \`is_return\` for safety, but write the canonical form.
+Pre-configured at \`src/lib/dypai.ts\`. Every method returns \`{ data, error }\` — never throws. Endpoints are called BY NAME (not URL).
 
-### Edges use \`from/to\`, not \`source/target\`
-\`\`\`yaml
-edges:
-  - { from: a, to: b }                          # ✅ canonical
-  - { from: cond, to: y, source_handle: "true" } # ✅ for branching
-\`\`\`
+**Three namespaces**:
+- \`dypai.api\` → \`get\` / \`post\` / \`put\` / \`delete\` / \`upload\` / \`stream\` (SSE async iterator)
+- \`dypai.auth\` → \`signUp\` / \`signInWithPassword\` / \`signOut\` / \`getSession\` / \`resetPassword\` / \`updateUser\` — NEVER create auth endpoints, the SDK does everything.
+- \`dypai.realtime\` → \`subscribe(table, opts, callback)\` with Postgres-style filters (\`user_id=eq.\${uid}\`)
 
-### Parameters are FLAT inline on the node, not nested
-\`\`\`yaml
-# ✅ CORRECT — params flat on the node
-- id: insert
-  type: dypai_database
-  operation: insert
-  table: orders
-  data: { user_id: \${current_user_id}, qty: \${input.qty} }
-\`\`\`
-\`\`\`yaml
-# ❌ AVOID — only use nested parameters: when a param NAME collides with id/type/return/variable
-- id: insert
-  type: dypai_database
-  parameters:
-    operation: insert
-    table: orders
-\`\`\`
+**React hooks** (preferred over raw calls): \`DypaiProvider\` wrap, \`useAuth\`, \`useEndpoint\` (GET auto-fetch + refetch), \`useAction\` (mutation), \`useUpload\` (progress), \`useRealtime\`, \`useChannel\`, \`useChannelMessages\`, \`useChannels\`, \`<ProtectedRoute>\`.
 
-### Multiple return paths are fine
-Mark \`return: true\` on every node that produces a final HTTP response. Workflow execution only reaches one of them per run.
+→ Full method signatures + examples: \`search_docs("sdk reference")\` (raw SDK), \`search_docs("react hooks")\` (all hooks with params).
 
-### Agent tools use \`tool:\` + \`tools: [names]\`
-\`\`\`yaml
-# Endpoint exposes itself as a tool:
-name: search-products
-tool: true
-tool_description: "Search the product catalog. Use for availability/prices."
-\`\`\`
-\`\`\`yaml
-# Agent node references tools by NAME (codec resolves to UUIDs on push):
-- id: chat
-  type: agent
-  tools: [search-products, send-email]   # ✅ names
+## What the engine handles for you (don't reinvent)
+
+- **JWT verification** — jwt auth_mode validates the session token automatically. \`\${current_user_id}\` is trusted.
+- **Rate limiting** — per-plan. Returns 429 automatically.
+- **CORS** — allowed origins per project (configured in dashboard).
+- **Request logging** — every execution in \`system.workflow_runs\` with duration, status, tokens (for agents). View via \`get_recent_workflow_activity\`.
+- **Input validation** — if the endpoint has \`input:\` schema, requests with invalid payloads are rejected with 400 + details BEFORE the workflow runs.
+- **SQL injection** — placeholders bind as Postgres params. Safe by construction.
+- **Secrets management** — credentials and env vars never appear in YAML or logs.
+- **Scheduled jobs** — schedule_trigger endpoints are enqueued by the engine on startup + on deploy. No cron daemon to configure.
+- **Webhook retries** — NOT automatic. If you need retries on failures, add an explicit \`wait_delay\` + re-attempt in the workflow.
+
+## Common app recipes
+
+- **Auth-gated CRUD**: CREATE TABLE with \`user_id UUID\`. Endpoints jwt-auth. SQL always \`WHERE user_id = \${current_user_id}\`. Frontend wraps routes in \`ProtectedRoute\`.
+- **Admin panel**: endpoints with \`allowed_roles: [admin]\`. Same SQL but no user_id filter (admin sees all). Promote users via \`manage_users(operation: update_role)\`.
+- **AI chat**: single endpoint with \`agent\` node + \`memory_key: "chat:\${current_user_id}"\`. Frontend uses \`dypai.api.stream()\` for SSE.
+- **Payments (Stripe)**: \`stripe\` node for operations (checkout, invoices). Webhook endpoint with \`trigger.webhook\` + \`stripe_webhook: true\` receives events — the node auto-verifies the signature.
+- **Cron job**: endpoint with \`trigger.schedule: { cron: "0 9 * * *", timezone: "Europe/Madrid" }\`. Workflow body runs in engine — same syntax as HTTP endpoints.
+- **File uploads**: frontend uses \`dypai.api.upload(endpoint, file)\`. The endpoint is a workflow with one \`dypai_storage\` node (\`operation: upload\`, \`bucket: <name>\`, \`confirm: false\`). SDK handles the signed URL PUT flow.
+- **Live dashboard**: normal endpoint returning aggregated data + frontend \`useRealtime(table, { onInsert: refetch })\`. Auto-updates when rows change.
+- **Multi-tenant**: every row has \`org_id\` or \`user_id\`. Every endpoint filters by \`\${current_user_id}\`. Shared resources → endpoints with \`allowed_roles\`.
+
+## Gotchas that will cost time if you don't know them
+
+- **\`.env\` missing after sync** → frontend SDK can't reach the engine → every API call 404s. The fix is always creating .env, not debugging code.
+- **\`tool_ids\` vs \`tools\`** → write \`tools: [names]\` in YAML. Using \`tool_ids\` makes the engine receive the name as a literal UUID. Fails silently in prod.
+- **Missing \`return: true\`** → endpoint returns \`null\` or empty. Every path that should produce an HTTP response needs it.
+- **\`public\` auth_mode with placeholders** → \`\${current_user_id}\` is empty → SQL fails or returns wrong data. Use jwt if you need the user.
+- **Forgetting \`WHERE user_id = \${current_user_id}\`** → users see each other's data. The engine does NOT auto-filter.
+- **Credentials not created** → workflow fails with "credential not found". Check \`get_app_credentials\` before referencing one in a node. Create in dashboard (not via MCP yet).
+- **Binary files in \`dypai/code/\`** → only text code files here. Binary assets go to the frontend \`public/\` or to a bucket.
+- **\`dypai_push\` without \`dypai_validate\`** → pushing a broken workflow. Always validate first.
+- **Frontend dev server + R2 media** → media files are auto-uploaded to R2 on deploy but \`vite dev\` doesn't proxy to R2. Run \`manage_frontend(sync)\` first to pull media to disk.
+
+## Frontend
+
+SDK is pre-configured at \`src/lib/dypai.ts\`. Import \`dypai\` from there. Every method returns \`{ data, error }\` — never throws.
+
+- **API calls**: \`dypai.api.get(name)\`, \`.post(name, body)\`, \`.put()\`, \`.delete()\`, \`.upload(name, file)\`
+- **Auth**: \`dypai.auth.signInWithPassword()\`, \`.signUp()\`, \`.signOut()\`, \`.getSession()\` — DO NOT create auth endpoints
+- **Types**: \`import { api } from '@/dypai'\` for typed endpoint calls
+- **Realtime hooks**: \`useRealtime\`, \`useChannel\`, \`useChannelMessages\` (see Realtime section)
+- **Rule**: NEVER \`fetch()\` directly — always through the SDK
+
+**\`.env\` required** — \`.env\` is gitignored so \`manage_frontend(sync)\` does NOT fetch it. If \`env_file_missing: true\` in the sync response, create it:
+\`\`\`bash
+# Vite
+VITE_DYPAI_URL=https://<project_id>.dypai.app
+VITE_PROJECT_ID=<project_id>
+# Next.js (NEXT_PUBLIC_ prefix is required)
+NEXT_PUBLIC_DYPAI_URL=https://<project_id>.dypai.app
 \`\`\`
-⚠️ The engine param is \`tool_ids\` (UUIDs) but in YAML you write \`tools: [names]\`. Writing \`tool_ids: ["name"]\` in YAML bypasses the codec transform and fails in production. See the "Agent tools" section above for the full pattern.
+Without \`.env\`, all SDK calls fail. It's always the missing env var, not the code.
+
+## Frontend deploy
+
+\`manage_frontend(operation: deploy, sourceDirectory, project_id)\` → returns immediately with build_status=queued. Poll \`operation: build_status\` every ~5s until "success" or "failure". On failure: \`operation: list_deployments\` → \`operation: logs\` with deployment_id. Supports Vite, React, Next.js, Astro, SvelteKit, Nuxt, Remix, Angular, CRA (auto-detected).
+
+The deploy is delta by default: only files changed since last deploy are sent. Large media (>25MB) surfaces in \`assets_requiring_action\` with ready-to-exec \`manage_storage(upload_file)\` calls.
+
+→ Framework-specific gotchas (Next SSR, Vite, Astro, etc.): \`search_docs("frontend frameworks")\`. Deploy tool operations deep dive: \`search_docs("manage frontend")\`.
+
+## Other tools
 
-### When in doubt
-Read \`dypai/endpoints/_example.yaml.disabled\` (auto-shipped on empty projects) — it's a complete tour of every pattern.
+- \`bulk_upsert\` — import CSV/JSON into a table. Great for seed data.
+- \`manage_domain\` — custom domains. \`add\` returns the CNAME to configure. \`verify\` forces DNS/SSL recheck. → \`search_docs("manage domain")\`.
+- \`manage_users\` / \`manage_roles\` — app-level RBAC (users via better-auth).
+- \`manage_schedules\` / \`manage_webhooks\` — pause/resume/history. To change the DEFINITION, edit the endpoint YAML and push.
+- \`manage_storage\` — buckets + objects. \`upload_file\` reads local path, signs URL, PUTs direct to R2, registers. Max 100MB/file. → \`search_docs("file storage")\`.
+
+## Deep docs — search_docs topic map
+
+When you need more detail than this prompt gives, \`search_docs\` is vectorized semantic search over the full DYPAI docs. Topics available (query with the keywords in parentheses):
+
+- **Orientation**: "platform guide" (what AI can do vs user-manual actions), "project setup" (phased build flow)
+- **Backend**: "git-first workflow", "trigger model", "workflow patterns", "nodes reference", "node types", "javascript code node"
+- **AI**: "agent ai" (agent node deep dive)
+- **Auth**: "auth flows" (canonical patterns), "auth defaults" (what to default to)
+- **Integrations**: "integrations guide", "credentials reference"
+- **Realtime**: "realtime channels" (client API), "realtime policies" (backend YAML)
+- **Storage**: "file storage"
+- **Frontend**: "sdk reference", "react hooks", "frontend frameworks", "manage frontend"
+- **Ops**: "manage domain", "testing endpoints", "troubleshooting"
+
+Before writing something you're not 100% sure about → search first. The docs are the detailed truth; this prompt is the map.
 `
 
 // ── MCP Protocol (JSON-RPC over stdio) ──────────────────────────────────────
@@ -854,6 +896,19 @@ async function handleRequest(msg) {
           const toolDef = REMOTE_TOOLS.find(t => t.name === name)
           let finalArgs = withProjectContext(toolDef, args || {})
 
+          // manage_storage.upload_file is orchestrated LOCALLY (filesystem →
+          // sign → direct PUT to R2 → verify). It's listed under manage_storage
+          // so the agent sees one unified tool, but the binary never travels
+          // through the MCP transport — that would saturate the remote pod on
+          // large files. See tools/storage.js for the 3-step flow.
+          if (name === "manage_storage" && finalArgs?.operation === "upload_file") {
+            result = await uploadFile(finalArgs)
+            return makeResponse(id, {
+              content: [{ type: "text", text: typeof result === "string" ? result : JSON.stringify(result, null, 2) }],
+              isError: result?.success === false,
+            })
+          }
+
           // Resolve endpoint_name → endpoint_id for tools that accept only the UUID.
           // Keeps the agent-facing API name-based while the remote keeps its
           // UUID-based contract. Best-effort: if the lookup fails we still pass