@dypai-ai/mcp 1.4.6 → 1.5.0

package/src/index.js

@@ -56,6 +56,11 @@ import { enrichSuccess, enrichError } from "./tools/enrich.js"
 import { maybeRefreshSchemaAfterExecuteSql } from "./tools/sql-side-effects.js"
 import { maybeOffloadSearchLogs } from "./tools/search-logs-offload.js"
 import { withProjectContext, invalidateProjectContext } from "./tools/project-context.js"
+import { validateSql, formatValidationError } from "./tools/sql-guard.js"
+import { manageDatabaseTool } from "./tools/manage-database.js"
+// run_migration and introspect were collapsed into manage_database (discriminated
+// union by `operation`). Their standalone files still live on disk in case we
+// want to re-expose them, but the catalog only advertises manage_database.
 // summarizeDypaiTraceResponse (from ./tools/trace-summarize.js) is kept on
 // disk for when dypai_trace is re-enabled, but not imported here.
 
@@ -84,6 +89,12 @@ const LOCAL_TOOLS = [
   dypaiDiffTool,
   dypaiPushTool,
   dypaiTestEndpointTool,
+  // ── Schema / DB management ────────────────────────────────────────────────
+  // One discriminated-union tool for migrations, introspection, and multi-
+  // statement scripts. Uses the same `manage_*(operation, ...)` pattern as
+  // manage_users / manage_roles / manage_drafts. See tools/manage-database.js
+  // for the operation list + semantics.
+  manageDatabaseTool,
   // dypaiTestTool (YAML test-suite runner) — hidden until v2. See import comment above.
   // dypaiCodegenTool removed from v1 — see codegen import comment above.
 ]
@@ -111,7 +122,7 @@ const REMOTE_TOOLS = [
   // Note: `get_app_tables` is intentionally NOT exposed — dypai/schema.sql already
   // caches table info locally (auto-refreshed on DDL). For ad-hoc introspection,
   // use execute_sql against information_schema.
-  { name: "execute_sql", description: "BACKEND ONLY — executes any SQL query on the project database (PostgreSQL). Supports SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, ALTER TABLE, DROP TABLE. Platform schemas (system, auth, storage) are read-only for security. DDL on public.* auto-refreshes dypai/schema.sql. Note: DDL applies IMMEDIATELY to the live database (no draft stage) — for destructive DDL like DROP TABLE / TRUNCATE, summarize the impact and get the user's explicit OK before calling.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, sql: { type: "string", description: "SQL query to execute" } }, required: ["sql"] } },
+  { name: "execute_sql", description: "BACKEND ONLY — execute a SINGLE SQL statement on the project database. Supports SELECT, INSERT, UPDATE, DELETE, and single-statement DDL on `public.*`.\n\nSchema access: `public.*` writable. `auth`, `storage`, `system` are READ-ONLY — SELECT works, any write is rejected with a guided error.\n\nRejected (use other tools): multi-statement scripts, DO $$, EXECUTE, CALL, COPY, LOAD, SET ROLE/search_path. For multi-statement migrations, use `manage_database(operation:\"apply_migration\")`. For inspection, use `manage_database(operation:\"introspect_*\")`. Timeout: 30 s. DDL on public.* auto-refreshes dypai/schema.sql.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, sql: { type: "string", description: "A single SQL statement." } }, required: ["sql"] } },
 
   // ── API Endpoints ─────────────────────────────────────────────────────────
   // Full CRUD + exploration goes through the git-first flow:
@@ -478,6 +489,127 @@ 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 (workflow endpoints, database, auth, realtime) and FRONTEND (SDK integration, React/Vite/Next code).
 
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# TALKING TO THE USER — plain language, not tool names
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+The user is **not a developer watching your tool calls**. They read only your prose. Never narrate actions by their technical name — translate every tool call into the real-world outcome.
+
+## Translation rule of thumb
+
+Replace the VERB with what the user perceives:
+
+| Instead of (tool-speak) | Say (human) |
+|---|---|
+| "Voy a hacer dypai_push / I'll call dypai_push" | "Voy a subir los cambios al borrador para que los pruebes" |
+| "Voy a ejecutar manage_drafts(publish)" | "Voy a publicar los cambios en producción" |
+| "Ejecutando dypai_pull" | "Un momento, sincronizo tu proyecto" |
+| "Calling manage_frontend(deploy)" | "Voy a desplegar la nueva versión de tu web" |
+| "Running execute_sql to add a column" | "Voy a añadir un campo nuevo a la tabla X" |
+| "manage_database(operation:'apply_migration')" | "Voy a aplicar los cambios de estructura a la base de datos" |
+| "search_logs returned a 500" | "He mirado los registros: el error viene de..." |
+| "manage_drafts(list) shows 3 pending" | "Tienes 3 cambios pendientes de publicar" |
+| "On the draft overlay" / "en la overlay de draft" | "En tu entorno de previsualización" o "en el borrador" |
+| "dypai_validate rejected the workflow" | "Hay un problema con la configuración:" |
+
+## Principles
+
+1. **State outcomes, not function calls.** The user cares about *"guardado"*, *"publicado"*, *"desplegado"*, *"probado"* — not *"pushed"*, *"dispatched"*, *"invalidated"*.
+2. **Draft vs live → borrador vs producción / previsualización vs en vivo.** Never say "overlay", "engine", "endpoint hit" in user-facing prose.
+3. **Errors: summarize, don't paste.** *"Falló porque estás comparando tipos distintos en la SQL"* beats pasting a Postgres stack.
+4. **Confirmations use real-world verbs.** *"¿Lo publico a producción?"* not *"¿Ejecuto manage_drafts(publish, confirm:true)?"*.
+5. **Progress updates in sentences, not tool names.** *"Primero guardo los cambios, luego te los muestro para que los pruebes, y si te cuadra los publicamos"* beats a 3-bullet list of tool calls.
+
+## When you CAN mention a tool name
+
+- The user explicitly asks *"qué herramienta estás usando"* / *"how does this work under the hood"*.
+- You're writing documentation or a runbook (ONLY if they asked).
+- Error messages where the user will see an exact tool-level failure they'd have to react to.
+
+Default is **no tool names in user-facing text**.
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# SEARCH BEFORE YOU GUESS — \`search_docs\` is your reference manual
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+This prompt is the MAP of the DYPAI platform. The detailed docs live in
+\`search_docs\` (vectorized semantic search over the full manual). **If
+you're about to write something on a topic that feels fuzzy, search first
+— one \`search_docs\` call is always cheaper than a wrong push you then have
+to undo.**
+
+## When to call \`search_docs\` (triggers)
+
+- **Before writing an unfamiliar node type**: agent / stripe / telegram / google_sheets / webhook / schedule — query its name.
+- **Before touching a platform feature**: auth, realtime, storage, credentials, SDK, frontend framework specifics.
+- **When the user mentions a concept you don't have in cache**: "signup flow", "magic link", "custom domains", "file upload", "realtime channels", "draft flow", "migrations", "tools for agents".
+- **When a tool's response contains \`search_docs("X")\` hint**: call it — the hint is written in by the tool author for exactly that reason.
+- **When the user asks "how does X work"**: search BEFORE answering. Better an accurate answer after one search than a confident wrong one.
+
+Don't search for: generic programming (JS/Python/SQL syntax), third-party
+APIs outside DYPAI, anything you already have in this prompt.
+
+## Topic map — what's searchable
+
+Query with the phrases in parentheses. Semantic search is fuzzy; these are
+anchors, not exact strings. If the first result is thin, rephrase with a
+synonym.
+
+### Orientation
+- \`"platform guide"\` — what AI can do vs what lives in the user manual
+- \`"project setup"\` — phased build flow from empty project to live app
+
+### Backend core
+- \`"git-first workflow"\` — edit → validate → push → test → publish loop
+- \`"trigger model"\` — http_api / webhook / schedule / telegram options
+- \`"workflow patterns"\` — canonical shapes: CRUD, auth-gated, branching, multi-return, error handling
+- \`"drafts and publish"\` — push vs publish, draft overlay at \`dev-<id>.dypai.dev\`
+- \`"manage database"\` — migrations (\`apply_migration\`) + introspection + multi-statement scripts
+
+### Nodes
+- \`"nodes reference"\` — all nodes with input/output schemas (also in \`dypai/node-catalog.json\`)
+- \`"node types"\` — high-level grouping of what each node family does
+- \`"agent ai"\` — agent node: providers, tools, memory, streaming, tool endpoints
+- \`"javascript code node"\` — custom code escape hatch when native nodes don't fit
+
+### Auth
+- \`"auth flows"\` — signup / login / reset / magic link / role upgrade canonical flows
+- \`"auth defaults"\` — what auth_mode to pick when the user doesn't specify
+
+### Integrations
+- \`"integrations guide"\` — step-by-step integration recipes (Stripe has full coverage; Telegram, Slack, WhatsApp, Resend, Google Sheets are referenced inside this doc)
+- \`"credentials reference"\` — what fields each provider needs
+- To find a specific provider: \`search_docs("integrations guide stripe")\` (combine the topic + the provider name) — semantic search will pick up the provider's section
+
+### Realtime
+- \`"realtime channels"\` — client API for WebSocket subscriptions
+- \`"realtime policies"\` — backend \`dypai/realtime.yaml\` format + access control
+
+### Storage
+- \`"file storage"\` — buckets, upload flow, signed URLs, \`manage_storage\` ops
+
+### Frontend
+- \`"sdk reference"\` — raw \`@dypai-ai/client-sdk\` methods
+- \`"react hooks"\` — \`useAuth\`, \`useEndpoint\`, \`useAction\`, \`useUpload\`, \`ProtectedRoute\`
+- \`"frontend frameworks"\` — Next SSR gotchas, Vite config, Astro
+- \`"manage frontend"\` — sync / deploy / status / logs ops deep dive
+
+### Ops / debugging
+- \`"testing endpoints"\` — \`dypai_test_endpoint\` patterns + assertions
+- \`"troubleshooting"\` — common failures + fixes (catch-all for gotchas)
+- \`"manage domain"\` — custom domains + DNS / SSL
+- \`"manage database"\` — introspection ops (\`introspect_schema\` / \`introspect_table\` / \`introspect_function\`)
+
+## How to phrase a query
+
+- **Concept, not code.** \`search_docs("magic link auth flow")\` beats \`search_docs("dypai.auth.signInWithMagicLink")\`.
+- **Two or three words max.** Long queries dilute the vector. *"how do I send email"* → just \`"email integration"\` or \`"resend"\`.
+- **If first hit is unrelated, try a synonym.** "realtime" vs "websockets" vs "subscriptions" may all match different chunks.
+- **One search is cheap.** Two or three narrow searches beat one giant one if the topic is broad.
+
+When docs say the opposite of this prompt → **trust the docs**. This prompt
+is the quickstart; docs are authoritative and current.
+
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # QUICK START — read this section even if you skip everything else
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -621,456 +753,77 @@ Each item has \`type\` (\`execution_failed\` | \`log\`), \`level\` (\`error\` |
 - "Promoting projects to production" — every new project already has the draft-publish flow enabled. \`manage_project(promote_to_production)\` is legacy and you should never need it.
 
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-# DEEP REFERENCE — the rest of this document
+# ESSENTIALS — things you reuse every session
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-## 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.
-
 ## 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.
-
-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\`
-
-## Build Backend (git-first workflow)
-Endpoints live in ./dypai/ — there is NO create_endpoint / update_endpoint / add_node tool.
-
-1. Tables: \`execute_sql\` for DDL. \`schema.sql\` auto-refreshes. **DDL is the only backend mutation that bypasses drafts — it hits live immediately.**
-2. Endpoints / realtime / webhooks / crons:
-   - 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. Run before push (push also runs it as pre-flight).
-   - \`dypai_diff\` → preview changes (read-only).
-   - \`dypai_push\` → **stages your edits as drafts on the platform**. This is the "save" step. NOT a publish. Run after every meaningful change set, not just at the end of a session — until you push, neither the engine nor the local frontend (which talks to the draft overlay) can see your edits.
-   - \`manage_drafts(operation:'publish', confirm:true)\` → ONLY when the user signs off. Promotes ALL pending drafts atomically to live.
-3. \`dypai_test_endpoint\` to execute an endpoint against the engine. Three sources via \`mode\`: \`local\` (default — your YAML on disk, BEFORE push, fastest while iterating), \`draft\` (the version staged by \`dypai_push\` but not yet published — what live will look like after \`manage_drafts(publish)\`), \`live\` (currently deployed). Canonical loop: edit → \`dypai_validate\` → \`dypai_test_endpoint(mode:'local')\` → \`dypai_push\` → \`dypai_test_endpoint(mode:'draft')\` (or user tests local UI on the draft overlay) → \`manage_drafts(publish, confirm:true)\`.
-
-## Picking nodes — catalog-first
-
-\`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.
-
-**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)
+DYPAI has NO standalone "edge functions". Every piece of server-side logic (API endpoints, crons, webhooks, AI agents) is a workflow endpoint under \`dypai/endpoints/<name>.yaml\`. A workflow is either a chain of native nodes (\`dypai_database\`, \`http_request\`, \`agent\`, \`stripe\`, etc.) OR a single \`javascript_code\` / \`python_code\` node for custom logic. Mix freely.
 
-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.
+Mental translations: "edge function" → workflow with one code node; "cron" → \`trigger.schedule\` in the YAML; "webhook receiver" → \`trigger.webhook\`; "internal API" → \`trigger.http_api auth_mode:jwt\`.
 
-**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
-
-Four ways to validate a backend change, in increasing fidelity:
-
-1. **\`dypai_test_endpoint(mode:'local')\`** — runs YOUR YAML on disk against the engine BEFORE \`dypai_push\`. Fastest feedback loop while iterating on a single endpoint. Pass \`as_user\` UUID for jwt endpoints.
-2. **\`dypai_test_endpoint(mode:'draft')\`** — runs the version staged by \`dypai_push\` (i.e. exactly what \`manage_drafts(publish)\` will promote). Use as the final isolated check before publishing.
-3. **End-to-end from the local frontend** (Layer 2.5 draft overlay) — after \`dypai_push\`, the user's local frontend already calls \`https://dev-<project_id>.dypai.dev\` (set by \`manage_frontend(sync)\`), which serves drafts on top of live. So real UI flows hit the draft transparently. No setup, no env-flip, no headers. Read-only impact on prod data — drafts share the SAME database as live.
-4. **\`dypai_test_endpoint(mode:'live')\`** — repro a bug that's already in production.
-
-Other tools:
-- **\`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**: \`search_logs\` is the entry point — see the "Debugging user-reported errors" section above. Returns failed executions + warn/error logs from the last 7 days; pass \`environment:'live'\` to exclude draft-overlay test runs and \`include_trace:true\` for the per-node failure trace.
-
-→ Deep patterns: \`search_docs("testing endpoints")\` (test setup + assertions), \`search_docs("troubleshooting")\` (common failures + fixes).
-
-## The \`dypai/\` folder (BACKEND source of truth)
-
-\`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\`.
-
-\`\`\`
-<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 the storage bucket
-\`\`\`
-
-### Where to put what
-
-| If you need to add... | Put it here | How it's referenced |
-|---|---|---|
-| 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 the storage bucket (auto-populated on deploy; see "Frontend deploy")
-- \`https://<project_id>.dypai.dev\` — engine base URL serving LIVE traffic (what the deployed frontend's SDK points to)
-- \`https://dev-<project_id>.dypai.dev\` — engine base URL serving the **draft overlay** (Layer 2.5): drafts staged via \`dypai_push\` are served here, falling back to live for anything not drafted. This is what the SDK in \`.env.local\` points to during local frontend development, so a local UI can validate backend drafts end-to-end BEFORE \`manage_drafts(publish)\`.
-
-## Endpoint YAML skeleton (top-level fields)
-
-\`\`\`yaml
-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: [product_id]
-  properties:
-    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: x, type: ..., return: true, ...params }
-  edges:
-    - { from: a, to: b }            # optional — default is declaration order
-\`\`\`
-
-**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).
-
-**Placeholders**: \`\${input.<f>}\`, \`\${nodes.<id>.<f>}\`, \`\${current_user_id}\` (jwt only), \`\${current_user_role}\` (jwt only), \`\${env.<VAR>}\` (engine env vars from dashboard).
-
-→ 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).
-
-## Templates (reuse before reinventing)
-
-Before writing a workflow from scratch, check if it already exists:
-
-- **\`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.
-
-Pattern: search templates → if match, copy + adapt → else write from scratch using the node-catalog.json.
-
-## dypai_database — query vs mutation
-
-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.
-
-**Legacy ops** (\`select\`/\`insert\`/\`update\`/\`delete\`/\`upsert\`/\`aggregate\`/\`custom_query\`) still work but don't write new ones — validator warns.
-
-→ Full shapes + examples: \`search_docs("nodes reference")\` or read \`dypai/node-catalog.json\` entry for \`dypai_database\`.
-
-## SQL placeholders — no manual casts
-
-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.
-
-Write SQL naturally:
-\`\`\`
-✅  WHERE user_id = \${current_user_id}
-❌  WHERE user_id = '\${current_user_id}'::uuid    (redundant — validator warns)
-\`\`\`
-
-## 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
-\`\`\`
-
-**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.
-
-**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\`).
-
-**Protected frontend routes**: wrap with \`<ProtectedRoute>\` from \`@dypai-ai/client-sdk/react\` — redirects to login if no session.
-
-**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.
-
-→ 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")\`.
-
-## Agent node (\`type: agent\`)
-
-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.
-
-**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.
-
-→ Deep details: \`search_docs("agent ai")\` — memory, streaming, structured output, provider specifics.
-
-## Core DYPAI nodes (the primitives)
-
-These are the engine-level building blocks you'll use in almost every workflow. Learn these well — integrations are just on top.
-
-| 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. |
-
-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.
-
-## Finding 3rd-party integrations (native-first rule)
-
-For external providers (Stripe, Resend, Slack, Telegram, WhatsApp, Google Sheets, PostgreSQL, SMTP, etc.) check the catalog BEFORE reaching for \`http_request\`:
-
-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.
-
-## Credentials (how user secrets flow)
-
-- **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\`.
-
-→ Full credential types + which provider needs what: \`search_docs("credentials reference")\`. Step-by-step integration flows: \`search_docs("integrations guide")\`.
-
-## Environment variables
-
-- 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.
-
-## SDK (\`@dypai-ai/client-sdk\`)
-
-Pre-configured at \`src/lib/dypai.ts\`. Every method returns \`{ data, error }\` — never throws. Endpoints are called BY NAME (not URL).
-
-**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}\`)
-
-**React hooks** (preferred over raw calls): \`DypaiProvider\` wrap, \`useAuth\`, \`useEndpoint\` (GET auto-fetch + refetch), \`useAction\` (mutation), \`useUpload\` (progress), \`useRealtime\`, \`useChannel\`, \`useChannelMessages\`, \`useChannels\`, \`<ProtectedRoute>\`.
-
-→ Full method signatures + examples: \`search_docs("sdk reference")\` (raw SDK), \`search_docs("react hooks")\` (all hooks with params).
+→ Full workflow patterns + YAML shape: \`search_docs("workflow patterns")\` and \`search_docs("trigger model")\`. Node catalog (full input/output schemas): read \`dypai/node-catalog.json\`.
 
 ## 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 is recorded with duration, status, environment (live/draft), and (on failure) a per-node debug trace. Warn/error \`userLog\` lines are persisted alongside. Query both via \`search_logs\` (last 7 days).
-- **Input validation** — if the endpoint has \`input:\` schema, requests with invalid payloads are rejected with 400 + details BEFORE the workflow runs.
+- **Request logging** — every execution recorded with duration, status, environment, and (on failure) per-node trace. Query with \`search_logs\` (7-day retention).
+- **Input validation** — \`input:\` schema in YAML → invalid payloads rejected with 400 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.
-- **Editing a YAML and forgetting \`dypai_push\`** → the user reloads their local frontend (which points at the draft overlay \`dev-<project_id>.dypai.dev\`) and sees the OLD behavior because your edit only exists on YOUR DISK. Symptom: "I tested it locally and nothing changed." First check: did you push? Push after every meaningful change set, not at the end.
-- **Treating \`dypai_push\` as a deploy** → It's a "save as draft", not a publish. Live traffic is unaffected until \`manage_drafts(publish, confirm:true)\`. Don't ask the user "ready to ship?" before push — push freely, only ask before publish.
-- **Frontend dev server + remote media** → media files are auto-uploaded to the storage bucket on deploy but \`vite dev\` doesn't proxy to it. 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.local\` is auto-managed by \`manage_frontend(sync)\`** — when missing, sync writes it for you pointing at the **draft overlay** (\`https://dev-<project_id>.dypai.dev\`) so your local frontend transparently consumes backend drafts. The variable name follows your framework: \`VITE_DYPAI_URL\` for Vite, \`NEXT_PUBLIC_DYPAI_URL\` for Next.js. **Do not overwrite a user-authored \`.env.local\`** — sync respects an existing file. Only create it manually if \`env_file_missing: true\` in the sync response AND you have a reason to deviate.
-
-\`\`\`bash
-# What sync writes (Vite)
-VITE_DYPAI_URL=https://dev-<project_id>.dypai.dev
-
-# What sync writes (Next.js)
-NEXT_PUBLIC_DYPAI_URL=https://dev-<project_id>.dypai.dev
-\`\`\`
+- **Secrets** — credentials never appear in YAML or logs.
+- **Scheduled jobs** — \`schedule_trigger\` endpoints enqueued on startup/deploy. No cron daemon.
+- **NOT automatic**: webhook retries (add explicit \`wait_delay\` + retry in the workflow if needed).
+
+## Top gotchas (the expensive ones)
 
-For **production** the deployed frontend bundle automatically receives the live URL (\`https://<project_id>.dypai.dev\`, no \`dev-\` prefix) injected as a build-time env var by \`manage_frontend(deploy)\` — the user never has to flip URLs by hand. Without an \`.env.local\` the local SDK has no engine to call → every API call fails. It's always the env var, not the code.
+1. **Forgetting \`WHERE user_id = \${current_user_id}\`** — users see each other's data. #1 multi-tenancy bug. The engine does NOT auto-filter. RLS doesn't exist.
+2. **Editing YAML without \`dypai_push\`** — your change is on YOUR DISK only. Local frontend (which points at the draft overlay) keeps serving the old version. Symptom: *"I tested it locally and nothing changed"*. Always push after each meaningful change set.
+3. **Treating \`dypai_push\` as a deploy** — it's "save as draft", not publish. Live traffic is untouched until \`manage_drafts(publish, confirm:true)\`. Push freely, only ask the user before publish.
+4. **\`public\` auth_mode with \`\${current_user_id}\`** — no JWT → placeholder empty → SQL fails or returns wrong data. Use \`jwt\` if you need the user.
+5. **Missing \`return: true\`** — endpoint returns \`null\`. Every path that should produce an HTTP response needs one node with \`return: true\`.
+6. **\`tool_ids\` in YAML instead of \`tools\`** — write \`tools: [name1, name2]\`. \`tool_ids\` bypasses the codec and fails silently in prod.
 
-## Frontend deploy
+→ Longer list of common pitfalls + fixes: \`search_docs("troubleshooting")\`.
 
-\`manage_frontend(operation: deploy, sourceDirectory, project_id, confirm:true)\` → ships the frontend bundle. **Replaces the live site IMMEDIATELY** — no draft stage, no automatic rollback. \`confirm:true\` is REQUIRED; without it the tool returns a \`confirmation_required\` hint (and warns if backend drafts are still pending — you should publish those FIRST so the frontend doesn't call non-existent endpoints).
+## Common app recipes (one-liners)
 
-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).
+- **Auth-gated CRUD**: table with \`user_id UUID\`, jwt endpoints, SQL always filters by \`\${current_user_id}\`, frontend \`<ProtectedRoute>\`.
+- **Admin panel**: endpoints with \`allowed_roles: [admin]\`. Same SQL, no user filter (admin sees all). Promote via \`manage_users(update_role)\`.
+- **AI chat**: single endpoint with \`agent\` node + \`memory_key: "chat:\${current_user_id}"\`. Frontend \`dypai.api.stream()\`.
+- **Payments (Stripe)**: \`stripe\` node for ops. Webhook endpoint with \`trigger.webhook\` + \`stripe_webhook: true\` (auto-verifies signature).
+- **Cron**: \`trigger.schedule: { cron: "0 9 * * *", timezone: "..." }\`. Same workflow syntax as HTTP endpoints.
+- **File upload**: frontend \`dypai.api.upload(endpoint, file)\`. Endpoint = one \`dypai_storage\` node. SDK handles signed-URL PUT.
+- **Live dashboard**: normal endpoint + frontend \`useRealtime(table, { onInsert: refetch })\`.
+- **Multi-tenant**: every row has \`org_id\` or \`user_id\`. Every endpoint filters by \`\${current_user_id}\`.
 
-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.
+→ Full canonical patterns + pitfalls: \`search_docs("workflow patterns")\`.
 
-→ Framework-specific gotchas (Next SSR, Vite, Astro, etc.): \`search_docs("frontend frameworks")\`. Deploy tool operations deep dive: \`search_docs("manage frontend")\`.
+## Frontend essentials
 
-## Other tools
+SDK is pre-configured at \`src/lib/dypai.ts\` (or \`src/dypai.ts\`). Import \`dypai\` from there. Every method returns \`{ data, error }\` — never throws.
 
-- \`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 the storage bucket, registers. Max 100MB/file. → \`search_docs("file storage")\`.
-- \`manage_drafts\` — universal draft-and-publish workflow. \`dypai_push\` always saves changes as drafts; use \`list\` to show the user what's pending, \`publish\` (confirm:true) to apply them atomically to live, \`discard\` to throw them away. Test pending drafts with \`dypai_test_endpoint(mode:'draft')\` before publishing.
+- **API**: \`dypai.api.get(name)\`, \`.post(name, body)\`, \`.put()\`, \`.delete()\`, \`.upload(name, file)\`, \`.stream(name, body)\`.
+- **Auth**: \`dypai.auth.signInWithPassword()\`, \`.signUp()\`, \`.signOut()\`, \`.getSession()\`. **Never** create login/signup workflows — auth is built-in.
+- **Hooks**: \`useAuth\`, \`useEndpoint\`, \`useAction\`, \`useUpload\`, \`useRealtime\`, \`<ProtectedRoute>\`.
+- **Rule**: NEVER \`fetch()\` directly — always through the SDK.
 
-## Deep docs — search_docs topic map
+**\`.env.local\` is auto-managed by \`manage_frontend(sync)\`** — when missing, sync writes it pointing at the **draft overlay** (\`https://dev-<project_id>.dypai.dev\`) so local dev transparently consumes backend drafts. Var name: \`VITE_DYPAI_URL\` (Vite) or \`NEXT_PUBLIC_DYPAI_URL\` (Next.js). **Do not overwrite a user-authored \`.env.local\`** — sync respects an existing file. For production, \`manage_frontend(deploy)\` injects the live URL (without \`dev-\`) at build time automatically.
 
-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):
+→ Deep: \`search_docs("sdk reference")\`, \`search_docs("react hooks")\`, \`search_docs("frontend frameworks")\` (Next SSR, Vite, Astro gotchas), \`search_docs("manage frontend")\` (deploy operations).
 
-- **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"
+## Other tools (short hits)
 
-Before writing something you're not 100% sure about → search first. The docs are the detailed truth; this prompt is the map.
+- \`bulk_upsert\` — CSV/JSON → table. Seed data.
+- \`manage_domain\` — custom domains. \`add\` returns CNAME to configure. \`verify\` rechecks DNS/SSL. → \`search_docs("manage domain")\`.
+- \`manage_users\` / \`manage_roles\` — app-level RBAC (better-auth). Create/ban/assign roles.
+- \`manage_schedules\` / \`manage_webhooks\` — pause/resume/history. To change the DEFINITION, edit the YAML and push.
+- \`manage_storage\` — buckets + objects. \`upload_file\` reads local path, signs URL, PUTs, registers. Max 100MB/file. → \`search_docs("file storage")\`.
+- \`manage_drafts\` — universal draft/publish. \`list\` before \`publish\` so the user sees what's shipping. \`discard\` to throw away. Always pair with \`dypai_test_endpoint(mode:'draft')\` before publish.
+- \`manage_database\` — migrations + introspection + multi-statement scripts. \`apply_migration\` for versioned DDL in \`dypai/migrations/\`. \`introspect_*\` for tables/functions/schemas.
+
+→ For any unfamiliar territory: the topic map at the top covers where to dig. When in doubt — search first, code after.
 `
 
 // ── MCP Protocol (JSON-RPC over stdio) ──────────────────────────────────────
@@ -1142,6 +895,20 @@ async function handleRequest(msg) {
             })
           }
 
+          // Pre-flight: block DDL/DML on protected schemas (auth, storage,
+          // system, pg_*, _timescaledb_*). SELECT is always allowed. Failing
+          // here with a guided message is strictly UX — the cloud tool also
+          // enforces the same rules, but a clear message from the local MCP
+          // saves the agent from parsing raw Postgres permission errors.
+          // manage_database runs its own guard internally, so it's NOT
+          // re-validated here.
+          if (name === "execute_sql" && typeof finalArgs?.sql === "string") {
+            const v = validateSql(finalArgs.sql)
+            if (!v.ok) {
+              throw new Error(formatValidationError(v))
+            }
+          }
+
           // 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
@@ -1164,7 +931,9 @@ async function handleRequest(msg) {
           result = enrichSuccess(name, raw)
 
           // Side effect: if the user ran schema-changing DDL via execute_sql,
-          // re-dump dypai/schema.sql so the validator stays in sync.
+          // re-dump dypai/schema.sql so the validator stays in sync. The
+          // helper is a no-op for non-DDL. manage_database handles its own
+          // schema refresh for apply_migration / execute_script operations.
           if (name === "execute_sql") {
             const refresh = await maybeRefreshSchemaAfterExecuteSql(args || {}, result)
             if (refresh.refreshed) {