@dypai-ai/mcp 1.5.7 → 1.5.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dypai-ai/mcp",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "description": "DYPAI MCP Server — AI agent toolkit for building and deploying full-stack apps",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -115,8 +115,38 @@ const REMOTE_TOOLS = [
   // ── Project ───────────────────────────────────────────────────────────────
   { name: "list_projects", description: "Lists all projects you have access to across your organizations. Returns project id, name, description, organization, subscription plan, and status. Use this as the first step to discover which projects are available, then pass project_id to other tools.", inputSchema: { type: "object", properties: { organization_id: { type: "string", description: "Optional. Filter projects by organization UUID." } }, required: [] } },
   { name: "get_project", description: "Gets detailed information about a specific project. Returns project name, description, organization, plan, status, engine URL, frontend slug, and timestamps.", inputSchema: { type: "object", properties: { project_id: { type: "string" } }, required: ["project_id"] } },
-  { name: "list_ai_models", description: "List only the DYPAI Managed AI models that are active for a project. Returns the project-gated OpenRouter model catalog, monthly included AI credits, monthly hard cap, RPM limit, max output tokens, active/available counts, and the exact node parameters to use. Call this before creating or editing an AI Agent node with DYPAI Managed models. Agents must not invent or use inactive model ids. Use provider='openrouter' and do NOT set credential_id; DYPAI uses the platform OpenRouter key and bills usage to the organization.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "Project UUID whose plan and Model Gateway settings determine the active Managed AI catalog." } }, required: ["project_id"] } },
-  { name: "create_project", description: "Create a new DYPAI project (free plan). Creates a full project with database, engine, GitHub repo, and frontend hosting. BLOCKS by default until provisioning finishes (~60s typical, 120s max) — when it returns, the project_id is ready to use with execute_sql, endpoint tools, etc. Pass wait_until_ready:false for batch flows.\n\nName collision: if another project in the same org already uses the name (case-insensitive), returns {error:'name_taken', existing_project_id, suggestions:[...]}. Pick a different name or use the existing project.\n\nIMPORTANT: before calling, check for a matching template with `search_project_templates`. Passing a `template_slug` drops in a ready-made schema + endpoints + UI that cover 70% of common app types. Only create a blank project if nothing matches.", inputSchema: { type: "object", properties: { name: { type: "string", description: "Project name (e.g. 'My Veterinary App')" }, organization_id: { type: "string", description: "Optional. Uses default org if omitted." }, description: { type: "string" }, template_slug: { type: "string", description: "RECOMMENDED. Project template slug to start from (e.g. 'clinic', 'gym', 'waitlist', 'blank'). Always call search_project_templates first to find the best match." }, wait_until_ready: { type: "boolean", description: "If true (default), blocks until provisioning completes and the project is ready for all operations. If false, returns immediately with status='provisioning' — caller must poll get_project before using.", default: true } }, required: ["name"] } },
+  {
+    name: "manage_project_access_profile",
+    description: `Read or update the project's product access profile.
+
+Use this when you know what kind of app is being built:
+- private/admin tool: app_visibility='private', auth_scope='admin_only', has_admin_area=true, root_requires_auth=true
+- public landing with admin panel: app_visibility='mixed', auth_scope='admin_only', has_public_area=true, has_admin_area=true
+- customer/user portal: app_visibility='private' or 'mixed', auth_scope='end_users' or 'admin_and_end_users', has_end_user_accounts=true
+- public-only site: app_visibility='public', auth_scope='none', role_model='none', root_requires_auth=false
+
+This stores classification metadata only. It does not create users, roles, login UI, tables, endpoints, or publish anything.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "string", description: "Project UUID. Required for user tokens; auto-detected for project tokens." },
+        operation: { type: "string", enum: ["get", "update"], description: "Read or update the project access classification." },
+        app_visibility: { type: "string", enum: ["public", "private", "mixed"], description: "Public surface of the app." },
+        auth_scope: { type: "string", enum: ["none", "admin_only", "internal_users", "end_users", "admin_and_end_users"], description: "Who needs authentication." },
+        role_model: { type: "string", enum: ["none", "single_role", "multi_role"], description: "Whether the app has no roles, one role, or multiple roles." },
+        has_admin_area: { type: "boolean", description: "Whether the app should include an admin/private management area." },
+        has_public_area: { type: "boolean", description: "Whether the app should include pages usable without login." },
+        has_end_user_accounts: { type: "boolean", description: "Whether non-admin end users have their own accounts." },
+        root_requires_auth: { type: "boolean", description: "Whether the root route should require login." },
+        metadata_patch: { type: "object", description: "Optional non-sensitive notes to merge into access_metadata. Sensitive-looking keys are dropped." },
+        reason: { type: "string", description: "Short reason for the update." },
+        source: { type: "string", description: "Optional caller label. Defaults to mcp." },
+      },
+      required: ["operation"],
+    },
+  },
+  { name: "list_ai_models", description: "List only the DYPAI Managed AI models that are active for a project. Returns the project-gated OpenRouter model catalog priced in AI Credits per 1M tokens, RPM limit, max output tokens, active/available counts, billing metadata, and the exact node parameters to use. Call this before creating or editing an AI Agent node with DYPAI Managed models. Agents must not invent or use inactive model ids. Use provider='openrouter' and do NOT set credential_id; DYPAI uses the platform OpenRouter key and deducts usage from the organization's AI Credits.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "Project UUID whose plan and Model Gateway settings determine the active Managed AI catalog." } }, required: ["project_id"] } },
+  { name: "create_project", description: "Create a new DYPAI project (free plan). Creates a full project with database, engine, GitHub repo, and frontend hosting. BLOCKS by default until provisioning finishes (~60s typical, 120s max) — when it returns, the project_id is ready to use with execute_sql, endpoint tools, etc. Pass wait_until_ready:false for batch flows.\n\nName collision: if another project in the same org already uses the name (case-insensitive), returns {error:'name_taken', existing_project_id, suggestions:[...]}. Pick a different name or use the existing project.\n\nProject limits are enforced by the DYPAI API at organization/workspace scope according to the workspace plan. If it returns {error:'project_limit_reached'}, do not retry create_project; show list_projects for that organization and ask the user to reuse, archive/pause, upgrade the workspace to Pro, or add capacity.\n\nIMPORTANT: before calling, check for a matching template with `search_project_templates`. Passing a `template_slug` drops in a ready-made schema + endpoints + UI that cover 70% of common app types. Use built-in bases when appropriate: `private-admin` for private internal tools, `user-accounts` for apps with signup/login users, `landing-admin` for public landing plus admin, and `blank` only when no base fits.", inputSchema: { type: "object", properties: { name: { type: "string", description: "Project name (e.g. 'My Veterinary App')" }, organization_id: { type: "string", description: "Optional. Uses default org if omitted." }, description: { type: "string" }, template_slug: { type: "string", description: "RECOMMENDED. Project template slug to start from (e.g. 'clinic', 'gym', 'private-admin', 'user-accounts', 'landing-admin', 'blank'). Always call search_project_templates first to find the best match." }, wait_until_ready: { type: "boolean", description: "If true (default), blocks until provisioning completes and the project is ready for all operations. If false, returns immediately with status='provisioning' — caller must poll get_project before using.", default: true } }, required: ["name"] } },
   { name: "get_app_credentials", description: "Lists available credentials in the current application. Returns API keys, anon key, service role key, and engine URL needed for SDK configuration.", inputSchema: { type: "object", properties: { project_id: { type: "string" } }, required: [] } },
 
   // ── Database ──────────────────────────────────────────────────────────────
@@ -437,15 +467,16 @@ endpoint YAML and \`dypai_push\`. This tool does NOT modify the definition.`,
   // ── Observability ─────────────────────────────────────────────────────────
   {
     name: "search_logs",
-    description: "Search recent errors and warnings for the current project. ALWAYS call this FIRST when the user reports any error, bug, or 'this isn't working' — don't guess from the code; check what actually broke. Returns a unified, time-ordered list mixing failed workflow executions and warn/error log lines from the engine. Defaults to the last 24h. Data retention: 7 days.\n\nWorkflow:\n  1) Call with no args (or just `since:'1h'`) → see recent failures.\n  2) Pick the relevant entry → call again with `endpoint` + tighter `query` to narrow down.\n  3) For the full step-by-step debug trace of a specific failure, set `include_trace:true` (response is much larger; you'll likely get a `file_path` to read the full JSON from disk).\n\nUse `environment:'live'` when investigating a production user complaint (excludes draft test runs). Use `environment:'draft'` when the user says 'I just tested X locally and it failed' (their local UI hits the draft overlay).",
+    description: "Search recent backend activity for the current project. ALWAYS call this FIRST when the user reports any error, bug, 'this isn't working', or a click/action that appears to do nothing — don't guess from the code; check what actually happened. Returns a unified, time-ordered list mixing workflow executions and warn/error log lines from the engine. Defaults to recent problems only (`status:'problem'`) over the last 24h. Raw data is retained 7 days and cleaned automatically by metrics-db retention policies.\n\nWorkflow:\n  1) Call with no args (or just `since:'1h'`) → see recent failures/warnings.\n  2) If the user says a button/action did nothing and there is no visible error → call `search_logs({ since:'30m', status:'all', endpoint:'...' })` or `status:'success'` to see successful backend calls too.\n  3) Pick the relevant entry → call again with `endpoint` + tighter `query` to narrow down.\n  4) For the full step-by-step debug trace of a specific failure, set `include_trace:true` (response is much larger; you'll likely get a `file_path` to read the full JSON from disk).\n\nUse `environment:'live'` when investigating a production user complaint (excludes draft overlay test runs). Use `environment:'draft'` when the user says 'I just tested X locally and it failed' (their local UI hits the draft overlay).",
     inputSchema: {
       type: "object",
       properties: {
         project_id: { type: "string", description: "Project UUID. Auto-detected for project tokens." },
-        query: { type: "string", description: "Optional substring to match (case-insensitive) in error messages and log lines. e.g. 'timeout', 'OpenAI', 'permission denied'." },
+        query: { type: "string", description: "Optional substring to match (case-insensitive) in messages, endpoint names, statuses, request IDs, and log lines. e.g. 'timeout', 'OpenAI', 'permission denied'." },
         endpoint: { type: "string", description: "Optional endpoint name filter (e.g. 'create-order')." },
         since: { type: "string", default: "24h", description: "Time window: relative ('15m', '1h', '24h', '7d') or ISO 8601 timestamp. Default 24h. Hard cap: 7d (retention)." },
-        level: { type: "string", enum: ["error", "warn", "all"], default: "all", description: "Filter by severity. 'error' includes failed/timeout executions + error logs. 'warn' is warning logs. 'all' (default) returns both." },
+        level: { type: "string", enum: ["error", "warn", "all"], default: "all", description: "Filter by severity. 'error' includes failed/timeout executions + error logs. 'warn' returns warning logs only. 'all' returns every severity allowed by `status`." },
+        status: { type: "string", enum: ["problem", "success", "error", "timeout", "all"], default: "problem", description: "Workflow execution status filter. 'problem' (default) keeps the old lightweight behavior: failed/timed-out executions plus warn/error logs. 'success' shows successful executions only. 'all' shows successful and failed executions plus warn/error logs. Use 'success' or 'all' when debugging a user action that produced no visible backend error." },
         environment: { type: "string", enum: ["live", "draft", "all"], default: "all", description: "live = production traffic only (excludes draft overlay test runs). draft = only requests through dev-<project_id>.dypai.dev. all = both. Use 'live' for real user bug reports." },
         limit: { type: "integer", default: 50, minimum: 1, maximum: 200, description: "Max items to return. Default 50, max 200." },
         include_trace: { type: "boolean", default: false, description: "Attach the full step-by-step debug trace per failed execution. Verbose — combine with `query`/`endpoint` filters and a low `limit`. If the response gets large, the local proxy writes it to disk and returns a file_path you can Read." }
@@ -456,8 +487,9 @@ endpoint YAML and \`dypai_push\`. This tool does NOT modify the definition.`,
 
   // ── Knowledge ─────────────────────────────────────────────────────────────
   { name: "search_docs", description: "Search DYPAI documentation. Use this when unsure about SDK usage, auth patterns, workflow nodes, or platform features. Returns relevant documentation chunks.", inputSchema: { type: "object", properties: { query: { type: "string", description: "What you want to learn about" } }, required: ["query"] } },
+  { name: "search_design_patterns", description: "Search compact DYPAI UI/design recipes. Use before designing substantial screens.", inputSchema: { type: "object", properties: { query: { type: "string", description: "Design need, with starter/domain/screen/style context when known." }, starter_slug: { type: "string", description: "Optional: private-admin, user-accounts, landing-admin, or blank." }, app_type: { type: "string", description: "Optional domain/app type." }, screen_type: { type: "string", description: "Optional screen/workflow." }, visual_style: { type: "string", description: "Optional style." }, category: { type: "string", description: "Optional category." }, limit: { type: "integer", default: 3, minimum: 1, maximum: 4 } }, required: ["query"] } },
   { name: "search_workflow_templates", description: "Search workflow templates by description. Returns ready-to-use workflow code for common patterns: CRUD operations, payment gateways, email sending, AI chatbots, data pipelines, etc.", inputSchema: { type: "object", properties: { query: { type: "string", description: "What the workflow should do (e.g. 'send email', 'stripe payment')" }, category: { type: "string", description: "Optional: AI, Database, Payments, Communication, Logic, Storage" } }, required: ["query"] } },
-  { name: "search_project_templates", description: "Search project starter templates by description. Returns template metadata and slugs for starters like clinic, gym, waitlist, blank, auth, or landing.", inputSchema: { type: "object", properties: { query: { type: "string", description: "What kind of project starter you need (e.g. 'gym app', 'landing page', 'auth starter')" }, category: { type: "string", description: "Optional category filter" } }, required: ["query"] } },
+  { name: "search_project_templates", description: "Search project starter templates by description. Returns template metadata and slugs for marketplace templates plus built-in bases: private-admin, user-accounts, landing-admin, and blank.", inputSchema: { type: "object", properties: { query: { type: "string", description: "What kind of project starter you need (e.g. 'gym app', 'private admin dashboard', 'user accounts portal', 'landing plus admin')" }, category: { type: "string", description: "Optional category filter" } }, required: ["query"] } },
 ]
 
 // ── Server Instructions ──────────────────────────────────────────────────────
@@ -486,16 +518,26 @@ First reflex, always:
 
 1. **Acknowledge briefly** what they want to build (one short line, their language).
 2. **\`search_project_templates(query: "<keywords from their request>")\`** — keywords in their language. Templates cover common app types (gym, clinic, waitlist, saas dashboard, etc.).
-3. **Decide: template or blank?** Default is **blank**. A template is only the right pick when the match is OBVIOUS and STRONG:
+3. **Decide: marketplace template, built-in base, or blank.** Marketplace templates are only right when the match is OBVIOUS and STRONG:
    - ✅ User says *"app para mi gimnasio"* + there's \`gym-manager\` (exact domain + feature overlap) → template.
-   - ❌ User says *"algo para gestionar reservas"* + there's \`gym-manager\` (soft match, many interpretations) → **blank**. Don't assume they want the gym's specific schema (classes, memberships, check-ins) — they didn't ask for it.
-   - ❌ User is a dev with a concrete spec (*"crea un proyecto con estas 3 tablas y estos endpoints"*) → **blank**, always. Respect their design.
-   - ❌ No template returned at all → **blank**.
-4. **Call it** → \`create_project(name: "<their name>", template_slug: "<matched_slug>" | "blank")\`.
+   - ❌ User says *"algo para gestionar reservas"* + there's \`gym-manager\` (soft match, many interpretations) → use a built-in base or **blank**. Don't assume they want the gym's specific schema (classes, memberships, check-ins) — they didn't ask for it.
+   - Built-in bases are safe defaults:
+     - private/internal/admin/dashboard/backoffice/business management → \`private-admin\`
+     - end-user signup/login/customer/member portal/marketplace/SaaS accounts → \`user-accounts\`
+     - public landing/marketing site plus private admin → \`landing-admin\`
+     - no clear access pattern or explicitly custom/from scratch → \`blank\`
+   - ❌ User is a dev with a concrete spec (*"crea un proyecto con estas 3 tablas y estos endpoints"*) → usually **blank**, unless they explicitly want one of the built-in bases.
+   - ❌ No marketplace or built-in base fits → **blank**.
+4. **Call it** → \`create_project(name: "<their name>", template_slug: "<matched_slug>" | "private-admin" | "user-accounts" | "landing-admin" | "blank")\`.
    If you went with a template, acknowledge in ONE line what's included so the user can push back: *"Lo arranco con la plantilla X, que trae socios, clases y pagos. ¿Te vale o prefieres algo más simple?"*
    If you went blank, just say: *"Arranco un proyecto en blanco y lo construimos a medida."*
 5. **After \`create_project\`** → ask for an absolute workspace path, then \`dypai_pull\` + \`manage_frontend(sync)\` (see next section).
 
+Before designing substantial UI (app shell, dashboard, login, tables/lists,
+forms, calendars, or domain-specific screens), use \`search_design_patterns\`
+with the app/starter/screen/style context. It returns curated recipes; adapt
+them to the project instead of inventing generic starter UI.
+
 **The template system exists to save time when the fit is obvious, not to force-match every request.** When in doubt → blank is always correct. Iterating up from blank is cheaper than deleting 80% of a mismatched template.
 
 ## The one legit follow-up question
@@ -520,6 +562,34 @@ DYPAI builds the **backend** (DB, auth, API, storage, realtime) for any client.
 
 For everything else, **the stack is decided. Start building.**
 
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# PROJECT ACCESS PROFILE — classify the app once you know the product shape
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+DYPAI projects store a lightweight product access profile: whether the app is
+public, private, mixed, admin-only, internal-user based, end-user-account based,
+single-role, or multi-role. This helps later agents and platform UI reason
+about login, first-run credentials, preview instructions, and route protection.
+
+When you know the product shape, call
+\`manage_project_access_profile(operation:"update", ...)\`. Do this as metadata
+only; it does NOT replace implementing the actual auth UI, roles, protected
+routes, tables, or endpoints.
+
+Defaults:
+- Private/admin app: \`app_visibility:"private"\`, \`auth_scope:"admin_only"\`,
+  \`role_model:"single_role"\`, \`has_admin_area:true\`, \`has_public_area:false\`,
+  \`has_end_user_accounts:false\`, \`root_requires_auth:true\`.
+- Public site with admin panel: \`app_visibility:"mixed"\`,
+  \`auth_scope:"admin_only"\`, \`has_public_area:true\`, \`has_admin_area:true\`,
+  \`root_requires_auth:false\`.
+- User portal / marketplace / SaaS: use \`auth_scope:"admin_and_end_users"\`
+  when both admins and customers log in, \`role_model:"multi_role"\` if there
+  are materially different permissions, and \`has_end_user_accounts:true\`.
+- Public-only landing/docs/blog: \`app_visibility:"public"\`,
+  \`auth_scope:"none"\`, \`role_model:"none"\`, \`has_admin_area:false\`,
+  \`root_requires_auth:false\`.
+
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # BEFORE YOU DO ANYTHING — materialize the project locally
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -689,7 +759,7 @@ Use phrases like:
 Default is **no tool names in user-facing text**.
 
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-# SEARCH BEFORE YOU GUESS — \`search_docs\` is your reference manual
+# SEARCH BEFORE YOU GUESS — \`search_docs\` and \`search_design_patterns\`
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 This prompt is the MAP of the DYPAI platform. The detailed docs live in
@@ -732,6 +802,17 @@ synonym.
 - \`"agent ai"\` — agent node: providers, tools, memory, streaming, tool endpoints
 - \`"javascript code node"\` — custom code escape hatch when native nodes don't fit
 
+### Managed AI Models
+- Before creating or editing any AI Agent node that uses DYPAI Managed AI,
+  always call \`list_ai_models\` first.
+- Use only model IDs from \`list_ai_models.models[].id\`; never invent OpenRouter
+  model IDs.
+- For DYPAI Managed AI, set \`provider: "openrouter"\` and do not set
+  \`credential_id\`; DYPAI uses the platform key server-side.
+- Treat model pricing as AI Credits, using
+  \`input_ai_credits_per_million\` / \`output_ai_credits_per_million\` when you
+  need to explain cost.
+
 ### 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
@@ -800,12 +881,13 @@ Editing files inside \`dypai/\` only changes YOUR DISK. The platform doesn't see
 \`\`\`
 
 Practical consequences — internalize these:
-- **After EVERY meaningful change set, call \`dypai_push\`.** Don't batch a session's worth of edits hoping to push at the end — if you forget, the user tests the local UI and sees the OLD behavior, gets confused, and you waste a debug round-trip blaming the code. The push is cheap, idempotent, and creates ONE draft per resource (subsequent pushes overwrite the draft, not stack new ones).
-- **\`dypai_push\` is the "save" button. It is NOT a publish.** Live traffic is untouched. You can push 20 times in a row without affecting a single user. Tell the user that explicitly when they ask "did it ship?" — push = staged draft, publish = live.
-- **The draft overlay (\`dev-<project_id>.dypai.dev\`) only sees what you've pushed.** A change still on disk is invisible to the local frontend. If the user says "I tested it locally and nothing changed", your first check is "did I run \`dypai_push\` after the last edit?".
+- **Never publish backend changes just to test them.** Backend changes are testable before production: save them to preview, verify with \`dypai_test_endpoint(mode:'draft')\` when possible, then tell the user exactly what to try in preview.
+- **After EVERY meaningful backend change set, call \`dypai_push\`.** Don't batch a session's worth of edits hoping to push at the end — if you forget, the user tests the preview and sees the OLD behavior. The push is cheap, idempotent, and creates ONE preview version per resource (subsequent pushes overwrite the pending preview version, not stack new ones).
+- **\`dypai_push\` is the internal save-to-preview step. It is NOT a production publish.** Live traffic is untouched. You can run it repeatedly without affecting real users. In user-facing prose, say "listo para probar" or "en previsualización", not "pushed" or "draft".
+- **The preview host (\`dev-<project_id>.dypai.dev\`) only sees what you've saved to preview.** A change still only on disk is invisible to the user's preview. If the user says "I tested it and nothing changed", first check whether the backend change was saved to preview after the last edit.
 - **\`dypai_validate\` before \`dypai_push\`** — push runs validate as a pre-flight, but running it explicitly first gives you the lint output without committing. Cheap insurance.
-- **Order during a multi-step feature**: edit → \`dypai_validate\` → \`dypai_push\` → \`dypai_test_endpoint(mode:'draft')\` (or tell the user to test their local UI). Repeat per change. ONLY at the end, when the user signs off, do \`manage_drafts(operation:'list')\` → \`manage_drafts(operation:'publish', confirm:true)\`.
-- **DDL is the exception**: \`execute_sql\` with CREATE / ALTER / DROP TABLE applies to live IMMEDIATELY (no draft stage for schema). Drafts only exist for endpoints / webhooks / crons / realtime policies. Summarize destructive DDL to the user before running it.
+- **Order during a multi-step backend feature**: edit → \`dypai_validate\` → \`dypai_push\` → \`dypai_test_endpoint(mode:'draft')\` (or tell the user to test preview). Repeat per change. ONLY when the user explicitly approves production do \`manage_drafts(operation:'list')\` → \`manage_drafts(operation:'publish', confirm:true)\`.
+- **DDL is the exception**: \`execute_sql\` with CREATE / ALTER / DROP TABLE applies to live IMMEDIATELY (no preview layer for schema). Preview only exists for endpoints / webhooks / crons / realtime policies. Summarize destructive DDL to the user before running it.
 
 ## User intent → tool to call (decision table)
 
@@ -815,13 +897,14 @@ Use this BEFORE picking a tool. If unsure which row matches, ask the user.
 |---|---|---|
 | "Create a new project" | \`search_project_templates\` (find a starter) | \`create_project(template_slug: ...)\` |
 | "Show me what we have" / "I want to work on existing project X" | \`list_projects\` → \`dypai_pull\` (backend) + \`manage_frontend(sync)\` (frontend) | Read \`dypai/\` files + \`src/\` |
+| "This is a private admin app / public site / user portal / multi-role app" | \`manage_project_access_profile(operation:'update')\` | Then implement the actual auth/UI/data behavior normally |
 | "Add/change a backend endpoint, table, cron, webhook, agent, integration" | Edit files in \`dypai/\` | \`dypai_validate\` → \`dypai_push\` |
 | "Publish my backend changes" / "make it live" | \`manage_drafts(operation:'list')\` to show what's pending | \`manage_drafts(operation:'publish', confirm:true)\` |
 | "Test an endpoint before publishing" | \`dypai_test_endpoint(mode:'local')\` (your edits) or \`(mode:'draft')\` (after push) | — |
 | "Test the new endpoint from my local frontend, end-to-end, before publishing" | Tell user: their local frontend already points to \`https://dev-<project_id>.dypai.dev\` (set by \`manage_frontend(sync)\`), which serves drafts on top of live. So after \`dypai_push\` the local UI hits the draft overlay automatically — nothing else to do. | — |
 | "Throw away my backend changes" | \`manage_drafts(operation:'discard', confirm:true)\` | — |
-| "Change the UI / change colors / add a page" | Edit files in \`src/\` | \`manage_frontend(deploy, confirm:true)\` |
-| "Publish the new UI" / "ship the frontend" | \`manage_frontend(deploy, confirm:true)\` | (deploy is the publish — there is no separate step) |
+| "Change the UI / change colors / add a page" | Edit files in \`src/\` | Test locally/with browser when possible. \`manage_frontend(deploy, confirm:true)\` only when the user approves publishing the UI. |
+| "Publish the new UI" / "ship the frontend" | If backend changes are needed by the new UI, publish those backend changes first with explicit approval | Then \`manage_frontend(deploy, confirm:true)\` — deploy is live, not a preview. |
 | "Roll back" | Backend: \`get_endpoint_versions\` then write old code back. Frontend: re-deploy older source. | — |
 | "Upload a file / a CSV / seed data" | \`bulk_upsert\` (data) or \`manage_storage(upload_file)\` (binary) | — |
 | "X is broken" / "I'm getting an error" / "this doesn't work" / "users are reporting Y" | \`search_logs\` FIRST (don't guess from the code) | If a specific failure is found → \`search_logs(include_trace:true, query:'...')\` for the full step-by-step trace |
@@ -847,19 +930,21 @@ User: "Add a /api/list-tasks endpoint that returns the current user's tasks, and
 2. manage_frontend(operation:'sync', ...)        # materialize frontend if not already on disk
 3. # Backend: create the endpoint
    Write dypai/endpoints/list-tasks.yaml         # trigger.http_api auth_mode:jwt + dypai_database query
-4. dypai_validate                                # catch typos before push
-5. dypai_push                                    # stages as draft, NOT live yet
-6. dypai_test_endpoint(name:'list-tasks', mode:'draft', as_user:'<uuid>')   # verify the staged version
-7. manage_drafts(operation:'list')               # show pending changes to user
-8. # ASK USER: "Ready to publish list-tasks to live?"
-9. manage_drafts(operation:'publish', confirm:true)   # backend now live ✅
-10. # Frontend: call the new endpoint from React
-    Edit src/pages/Dashboard.tsx                 # useEndpoint('list-tasks')
-11. # ASK USER: "Ready to deploy the dashboard UI?"
-12. manage_frontend(operation:'deploy', sourceDirectory, confirm:true)   # frontend now live ✅
+4. dypai_validate                                # catch typos before saving to preview
+5. dypai_push                                    # saves to preview, NOT production
+6. dypai_test_endpoint(endpoint:'list-tasks', mode:'draft', as_user:'<user_id>')
+   # verifies the preview version; do NOT publish just to test
+7. # Frontend: call the new endpoint from React
+   Edit src/pages/Dashboard.tsx                  # useEndpoint('list-tasks')
+8. # Test locally/browser if available. Then tell the user in plain language:
+   # "Ya está listo para probar. Abre la previsualización y revisa la lista de tareas. Todavía no está publicado para tus usuarios."
+9. # ONLY after the user confirms it is good:
+   manage_drafts(operation:'list')               # internal: inspect what will publish
+10. manage_drafts(operation:'publish', confirm:true)  # backend live after explicit approval
+11. manage_frontend(operation:'deploy', sourceDirectory, confirm:true)  # frontend live after explicit approval
 \`\`\`
 
-**Order matters**: publish backend BEFORE deploying frontend. Otherwise the new UI calls an endpoint that doesn't exist on live yet → 404s for users. The \`manage_frontend(deploy)\` confirmation hint will warn you if backend drafts are still pending.
+**Testing rule**: never publish backend changes just to test them. Backend can be verified from the preview version. **Production order rule**: when you are truly publishing a full-stack change, publish backend BEFORE deploying the frontend; otherwise the live UI may call backend functionality that is not live yet.
 
 ## Debugging user-reported errors — \`search_logs\` is your starting point
 
@@ -876,10 +961,16 @@ User: "Add a /api/list-tasks endpoint that returns the current user's tasks, and
    # Did they say "production users are reporting..."?
    #   → add environment: "live"    (excludes their own draft test runs)
 
-3. # Found the relevant entry? Narrow down:
+3. # Did they say "I clicked the button and it disappeared / nothing happened"
+   # and the error scan is empty?
+   search_logs({ since: "30m", status: "all", endpoint: "<likely-endpoint>" })
+   → This shows successful executions too, so you can tell whether the backend
+     was called, returned 200, was slow, or was never reached.
+
+4. # Found the relevant entry? Narrow down:
    search_logs({ endpoint: "create-order", query: "stripe", since: "1h" })
 
-4. # For the full step-by-step trace of one specific failure:
+5. # For the full step-by-step trace of one specific failure:
    search_logs({
      endpoint: "create-order",
      query: "<a unique substring from the error message>",
@@ -890,12 +981,12 @@ User: "Add a /api/list-tasks endpoint that returns the current user's tasks, and
      and returns a \`file_path\`. Read that file with the Read tool ONLY
      when you need fields beyond the inline summary.
 
-5. # Now you know exactly which node failed and why → fix the code.
+6. # Now you know exactly which node failed, succeeded, or was never called → fix the code.
 \`\`\`
 
 ### What \`search_logs\` returns
 
-Each item has \`type\` (\`execution_failed\` | \`log\`), \`level\` (\`error\` | \`warn\`), \`time\`, \`endpoint\`, \`message\`, and \`environment\` (\`live\` | \`draft\` | null for legacy rows). Failed executions also include \`status\` (\`error\` | \`timeout\`) and \`duration_ms\`. With \`include_trace:true\` they also include \`trace\` — a per-node log of inputs, outputs, errors, and stacks.
+Each item has \`type\` (\`execution\` | \`execution_failed\` | \`log\`), \`level\` (\`info\` | \`error\` | \`warn\`), \`time\`, \`endpoint\`, \`message\`, and \`environment\` (\`live\` | \`draft\` | null for legacy rows). Workflow executions include \`status\` (\`success\` | \`error\` | \`timeout\`) and \`duration_ms\`. With \`include_trace:true\`, failed executions can include \`trace\` — a per-node log of inputs, outputs, errors, and stacks.
 
 ### Common pitfalls
 
@@ -944,6 +1035,7 @@ Mental translations: "edge function" → workflow with one code node; "cron" →
 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.
+7. **Putting workflow placeholders inside \`javascript_code.code\`** — code is raw JavaScript, so JS template literals like \`\${where.join(" AND ")}\` are safe and not rendered by DYPAI. Pass workflow values via \`input_data\`, \`ctx.nodes\`, \`ctx.user\`, or \`ctx.env\`; do not write \`\${input.email}\` inside code or set \`code\` from another node output.
 
 → Longer list of common pitfalls + fixes: \`search_docs("troubleshooting")\`.
 

package/src/tools/frontend.js

@@ -32,7 +32,7 @@ export const manageFrontendTool = {
     "AFTER SYNC: .env is gitignored so it's NOT included in the download. If the target directory has no .env, the response sets `env_file_missing: true` and adds a `next_steps` line with the exact VITE_DYPAI_URL / NEXT_PUBLIC_DYPAI_URL value to write. Follow it — without .env the SDK can't reach the engine.\n" +
     "  - deploy: Upload source files from a local directory and queue a build. **DESTRUCTIVE: replaces the LIVE site immediately, no draft stage, no rollback button.** " +
     "Requires `confirm: true` — without it the tool returns a confirmation_required hint instead of deploying. " +
-    "If backend drafts are pending, the hint includes a warning to publish backend FIRST (otherwise the new frontend may call endpoints that don't exist yet). " +
+    "If backend drafts are pending, the hint warns that publishing the frontend is a live production action; only publish backend FIRST when the user has explicitly approved going live. Do NOT publish backend just to test it — use preview/draft testing instead. " +
     "Returns immediately with build_status=\"queued\" — poll with `build_status` until \"success\" or \"failure\". " +
     "The response includes `build_quota` with remaining monthly build minutes. If minutes_remaining is low, tell the user. If 0, DO NOT retry — suggest upgrading the plan.\n" +
     "  - status: Current live deploy info (URL, last deploy time, size).\n" +
@@ -41,7 +41,7 @@ export const manageFrontendTool = {
     "  - list_deployments: Recent deploy history (status, commit, duration, URL).\n" +
     "  - logs: Build logs for a specific deployment (needs deployment_id from list_deployments).\n\n" +
     "Related: `dypai_pull` brings BACKEND state (YAML endpoints, SQL, prompts). The two are independent — run both when starting fresh on a full-stack project.\n\n" +
-    "Order rule when both backend AND frontend changed: 1) dypai_push (saves backend as draft) → 2) manage_drafts(publish, confirm:true) → 3) manage_frontend(deploy, confirm:true). Inverting steps 2 and 3 may serve a frontend that calls non-existent endpoints.",
+    "Testing rule: backend changes can be tested in preview after dypai_push; do NOT publish backend just to test. Production order rule when both backend AND frontend changed and the user approved going live: 1) publish backend drafts with manage_drafts(publish, confirm:true) → 2) deploy frontend with manage_frontend(deploy, confirm:true). Inverting production order may serve a live frontend that calls backend functionality not live yet.",
 
   inputSchema: {
     type: "object",
@@ -117,7 +117,7 @@ export const manageFrontendTool = {
               const draftsTotal = draftsResult?.total || 0
               if (draftsTotal > 0) {
                 warnings.push(
-                  `${draftsTotal} backend draft(s) pending. Publish them BEFORE deploying the frontend with manage_drafts(operation:'publish', confirm:true) — otherwise the new frontend may call endpoints that don't exist on live yet.`,
+                  `${draftsTotal} backend preview change(s) pending. This frontend deploy is LIVE. Only publish the backend first if the user explicitly approved production; for testing, keep backend in preview and test without deploying live frontend.`,
                 )
               }
             } catch {

package/src/tools/scaffold.js

@@ -20,7 +20,8 @@ Scaffolds a project directory with:
 - .env with engine URL
 
 Use search_project_templates first to find available templates, then pass the template slug here.
-Or use "blank" for an empty starter project.`,
+Use "private-admin" for private internal tools, "user-accounts" for apps with signup/login users,
+"landing-admin" for public landing plus admin, or "blank" only when no base fits.`,
 
   inputSchema: {
     type: "object",
@@ -35,7 +36,7 @@ Or use "blank" for an empty starter project.`,
       },
       template: {
         type: "string",
-        description: 'Template slug (e.g. "clinic", "gym", "blank"). Use search_project_templates to find available templates.',
+        description: 'Template slug (e.g. "clinic", "gym", "private-admin", "user-accounts", "landing-admin", "blank"). Use search_project_templates to find available templates.',
         default: "blank",
       },
     },

package/src/tools/search-logs-offload.js

@@ -130,6 +130,7 @@ export function maybeOffloadSearchLogs(result) {
         project_id: result.project_id,
         since: result.since,
         level: result.level,
+        status: result.status,
         environment: result.environment,
         endpoint: result.endpoint,
         query: result.query,

package/src/tools/sync/push.js

@@ -524,7 +524,7 @@ export const dypaiPushTool = {
       next_step: errors.length
         ? "Fix the offending YAMLs and push again."
         : draftCount > 0
-          ? `${draftCount} change(s) saved as draft(s) — they're not live yet. Review with manage_drafts(operation:'list'), verify with dypai_test_endpoint(mode:'draft', endpoint:'<name>'), then publish with manage_drafts(operation:'publish', confirm:true) (or discard with manage_drafts(operation:'discard', confirm:true) to throw them away).`
+          ? `${draftCount} change(s) saved to preview — they're not live yet. Verify with dypai_test_endpoint(mode:'draft', endpoint:'<name>') or ask the user to test the preview. Publish with manage_drafts(operation:'publish', confirm:true) ONLY after explicit approval.`
           : changedNames.length
             ? `Test changed endpoint(s) with dypai_test_endpoint: ${changedNames.slice(0, 3).join(", ")}${changedNames.length > 3 ? "…" : ""}`
             : undefined,

package/src/tools/sync/test-endpoint.js

@@ -361,6 +361,9 @@ export const dypaiTestEndpointTool = {
       data: input,
       trace_mode,  // used by the local MCP enrichment layer
     }
+    if (mode === "local") execArgs.draft_mode = true
+    if (mode === "draft") execArgs.draft_mode = true
+    if (mode === "live") execArgs.draft_mode = false
     if (as_user) execArgs.impersonated_user_id = as_user
 
     // Build a compact source-meta block for the response so the agent can see

package/src/tools/sync/validate.js

@@ -8,6 +8,7 @@
  *   - `credential: foo` pointing to a credential that doesn't exist remotely
  *   - Agent `tools: [foo]` pointing to endpoints that aren't tools
  *   - SQL queries referencing tables that don't exist in schema.sql
+ *   - dypai_storage/static storage bucket references that don't exist remotely
  *
  * Returns a list of diagnostics with severity + fix_hint. Non-zero errors
  * mean push will refuse (unless skip_validation is passed).
@@ -179,6 +180,44 @@ function* walkStrings(node, path = "") {
   }
 }
 
+const BUCKET_LOC_RE = /(?:^|\.)(?:bucket|bucket_name|bucketName|storage_bucket|storageBucket)$/
+const STATIC_BUCKET_RE = /^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$/
+
+function isStaticBucketName(value) {
+  const trimmed = String(value || "").trim()
+  if (!trimmed || trimmed.includes("${") || trimmed.includes("{{")) return false
+  return STATIC_BUCKET_RE.test(trimmed)
+}
+
+function collectStorageBucketRefs(entry, endpoint, file) {
+  const refs = new Map()
+  const add = (bucket, loc) => {
+    const name = String(bucket || "").trim()
+    if (!isStaticBucketName(name)) return
+    refs.set(`${name}|${loc}`, { bucket: name, endpoint, file, loc })
+  }
+
+  for (const { path, value } of walkStrings(entry.doc)) {
+    if (BUCKET_LOC_RE.test(path)) add(value, path)
+
+    // JS helper pattern from workflow code files/inline code:
+    // storage.upload("documents", ...), storage.read("documents", ...), etc.
+    if (/(^|\.|])code$/.test(path)) {
+      const re = /\bstorage\.(?:upload|read|list|getUrl|delete)\(\s*["']([a-z0-9][a-z0-9-]{1,61}[a-z0-9])["']/g
+      let m
+      while ((m = re.exec(value)) !== null) add(m[1], path)
+    }
+  }
+
+  for (const [filePath, content] of Object.entries(entry.fileMap || {})) {
+    const re = /\bstorage\.(?:upload|read|list|getUrl|delete)\(\s*["']([a-z0-9][a-z0-9-]{1,61}[a-z0-9])["']/g
+    let m
+    while ((m = re.exec(content)) !== null) add(m[1], filePath)
+  }
+
+  return [...refs.values()]
+}
+
 /** Extract all ${...} placeholder expressions from a string. */
 function extractPlaceholders(s) {
   const out = []
@@ -188,6 +227,13 @@ function extractPlaceholders(s) {
   return out
 }
 
+function isRawCodePlaceholderSource(source, loc) {
+  if (source === "file") {
+    return loc.startsWith("code/") || /\.(js|ts|py)$/.test(loc)
+  }
+  return /(^|\.|])code$/.test(loc)
+}
+
 /**
  * Extract the first identifier (a-z, A-Z, _, 0-9 — JS-ident shape) from the
  * head of an expression, ignoring any trailing template filter or coalesce
@@ -289,6 +335,31 @@ const LEGACY_OPS_THAT_USE_TABLE_FIELD = new Set([
   "select", "insert", "update", "delete", "upsert", "aggregate",
 ])
 
+function nodeParams(node) {
+  return node?.parameters && typeof node.parameters === "object" && !Array.isArray(node.parameters)
+    ? node.parameters
+    : null
+}
+
+function nodeField(node, params, key) {
+  return node?.[key] ?? params?.[key]
+}
+
+function lookupFileMapContent(fileMap, ref) {
+  if (!fileMap || typeof ref !== "string" || !ref.trim()) return ""
+  const key = ref.trim()
+  return fileMap[key] || fileMap[key.replace(/^dypai\//, "")] || fileMap[`dypai/${key}`] || ""
+}
+
+function collectMissingTableCandidates(ctx, referencedTables, endpoint, file) {
+  if (!ctx.schemaTables) return
+  for (const table of referencedTables) {
+    if (!ctx.schemaTables.has(table)) {
+      ctx.suspectedMissingTables.push({ table, endpoint, file })
+    }
+  }
+}
+
 // ─── Rules ──────────────────────────────────────────────────────────────────
 
 function ruleUsesJwt(trigger) {
@@ -307,17 +378,24 @@ function validateEndpoint(entry, ctx) {
 
   const jwt = ruleUsesJwt(doc.trigger)
 
-  // Collect all strings INCLUDING file contents (query_file, system_prompt_file, code_file)
+  // Collect all template-rendered strings, including query_file and prompts.
+  // Raw code is intentionally skipped: javascript_code.code/code_file may
+  // contain normal JS template literals such as `${where.join(" AND ")}`.
   const sources = []
   for (const { path, value } of walkStrings(doc)) {
+    if (isRawCodePlaceholderSource("yaml", path)) continue
     sources.push({ source: "yaml", loc: path, value })
   }
   for (const [filePath, content] of Object.entries(fileMap || {})) {
+    if (isRawCodePlaceholderSource("file", filePath)) continue
     sources.push({ source: "file", loc: filePath, value: content })
   }
 
   // Collect SQL tables referenced (before checking each individually)
   const referencedTables = new Set()
+  for (const ref of collectStorageBucketRefs(entry, name, file)) {
+    ctx.suspectedStorageBuckets.push(ref)
+  }
 
   // Aggregate missing input.X refs across the whole endpoint so we emit ONE
   // diagnostic per endpoint instead of N (an endpoint with 11 stray refs
@@ -457,23 +535,6 @@ function validateEndpoint(entry, ctx) {
     }
   }
 
-  // --- SQL table existence (if schema.sql available) ---
-  // Defer the actual error emission to runValidation: it batch-checks all
-  // missing tables against the remote in ONE query before deciding what's
-  // a real error vs a stale-local-schema. We just collect the misses here
-  // along with enough context for runValidation to emit per-endpoint errors.
-  if (ctx.schemaTables) {
-    for (const table of referencedTables) {
-      if (!ctx.schemaTables.has(table)) {
-        ctx.suspectedMissingTables.push({
-          table,
-          endpoint: name,
-          file,
-        })
-      }
-    }
-  }
-
   // --- Per-node catalog-based validation (unknown type, missing/unknown params) ---
   for (const node of doc.workflow?.nodes || []) {
     if (!node || typeof node !== "object") continue
@@ -504,30 +565,35 @@ function validateEndpoint(entry, ctx) {
 
     // dypai_database — coherence checks for the new canonical operations.
     if (nodeType === "dypai_database") {
-      const op = node.operation
+      const params = nodeParams(node)
+      const op = nodeField(node, params, "operation")
+      const table = nodeField(node, params, "table") ?? nodeField(node, params, "table_name")
+      const query = nodeField(node, params, "query")
+      const queryFile = nodeField(node, params, "query_file")
+      const insertValue = nodeField(node, params, "insert")
+      const updateValue = nodeField(node, params, "update")
+      const deleteValue = nodeField(node, params, "delete")
+      const whereValue = nodeField(node, params, "where")
 
       // Extract referenced tables from real SQL fields ONLY. Doing this here
       // (instead of in the generic walkStrings pass) eliminates the class of
       // false positive where a prompt/comment/label happens to contain words
       // like "INSERT" or "SELECT". Also covers `mutation` (table: <name>)
       // since that's a guaranteed table reference.
-      if (op === "query" || (op && LEGACY_OPS_THAT_USE_QUERY.has(op))) {
-        const sqlText = typeof node.query === "string" ? node.query : ""
-        if (sqlText) {
-          for (const t of extractSqlTables(sqlText)) referencedTables.add(t)
-        }
+      const sqlTexts = []
+      if (typeof query === "string" && query.trim()) sqlTexts.push(query)
+      const queryFileSql = lookupFileMapContent(fileMap, queryFile)
+      if (queryFileSql) sqlTexts.push(queryFileSql)
+      for (const sqlText of sqlTexts) {
+        for (const t of extractSqlTables(sqlText)) referencedTables.add(t)
       }
-      if (op === "mutation" && typeof node.table === "string") {
-        referencedTables.add(node.table)
+      if (op === "mutation" && typeof table === "string") {
+        referencedTables.add(table)
       }
       // Legacy ops like `select` / `insert` / `update` / `delete` use `table:`
       // as the target table directly.
-      if (op && LEGACY_OPS_THAT_USE_TABLE_FIELD.has(op) && typeof node.table === "string") {
-        referencedTables.add(node.table)
-      }
-      // Resolved query_file content also counts as SQL (loaded by the codec).
-      if (typeof node.query === "string" && node.query.length > 0) {
-        for (const t of extractSqlTables(node.query)) referencedTables.add(t)
+      if (op && LEGACY_OPS_THAT_USE_TABLE_FIELD.has(op) && typeof table === "string") {
+        referencedTables.add(table)
       }
       const LEGACY_OPS = new Set(["select", "insert", "update", "delete", "upsert", "aggregate", "copy_to", "custom_query"])
       if (op && LEGACY_OPS.has(op)) {
@@ -549,7 +615,7 @@ function validateEndpoint(entry, ctx) {
       // Fields like `query`, `query_file`, `params` belong to `operation: query`
       // and are silently ignored here — surface as ERROR so the agent reroutes.
       if (op === "mutation") {
-        if (!node.table) {
+        if (!table) {
           diagnostics.push({
             severity: "error",
             rule: "mutation_missing_table",
@@ -558,9 +624,9 @@ function validateEndpoint(entry, ctx) {
             fix_hint: `Add 'table: <name>'. mutation also needs exactly one of: insert / update / delete.`,
           })
         }
-        const wantsInsert = node.insert !== undefined && node.insert !== null
-        const wantsUpdate = node.update !== undefined && node.update !== null
-        const wantsDelete = node.delete === true
+        const wantsInsert = insertValue !== undefined && insertValue !== null
+        const wantsUpdate = updateValue !== undefined && updateValue !== null
+        const wantsDelete = deleteValue === true
         const opCount = [wantsInsert, wantsUpdate, wantsDelete].filter(Boolean).length
         if (opCount === 0) {
           diagnostics.push({
@@ -582,7 +648,7 @@ function validateEndpoint(entry, ctx) {
         if (wantsUpdate || wantsDelete) {
           // `where: {}` is just as dangerous as omitting `where:` entirely — both
           // produce an unconstrained UPDATE/DELETE in the engine.
-          const whereVal = node.where
+          const whereVal = whereValue
           const whereIsEmpty =
             whereVal === undefined ||
             whereVal === null ||
@@ -603,7 +669,7 @@ function validateEndpoint(entry, ctx) {
         // Foreign fields that belong to `operation: query`
         const QUERY_ONLY = ["query", "query_file", "params"]
         for (const k of QUERY_ONLY) {
-          if (node[k] !== undefined) {
+          if (node[k] !== undefined || params?.[k] !== undefined) {
             diagnostics.push({
               severity: "error",
               rule: "mutation_with_query_field",
@@ -620,7 +686,7 @@ function validateEndpoint(entry, ctx) {
       // Fields like `table`, `insert`, `update`, `delete`, `where`, `on_conflict`,
       // `returning` belong to `operation: mutation` and are ignored here.
       if (op === "query") {
-        if (!node.query && !node.query_file) {
+        if (!query && !queryFile) {
           diagnostics.push({
             severity: "error",
             rule: "query_missing_sql",
@@ -630,7 +696,10 @@ function validateEndpoint(entry, ctx) {
           })
         }
         const MUTATION_ONLY = ["table", "insert", "update", "delete", "where", "on_conflict", "returning"]
-        const foreign = MUTATION_ONLY.filter(k => node[k] !== undefined && node[k] !== false)
+        const foreign = MUTATION_ONLY.filter(k => {
+          const value = node[k] ?? params?.[k]
+          return value !== undefined && value !== false
+        })
         if (foreign.length > 0) {
           diagnostics.push({
             severity: "error",
@@ -855,6 +924,11 @@ function validateEndpoint(entry, ctx) {
     }
   }
 
+  // --- SQL table existence (if schema.sql available) ---
+  // Defer actual error emission to runValidation: it batch-checks all missing
+  // tables against the remote before deciding whether local schema.sql is stale.
+  collectMissingTableCandidates(ctx, referencedTables, name, file)
+
   // --- Credential references ---
   for (const node of doc.workflow?.nodes || []) {
     if (!node || typeof node !== "object") continue
@@ -982,14 +1056,15 @@ function validateEndpoint(entry, ctx) {
     for (const node of allNodes) {
       const nodeType = node?.type ?? node?.node_type
       if (nodeType !== "dypai_database") continue
-      const op = node.operation
+      const params = nodeParams(node)
+      const op = nodeField(node, params, "operation")
       let writeKind = null
       if (op === "mutation") {
-        if (node.insert !== undefined && node.insert !== null) writeKind = "INSERT"
-        else if (node.update !== undefined && node.update !== null) writeKind = "UPDATE"
-        else if (node.delete === true) writeKind = "DELETE"
+        if (nodeField(node, params, "insert") !== undefined && nodeField(node, params, "insert") !== null) writeKind = "INSERT"
+        else if (nodeField(node, params, "update") !== undefined && nodeField(node, params, "update") !== null) writeKind = "UPDATE"
+        else if (nodeField(node, params, "delete") === true) writeKind = "DELETE"
       } else if (op === "query") {
-        const sql = String(node.query || "")
+        const sql = String(nodeField(node, params, "query") || "")
         if (/\b(INSERT|UPDATE|DELETE|TRUNCATE|DROP|ALTER|CREATE)\b/i.test(sql)) {
           writeKind = "write SQL"
         }
@@ -1069,6 +1144,68 @@ async function verifyTablesInRemote(missingTables, projectId) {
   }
 }
 
+function bucketNamesFromStorageList(payload) {
+  const names = new Set()
+  const add = (value) => {
+    if (typeof value === "string" && value.trim()) names.add(value.trim())
+  }
+  const candidates = []
+  if (Array.isArray(payload)) {
+    candidates.push(payload)
+  } else if (payload && typeof payload === "object") {
+    for (const key of ["buckets", "data", "items", "results"]) {
+      if (Array.isArray(payload[key])) candidates.push(payload[key])
+    }
+    if (!candidates.length) candidates.push([payload])
+  }
+  for (const list of candidates) {
+    for (const item of list) {
+      if (typeof item === "string") {
+        add(item)
+      } else if (item && typeof item === "object") {
+        add(item.name)
+        add(item.bucket)
+        add(item.bucket_name)
+      }
+    }
+  }
+  return names
+}
+
+async function verifyStorageBucketsInRemote(bucketRefs, projectId) {
+  if (!bucketRefs.length) return []
+  const uniqueRefs = new Map(bucketRefs.map(ref => [`${ref.bucket}|${ref.endpoint}|${ref.file}|${ref.loc}`, ref]))
+  const refs = [...uniqueRefs.values()]
+  const bucketNames = [...new Set(refs.map(ref => ref.bucket))].sort()
+  try {
+    const args = { operation: "list" }
+    if (projectId) args.project_id = projectId
+    const result = await proxyToolCall("manage_storage", args)
+    const existing = bucketNamesFromStorageList(result)
+    return refs
+      .filter(ref => !existing.has(ref.bucket))
+      .map(ref => ({
+        severity: "error",
+        rule: "storage_bucket_missing",
+        endpoint: ref.endpoint,
+        file: ref.file,
+        loc: ref.loc,
+        message: `Storage bucket '${ref.bucket}' is referenced by endpoint '${ref.endpoint}', but it does not exist in this project.`,
+        fix_hint:
+          `Create it before testing/pushing this endpoint: ` +
+          `manage_storage({ operation: "create", name: "${ref.bucket}", public: false }). ` +
+          `Use public: true only for public assets; user documents/attachments should stay private.`,
+      }))
+  } catch (e) {
+    return [{
+      severity: "warn",
+      rule: "storage_bucket_check_failed",
+      message: `Could not verify storage buckets: ${bucketNames.join(", ")}.`,
+      fix_hint: `Retry manage_storage({ operation: "list" }) or create the expected bucket before testing upload/storage endpoints. Detail: ${e.message}`,
+    }]
+  }
+}
+
 /**
  * Refresh dypai/schema.sql from the remote. Best-effort — if it fails the
  * caller continues with the existing local schema (just logs the warning).
@@ -1116,6 +1253,7 @@ export async function runValidation(rootDir, projectId) {
     // Collected during per-endpoint pass; resolved against the remote AFTER
     // all endpoints are checked (one batch query instead of N).
     suspectedMissingTables: [],
+    suspectedStorageBuckets: [],
   }
 
   const diagnostics = []
@@ -1185,6 +1323,7 @@ export async function runValidation(rootDir, projectId) {
 
   // Realtime YAML rules
   diagnostics.push(...await validateRealtime(rootDir, ctx))
+  diagnostics.push(...await verifyStorageBucketsInRemote(ctx.suspectedStorageBuckets, targetProjectId))
 
   // Surface any file-read errors too
   for (const err of local.errors || []) {
@@ -1219,7 +1358,7 @@ export const dypaiValidateTool = {
   name: "dypai_validate",
   description:
     "Lint the local dypai/ folder BEFORE pushing. Catches ${input.x} / ${nodes.x.y} / ${current_user_*} refs that don't resolve, " +
-    "SQL tables not in schema.sql, credentials that don't exist remotely, and agent tool refs to non-tool endpoints. " +
+    "SQL tables not in schema.sql, missing storage buckets, credentials that don't exist remotely, and agent tool refs to non-tool endpoints. " +
     "Run this after editing YAMLs to catch typos pre-flight. Push already calls it by default — pass skip_validation:true to override.",
   inputSchema: {
     type: "object",