@dypai-ai/mcp 1.4.2 → 1.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dypai-ai/mcp",
-  "version": "1.4.2",
+  "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

@@ -18,11 +18,15 @@ function getConfig() {
   return {
     token: process.env.DYPAI_TOKEN || "",
     apiUrl: process.env.DYPAI_API_URL || DEFAULT_API_URL,
+    // Escape hatch for local dev against an API that doesn't have the
+    // gzip decompression middleware yet. Set DYPAI_NO_GZIP=1 to send
+    // bodies as plain JSON regardless of size.
+    noGzip: process.env.DYPAI_NO_GZIP === "1" || process.env.DYPAI_NO_GZIP === "true",
   }
 }
 
 export function request(method, path, body) {
-  const { token, apiUrl } = getConfig()
+  const { token, apiUrl, noGzip } = getConfig()
   const url = `${apiUrl}${path}`
 
   return new Promise((resolve, reject) => {
@@ -33,7 +37,7 @@ export function request(method, path, body) {
     let payload = jsonStr ? Buffer.from(jsonStr) : null
     let useGzip = false
 
-    if (payload && payload.length > GZIP_THRESHOLD) {
+    if (payload && payload.length > GZIP_THRESHOLD && !noGzip) {
       payload = gzipSync(payload)
       useGzip = true
     }
@@ -59,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