@dypai-ai/mcp 1.4.3 → 1.4.5

package/package.json

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

package/src/api.js

@@ -63,9 +63,21 @@ export function request(method, path, body) {
       res.on("end", () => {
         if (res.statusCode >= 200 && res.statusCode < 300) {
           try { resolve(JSON.parse(buf)) } catch { resolve(buf) }
-        } else {
-          reject(new Error(`HTTP ${res.statusCode}: ${buf.slice(0, 500)}`))
+          return
         }
+        // Build a richer error for quota-specific 429s so MCP tools can surface
+        // them to the agent without parsing raw HTTP strings.
+        let parsedBody = null
+        try { parsedBody = JSON.parse(buf) } catch {}
+        const err = new Error(`HTTP ${res.statusCode}: ${buf.slice(0, 500)}`)
+        err.statusCode = res.statusCode
+        err.body = parsedBody
+        const detail = parsedBody && parsedBody.detail
+        if (detail && typeof detail === "object" && detail.error) {
+          err.code = detail.error
+          err.detail = detail
+        }
+        reject(err)
       })
     })
     req.on("error", reject)

package/src/auto-update.js

@@ -21,6 +21,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_PATH = join(__dirname, "..", "package.json");
 const PKG_NAME = "@dypai-ai/mcp";
 const REGISTRY_URL = `https://registry.npmjs.org/${PKG_NAME}/latest`;
+// Dist-tags endpoint is tiny (<200B) — used to check if there's a CRITICAL
+// release the user must upgrade to immediately, bypassing the 6h throttle.
+// To mark a version as critical after publish:
+//   npm dist-tag add @dypai-ai/mcp@1.4.5 critical
+const DIST_TAGS_URL = `https://registry.npmjs.org/-/package/${PKG_NAME}/dist-tags`;
 const CHECK_TIMEOUT_MS = 2000;
 const THROTTLE_HOURS = 6;
 const STATE_FILE = join(tmpdir(), "dypai-mcp-update-state.json");
@@ -68,6 +73,32 @@ async function fetchLatestManifest() {
   }
 }
 
+/**
+ * Fetch the `critical` dist-tag (if published). Used to bypass the 6h throttle
+ * when a release is important enough that users must upgrade on next spawn.
+ *
+ * Returns the critical version string (e.g. "1.4.5") or null if no critical
+ * tag is set, the registry is unreachable, or the response is malformed.
+ *
+ * Cost: one tiny JSON fetch (~200 bytes) per spawn. Adds ~50-150ms to startup
+ * but runs in parallel with the rest of the MCP init, so wall-clock impact is
+ * usually zero.
+ */
+async function fetchCriticalVersion() {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), CHECK_TIMEOUT_MS);
+  try {
+    const res = await fetch(DIST_TAGS_URL, { signal: ctrl.signal });
+    if (!res.ok) return null;
+    const tags = await res.json();
+    return typeof tags?.critical === "string" ? tags.critical : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 /**
  * After npm publish there's a 30s–2min window where the registry knows the
  * version but the tarball is not yet replicated across the CDN. If we clear
@@ -145,7 +176,19 @@ export async function checkForUpdates({ force = false } = {}) {
   const current = getCurrentVersion();
   if (!current) return { skipped: "no current version" };
 
-  // Throttle
+  // ── Critical release check (bypasses the 6h throttle) ────────────────────
+  // If an ops person has run `npm dist-tag add @dypai-ai/mcp@X.Y.Z critical`,
+  // every spawn picks that up and forces an upgrade regardless of when the
+  // last normal check ran. Used for security / data-loss bug fixes where
+  // 6-24h propagation is too slow.
+  const criticalVersion = await fetchCriticalVersion();
+  const hasCritical = criticalVersion && compareVersions(criticalVersion, current) > 0;
+  if (hasCritical) {
+    log(`CRITICAL update required: ${current} → ${criticalVersion} (bypassing throttle)`);
+    force = true;
+  }
+
+  // Throttle (skipped when force or critical)
   if (!force) {
     const state = readState();
     if (state.lastCheckAt) {

package/src/index.js

@@ -110,7 +110,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: "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.", inputSchema: { type: "object", properties: { project_id: { type: "string" }, sql: { type: "string", description: "SQL query to execute" } }, required: ["sql"] } },
+  { 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"] } },
 
   // ── API Endpoints ─────────────────────────────────────────────────────────
   // Full CRUD + exploration goes through the git-first flow:
@@ -230,6 +230,56 @@ Operations:
     },
   },
 
+  // ── Drafts (production-only staging area) ────────────────────────────────
+  // manage_drafts wraps the cloud SDK that talks to /api/engine/{id}/endpoints/
+  // Single tool, three ops (list / publish / discard) — same shape as
+  // manage_users / manage_roles / manage_storage so the agent's mental
+  // model stays uniform. Every project starts in draft-publish mode by
+  // default: dypai_push stages mutations as drafts and the user (or
+  // agent on their behalf) publishes when ready.
+  {
+    name: "manage_drafts",
+    description: `BACKEND ONLY — inspect, publish, or discard pending backend changes (drafts).
+
+Mental model: every change made by \`dypai_push\` (endpoints, webhooks,
+crons, realtime policies) is staged as a DRAFT first. Drafts do NOT
+affect live traffic; they only show up in the live config once the user
+publishes them. This is the universal default — works the same on every
+project, no environment flags to worry about. The frontend is a separate
+stack — use \`manage_frontend(deploy)\` to publish frontend changes.
+
+Operations:
+- list:    Return pending drafts grouped by resource type. Read-only,
+           no confirmation. Run this BEFORE publish/discard so the user
+           sees exactly what will ship or be thrown away.
+- publish: Atomically apply ALL pending drafts to live (creates, updates,
+           deletions) and invalidate affected caches. Requires confirm:true.
+- discard: Drop pending drafts without applying. By default discards
+           every draft; pass resource_names:[...] to scope the discard
+           to specific endpoints. Requires confirm:true.
+
+Typical flow:
+  1. dypai_push                                          → changes saved as drafts
+  2. manage_drafts(operation:'list')                     → show user what's pending
+  3. (optional) test the draft from local dev / preview
+  4. manage_drafts(operation:'publish', confirm:true)    → make it live
+     OR manage_drafts(operation:'discard', confirm:true) → throw it away`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id:     { type: "string", description: "Project UUID. Required for user tokens; auto-detected for project tokens." },
+        operation:      { type: "string", enum: ["list", "publish", "discard"], description: "Operation to perform." },
+        confirm:        { type: "boolean", description: "Required true for publish and discard. Without it the tool returns a confirmation_required hint instead of mutating.", default: false },
+        resource_names: { type: "array", items: { type: "string" }, description: "Optional. For discard: scope to drafts whose resource_name matches one of these. Ignored by list/publish." },
+      },
+      required: ["operation"],
+      allOf: [
+        { if: { properties: { operation: { const: "publish" } }, required: ["operation"] }, then: { required: ["confirm"] } },
+        { if: { properties: { operation: { const: "discard" } }, required: ["operation"] }, then: { required: ["confirm"] } },
+      ],
+    },
+  },
+
   // ── Storage ───────────────────────────────────────────────────────────────
   // manage_storage covers BOTH bucket-level and object-level operations.
   // The remote also accepts the legacy name `list_buckets` (alias) so older
@@ -405,7 +455,109 @@ endpoint YAML and \`dypai_push\`. This tool does NOT modify the definition.`,
 
 // ── Server Instructions ──────────────────────────────────────────────────────
 
-const SERVER_INSTRUCTIONS = `You are building full-stack applications on the DYPAI platform. You handle backend (endpoints, database, auth, realtime) AND frontend (SDK integration, UI code).
+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).
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# QUICK START — read this section even if you skip everything else
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## What you ship — two completely separate stacks
+
+| Stack | What it is | Where it lives | How you change it | How you publish |
+|---|---|---|---|---|
+| **BACKEND** | Workflow endpoints (HTTP, cron, webhook, telegram), DB schema, realtime policies | \`dypai/\` folder | Edit YAMLs / SQL files / realtime.yaml on disk | \`dypai_push\` (saves draft) → \`manage_drafts(publish, confirm:true)\` |
+| **FRONTEND** | React/Vite/Next bundle (UI, SDK calls) | \`src/\`, \`public/\`, \`package.json\` | Edit React code | \`manage_frontend(deploy, confirm:true)\` |
+
+Two things to internalize:
+1. The two stacks are SHIPPED INDEPENDENTLY. Editing backend never touches frontend, and vice versa.
+2. Backend has a draft stage; frontend does NOT. Both publish operations require \`confirm:true\`.
+
+## Backend lifecycle — "save" = \`dypai_push\` (this is the rule that trips up new agents)
+
+Editing files inside \`dypai/\` only changes YOUR DISK. The platform doesn't see them, the draft overlay doesn't serve them, the local frontend can't call them. There are exactly **three** states and only \`dypai_push\` and \`manage_drafts(publish)\` move you between them:
+
+\`\`\`
+  ┌────────────┐  edit YAML / SQL / md   ┌────────────┐  dypai_push   ┌────────────┐  manage_drafts(publish, confirm:true)   ┌────────────┐
+  │   LIVE     │ ──────────────────────► │ LOCAL DISK │ ────────────► │   DRAFT    │ ──────────────────────────────────────► │   LIVE     │
+  │ (engine)   │  (no platform impact)   │ (your edit)│ (stages it)   │ (overlay)  │  (atomic, all drafts at once)           │ (engine)   │
+  └────────────┘                         └────────────┘               └────────────┘                                         └────────────┘
+                                                                            ▲
+                                                              draft overlay │ served at https://dev-<project_id>.dypai.dev
+                                                                            │ (what the user's local frontend points to)
+\`\`\`
+
+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?".
+- **\`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.
+
+## User intent → tool to call (decision table)
+
+Use this BEFORE picking a tool. If unsure which row matches, ask the user.
+
+| If the user asks to... | First call | Then |
+|---|---|---|
+| "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/\` |
+| "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) |
+| "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) | — |
+
+## Confirm rules — the ONLY operations that need \`confirm:true\`
+
+There are exactly THREE write operations that mutate live state and require explicit user approval (return a \`confirmation_required\` hint without it):
+
+1. **\`manage_drafts(operation:'publish', confirm:true)\`** — promotes backend drafts to live.
+2. **\`manage_drafts(operation:'discard', confirm:true)\`** — throws away pending backend drafts.
+3. **\`manage_frontend(operation:'deploy', confirm:true)\`** — replaces the live frontend bundle.
+
+Everything else (\`dypai_push\`, \`execute_sql\`, \`bulk_upsert\`, all read tools) does NOT require confirm. \`dypai_push\` is safe by design: it stages drafts, so you can iterate freely without affecting the live site.
+
+When you receive a \`confirmation_required\` response: SUMMARIZE the change to the user in plain language (what will go live, any warnings about pending backend drafts), wait for an explicit "yes" / "go ahead", then re-call with \`confirm:true\`.
+
+## End-to-end example — adding a feature that touches BOTH backend and frontend
+
+User: "Add a /api/list-tasks endpoint that returns the current user's tasks, and show them on the dashboard."
+
+\`\`\`
+1. dypai_pull(project_id)                        # materialize backend if not already on disk
+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 ✅
+\`\`\`
+
+**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.
+
+## What you do NOT have to think about
+
+- "Development vs production environment" — the user never sees this. Backend changes always go through draft-and-publish. Frontend changes always go through deploy. That's the whole model.
+- "Create auth endpoints" — auth is built into the SDK. \`dypai.auth.signInWithPassword()\` works out of the box. NEVER write a login/signup workflow.
+- "RLS / row-level security" — there is none. You filter by \`\${current_user_id}\` in your SQL WHERE clauses. Forgetting this is the #1 multi-tenancy bug.
+- "Rate limiting / CORS / JWT verification" — handled by the engine.
+- "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
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ## Getting Started
 1. list_projects() → pick project_id.
@@ -431,14 +583,15 @@ Mental translations:
 ## 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.
-2. Endpoints:
+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.
+   - \`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\` → apply.
-3. \`dypai_test_endpoint\` to run the LOCAL YAML against the engine. Iterate edit → test → push.
+   - \`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
 
@@ -494,7 +647,14 @@ Any endpoint can be flagged \`tool: true\` to be callable by \`agent\` nodes. Ho
 
 ## Testing & Debugging
 
-- **\`dypai_test_endpoint\`** — single endpoint, LOCAL YAML (unpushed edits). Pass \`as_user\` UUID for jwt endpoints. Trace modes: \`smart\` (default), \`full\`, \`minimal\`. Iterate edit → test → push.
+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**: \`get_recent_workflow_activity(only_errors=true)\` surfaces recent failures.
@@ -577,7 +737,8 @@ query_file: /absolute/path/sql/get-orders.sql
 - \`/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.app\` — the engine base URL (what the SDK points to)
+- \`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)
 
@@ -785,6 +946,8 @@ Pre-configured at \`src/lib/dypai.ts\`. Every method returns \`{ data, error }\`
 - **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
@@ -797,19 +960,23 @@ SDK is pre-configured at \`src/lib/dypai.ts\`. Import \`dypai\` from there. Ever
 - **Realtime hooks**: \`useRealtime\`, \`useChannel\`, \`useChannelMessages\` (see Realtime section)
 - **Rule**: NEVER \`fetch()\` directly — always through the SDK
 
-**\`.env\` required** — \`.env\` is gitignored so \`manage_frontend(sync)\` does NOT fetch it. If \`env_file_missing: true\` in the sync response, create it:
+**\`.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
-# Vite
-VITE_DYPAI_URL=https://<project_id>.dypai.app
-VITE_PROJECT_ID=<project_id>
-# Next.js (NEXT_PUBLIC_ prefix is required)
-NEXT_PUBLIC_DYPAI_URL=https://<project_id>.dypai.app
+# 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
 \`\`\`
-Without \`.env\`, all SDK calls fail. It's always the missing env var, not the code.
+
+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.
 
 ## Frontend deploy
 
-\`manage_frontend(operation: deploy, sourceDirectory, project_id)\` → returns immediately with build_status=queued. Poll \`operation: build_status\` every ~5s until "success" or "failure". On failure: \`operation: list_deployments\` → \`operation: logs\` with deployment_id. Supports Vite, React, Next.js, Astro, SvelteKit, Nuxt, Remix, Angular, CRA (auto-detected).
+\`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).
+
+Returns immediately with build_status=queued. Poll \`operation: build_status\` every ~5s until "success" or "failure". On failure: \`operation: list_deployments\` → \`operation: logs\` with deployment_id. Supports Vite, React, Next.js, Astro, SvelteKit, Nuxt, Remix, Angular, CRA (auto-detected).
 
 The deploy is delta by default: only files changed since last deploy are sent. Large media (>25MB) surfaces in \`assets_requiring_action\` with ready-to-exec \`manage_storage(upload_file)\` calls.
 
@@ -822,6 +989,7 @@ The deploy is delta by default: only files changed since last deploy are sent. L
 - \`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.
 
 ## Deep docs — search_docs topic map
 

package/src/tools/deploy.js

@@ -489,13 +489,19 @@ export async function deployFromSource({ sourceDirectory, project_id, force = fa
     const assetsAction = buildAssetsRequiringAction(skipped, mediaManifest, project_id)
     const hasUnresolvedAssets = assetsAction && assetsAction.count > 0
 
+    const quota = result.build_quota || null
+    const quotaWarning = buildQuotaWarning(quota)
+
     const baseMessage =
       `Deploy accepted — ${allFiles.length} files (${formatBytes(total)}). ` +
       `Build running (${label}, ~20-60s). Poll manage_frontend({operation:"build_status"}) every ~5s.`
 
     let message = baseMessage
+    if (quotaWarning) {
+      message = `${quotaWarning}\n\n${message}`
+    }
     if (hasUnresolvedAssets) {
-      message = `${assetsAction.message}\n\n${baseMessage}`
+      message = `${assetsAction.message}\n\n${message}`
     }
 
     return {
@@ -513,6 +519,8 @@ export async function deployFromSource({ sourceDirectory, project_id, force = fa
       ...(hasUnresolvedAssets ? { assets_requiring_action: assetsAction } : {}),
       ...(assetsAction?.all_synced ? { assets_synced: assetsAction.already_in_bucket } : {}),
 
+      ...(quota ? { build_quota: quota } : {}),
+
       next_step: hasUnresolvedAssets
         ? {
             action: "resolve_pending_assets_then_poll_build",
@@ -536,6 +544,46 @@ export async function deployFromSource({ sourceDirectory, project_id, force = fa
       message,
     }
   } catch (e) {
+    if (e.statusCode === 429 && e.detail && e.detail.error === "build_quota_exceeded") {
+      return {
+        success: false,
+        error: e.detail.message || "Monthly build minutes limit reached.",
+        error_code: "build_quota_exceeded",
+        build_quota: {
+          minutes_used: e.detail.minutes_used,
+          minutes_limit: e.detail.minutes_limit,
+          resets_at: e.detail.resets_at,
+        },
+        upgrade_url: e.detail.upgrade_url,
+        advice: "Do not retry this deploy. Inform the user that the monthly build minute quota is exhausted and suggest upgrading the project plan.",
+      }
+    }
+    if (e.statusCode === 429 && e.detail && e.detail.error === "concurrent_builds_limit") {
+      return {
+        success: false,
+        error: e.detail.message || "Concurrent build limit reached.",
+        error_code: "concurrent_builds_limit",
+        concurrent_active: e.detail.concurrent_active,
+        concurrent_limit: e.detail.concurrent_limit,
+        advice: "Wait for the active build to finish (poll manage_frontend({operation:'build_status'})) before re-deploying.",
+      }
+    }
     return { error: `Deploy failed: ${e.message}` }
   }
 }
+
+/**
+ * Human-readable warning when the project is near its monthly build quota.
+ * Returns null when plan is unlimited or usage is below 80%.
+ */
+function buildQuotaWarning(quota) {
+  if (!quota) return null
+  const { minutes_used, minutes_limit, minutes_remaining } = quota
+  if (minutes_limit == null) return null
+  const pct = minutes_limit > 0 ? (minutes_used / minutes_limit) : 0
+  if (pct < 0.8) return null
+  if (pct >= 1) {
+    return `⚠️ Monthly build minutes exhausted (${minutes_used}/${minutes_limit} min). This deploy used your last minutes — upgrade your plan to deploy again.`
+  }
+  return `⚠️ Build quota at ${Math.round(pct * 100)}% (${minutes_used}/${minutes_limit} min, ${minutes_remaining} remaining). Consider upgrading soon.`
+}

package/src/tools/frontend.js

@@ -14,11 +14,13 @@
 import { api } from "../api.js"
 import { deployFromSource } from "./deploy.js"
 import { syncFromRemote } from "./sync.js"
+import { proxyToolCall } from "./proxy.js"
 
 export const manageFrontendTool = {
   name: "manage_frontend",
   description:
-    "Manage the project's frontend: download the source code to disk AND the deploy lifecycle.\n\n" +
+    "FRONTEND ONLY — manages the project's static frontend (HTML/CSS/JS bundle). For BACKEND endpoints/workflows use dypai_push + manage_drafts; never use this tool for backend work.\n\n" +
+    "Two phases: download source to local disk (`sync`), then ship changes back (`deploy`).\n\n" +
     "Use `sync` FIRST whenever you start working on a project whose frontend code isn't already on this machine — " +
     "without it you have no React/Vite source to read or edit. Call `deploy` to ship your changes.\n\n" +
     "Operations:\n" +
@@ -28,19 +30,25 @@ export const manageFrontendTool = {
     "Writes only; does NOT delete local files that were removed upstream — you may have stale files after sync (call them out to the user). " +
     "By default refuses to overwrite a directory that already has a package.json — pass overwrite:true to allow it (local-only files like .env, node_modules, .vscode are always preserved). " +
     "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. Returns immediately with build_status=\"queued\" — poll with `build_status` until \"success\" or \"failure\".\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). " +
+    "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" +
     "  - build_status: Progress of the current/latest build (queued/building/success/failure + stage + %).\n" +
+    "  - usage: Full frontend usage snapshot including build_quota (minutes used/limit/remaining, deploy counts, resets_at). Call BEFORE deploy if unsure how much quota is left.\n" +
     "  - 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.",
+    "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.",
 
   inputSchema: {
     type: "object",
     properties: {
       operation: {
         type: "string",
-        enum: ["deploy", "sync", "status", "build_status", "list_deployments", "logs"],
+        enum: ["deploy", "sync", "status", "build_status", "usage", "list_deployments", "logs"],
         description: "Which action to run.",
       },
       project_id: {
@@ -65,6 +73,11 @@ export const manageFrontendTool = {
         description: "deploy only. Bypass the delta manifest and re-send ALL files (full deploy). Use when the previous deploy's remote build FAILED — the manifest says 'synced' but the remote never built, so a normal delta incorrectly reports no_changes. Default: false.",
         default: false,
       },
+      confirm: {
+        type: "boolean",
+        description: "Required `true` for `deploy`. Without it the tool returns a confirmation_required hint (with a ready-to-call next_call) instead of replacing the live site. The agent MUST get explicit user approval before passing confirm:true.",
+        default: false,
+      },
       deployment_id: {
         type: "string",
         description: "logs only. Deployment UUID obtained from list_deployments.",
@@ -77,7 +90,7 @@ export const manageFrontendTool = {
     required: ["operation"],
   },
 
-  async execute({ operation, project_id, sourceDirectory, targetDirectory, overwrite, force, deployment_id, limit } = {}) {
+  async execute({ operation, project_id, sourceDirectory, targetDirectory, overwrite, force, confirm, deployment_id, limit } = {}) {
     if (!operation) {
       return { success: false, error: "operation is required (deploy | sync | status | build_status | list_deployments | logs)." }
     }
@@ -91,6 +104,43 @@ export const manageFrontendTool = {
           if (!sourceDirectory) {
             return { success: false, error: "operation 'deploy' requires 'sourceDirectory' (absolute path to your frontend project root)." }
           }
+          // Defense-in-depth gate: deploy replaces the live site immediately
+          // with no rollback. Without explicit confirm we return a structured
+          // hint (with ready-to-execute next_call). We also surface any
+          // pending backend drafts as warnings — the agent should ALWAYS
+          // publish backend drafts before deploying frontend, otherwise the
+          // new frontend may call endpoints that don't exist yet on live.
+          if (confirm !== true) {
+            const warnings = []
+            try {
+              const draftsResult = await proxyToolCall("manage_drafts", { project_id, operation: "list" })
+              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.`,
+                )
+              }
+            } catch {
+              // Soft-fail — drafts check is advisory, not gating.
+            }
+            return {
+              confirmation_required: true,
+              summary: `About to replace the LIVE frontend at this project's public URL with the contents of '${sourceDirectory}'. This is IMMEDIATE and there is NO automatic rollback.`,
+              warnings: warnings.length > 0 ? warnings : undefined,
+              next_call: {
+                tool: "manage_frontend",
+                operation: "deploy",
+                project_id,
+                sourceDirectory,
+                ...(force ? { force: true } : {}),
+                confirm: true,
+              },
+              hint:
+                "Summarize the change to the user (what visual/functional changes are about to go live, " +
+                "and any pending backend drafts) and wait for explicit user approval. Then re-call this " +
+                "tool with confirm:true.",
+            }
+          }
           return await deployFromSource({ sourceDirectory, project_id, force: !!force })
 
         case "sync":
@@ -105,6 +155,9 @@ export const manageFrontendTool = {
         case "build_status":
           return await api.get(`/api/engine/${project_id}/frontend/build-status`)
 
+        case "usage":
+          return await api.get(`/api/engine/${project_id}/frontend/usage`)
+
         case "list_deployments":
           return await api.get(`/api/engine/${project_id}/frontend/deployments?limit=${limit || 10}`)
 
@@ -115,7 +168,7 @@ export const manageFrontendTool = {
           return await api.get(`/api/engine/${project_id}/frontend/deployments/${deployment_id}/logs`)
 
         default:
-          return { success: false, error: `Unknown operation '${operation}'. Use deploy | sync | status | build_status | list_deployments | logs.` }
+          return { success: false, error: `Unknown operation '${operation}'. Use deploy | sync | status | build_status | usage | list_deployments | logs.` }
       }
     } catch (e) {
       return { success: false, error: e.message, operation }

package/src/tools/scaffold.js

@@ -47,9 +47,13 @@ Or use "blank" for an empty starter project.`,
       return { error: `Directory already has a package.json. Pick an empty directory or a new name.` }
     }
 
-    // Production engine URL: https://<project-id>.dypai.app (NOT .dypai.dev — that's the dev tier).
+    // Engine base URL — `<project_id>.dypai.dev` serves LIVE traffic; the
+    // local-development URL `dev-<project_id>.dypai.dev` (Layer 2.5 draft
+    // overlay) is written into `.env.local` separately by `sync` once the
+    // user has the frontend on disk. Scaffold writes the production URL
+    // because at scaffold-time we expect the user to deploy soon.
     // Override with DYPAI_ENGINE_BASE for self-hosted / staging setups.
-    const engineBase = process.env.DYPAI_ENGINE_BASE || "dypai.app"
+    const engineBase = process.env.DYPAI_ENGINE_BASE || "dypai.dev"
     const engineUrl = `https://${project_id}.${engineBase}`
 
     // Try to download template from API