@dypai-ai/mcp 1.5.9 → 1.5.11

package/package.json

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

package/src/index.js

@@ -35,6 +35,10 @@ import { manageFrontendTool } from "./tools/frontend.js"
 // import { scaffoldTool } from "./tools/scaffold.js"
 import { manageDomainTool } from "./tools/domains.js"
 import { bulkUpsertTool } from "./tools/bulk-upsert.js"
+import {
+  searchCapabilityKitsTool,
+  manageCapabilityKitTool,
+} from "./tools/capability-kits.js"
 import { uploadFile } from "./tools/storage.js"
 // dypaiTestTool (YAML test-suite runner) is intentionally not imported — deferred to v2.
 // The format works but needs fixtures/auto-rollback/scaffolder + proper docs before being surfaced.
@@ -82,6 +86,9 @@ const LOCAL_TOOLS = [
   manageDomainTool,
   // ── Data ──────────────────────────────────────────────────────────────────
   bulkUpsertTool,
+  // ── Capability kits (local source installer) ──────────────────────────────
+  searchCapabilityKitsTool,
+  manageCapabilityKitTool,
   // ── Git-first source of truth ─────────────────────────────────────────────
   // dypai_describe was merged into dypai_pull (now returns an `overview` block).
   dypaiPullTool,
@@ -538,6 +545,17 @@ 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.
 
+For complex reusable capabilities (calendar booking, interactive maps, CRUD
+tables, Kanban boards, upload/document flows, dashboards, rich editors), also
+use \`search_capability_kits\`. If a strong kit matches, inspect it with
+\`manage_capability_kit(operation: "inspect")\` and install it with
+\`manage_capability_kit(operation: "apply")\` instead of building that complex
+component from scratch. Installed kit code is editable workspace source; after
+install, if the tool returns dependencies, add any missing packages to the
+target workspace package.json and install them locally (never globally or in
+the MCP server). Then wire the kit into the app, apply SQL if needed, validate
+endpoints, and verify the frontend.
+
 **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
@@ -683,9 +701,10 @@ Internally this means:
 
 1. edit backend files
 2. validate local backend changes
-3. save them to the preview environment
-4. test the preview version when practical
-5. then tell the user it is ready to try
+3. test changed endpoint YAML with \`dypai_test_endpoint(mode:'local')\` when practical
+4. save them to the preview environment
+5. test the preview version when practical
+6. then tell the user it is ready to try
 
 Never ask the user whether to run the internal save-to-preview step. It is safe, reversible, and required for the user to test the actual change.
 
@@ -881,12 +900,12 @@ Editing files inside \`dypai/\` only changes YOUR DISK. The platform doesn't see
 \`\`\`
 
 Practical consequences — internalize these:
-- **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.
+- **Never publish backend changes just to test them.** First test the local YAML directly with \`dypai_test_endpoint(mode:'local')\`; only after that save to preview with \`dypai_push\` and verify the staged draft when needed.
 - **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 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)\`.
+- **Order during a multi-step backend feature**: edit → \`dypai_validate\` → \`dypai_test_endpoint(mode:'local')\` → \`dypai_push\` → \`dypai_test_endpoint(mode:'draft')\` when you need to verify the saved preview. Repeat per coherent 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)
@@ -898,7 +917,7 @@ 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\` |
+| "Add/change a backend endpoint, table, cron, webhook, agent, integration" | Edit files in \`dypai/\` | \`dypai_validate\` → \`dypai_test_endpoint(mode:'local')\` for changed endpoints → \`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. | — |
@@ -930,21 +949,23 @@ 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 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
+4. dypai_validate                                # catch YAML/placeholder issues
+5. dypai_test_endpoint(endpoint:'list-tasks', mode:'local', as_user:'<user_id>')
+   # verifies the local YAML before saving anything to preview
+6. dypai_push                                    # saves to preview, NOT production
+7. dypai_test_endpoint(endpoint:'list-tasks', mode:'draft', as_user:'<user_id>')
+   # optional final sanity: verifies the preview version; do NOT publish just to test
+8. # 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:
+9. # 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:
+10. # 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
+11. manage_drafts(operation:'publish', confirm:true)  # backend live after explicit approval
+12. manage_frontend(operation:'deploy', sourceDirectory, confirm:true)  # frontend live after explicit approval
 \`\`\`
 
-**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.
+**Testing rule**: never publish backend changes just to test them. Verify local YAML first with \`dypai_test_endpoint(mode:'local')\`, then save to preview and test \`mode:'draft'\` or the dev URL when needed. **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
 
@@ -1011,6 +1032,8 @@ Each item has \`type\` (\`execution\` | \`execution_failed\` | \`log\`), \`level
 
 DYPAI has NO standalone "edge functions". Every piece of server-side logic (API endpoints, crons, webhooks, AI agents) is a workflow endpoint under \`dypai/endpoints/<name>.yaml\`. A workflow is either a chain of native nodes (\`dypai_database\`, \`http_request\`, \`agent\`, \`stripe\`, etc.) OR a single \`javascript_code\` / \`python_code\` node for custom logic. Mix freely.
 
+Endpoint naming is strict: the YAML \`name\` is the public API slug and must exactly match the file basename. Example: \`dypai/endpoints/list-videos.yaml\` must declare \`name: list-videos\`. Use lowercase letters, numbers, hyphens, or underscores only; never spaces or human titles. Put labels like "Listar videos" in \`description\`, not \`name\`. If \`id\` is present, it must match \`name\`; usually omit \`id\`.
+
 Mental translations: "edge function" → workflow with one code node; "cron" → \`trigger.schedule\` in the YAML; "webhook receiver" → \`trigger.webhook\`; "internal API" → \`trigger.http_api auth_mode:jwt\`.
 
 → Full workflow patterns + YAML shape: \`search_docs("workflow patterns")\` and \`search_docs("trigger model")\`. Node catalog (full input/output schemas): read \`dypai/node-catalog.json\`.
@@ -1030,12 +1053,13 @@ Mental translations: "edge function" → workflow with one code node; "cron" →
 ## Top gotchas (the expensive ones)
 
 1. **Forgetting \`WHERE user_id = \${current_user_id}\`** — users see each other's data. #1 multi-tenancy bug. The engine does NOT auto-filter. RLS doesn't exist.
-2. **Editing YAML without \`dypai_push\`** — your change is on YOUR DISK only. Local frontend (which points at the draft overlay) keeps serving the old version. Symptom: *"I tested it locally and nothing changed"*. Always push after each meaningful change set.
+2. **Editing YAML without \`dypai_push\`** — \`dypai_test_endpoint(mode:'local')\` can test your file edits, but the preview/frontend cannot see them until \`dypai_push\` saves them to draft. Symptom: *"I tested it in preview and nothing changed"*. Test local first, then push when the changed endpoint is ready for preview.
 3. **Treating \`dypai_push\` as a deploy** — it's "save as draft", not publish. Live traffic is untouched until \`manage_drafts(publish, confirm:true)\`. Push freely, only ask the user before publish.
 4. **\`public\` auth_mode with \`\${current_user_id}\`** — no JWT → placeholder empty → SQL fails or returns wrong data. Use \`jwt\` if you need the user.
 5. **Missing \`return: true\`** — endpoint returns \`null\`. Every path that should produce an HTTP response needs one node with \`return: true\`.
 6. **\`tool_ids\` in YAML instead of \`tools\`** — write \`tools: [name1, name2]\`. \`tool_ids\` bypasses the codec and fails silently in prod.
 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.
+8. **Human endpoint names** — \`name: Listar videos\` in \`list-videos.yaml\` creates a draft the frontend cannot call as \`list-videos\`. \`dypai_validate\` and \`dypai_push\` reject this; fix the slug instead of testing around it.
 
 → Longer list of common pitfalls + fixes: \`search_docs("troubleshooting")\`.
 
@@ -1046,7 +1070,7 @@ Mental translations: "edge function" → workflow with one code node; "cron" →
 - **AI chat**: single endpoint with \`agent\` node + \`memory_key: "chat:\${current_user_id}"\`. Frontend \`dypai.api.stream()\`.
 - **Payments (Stripe)**: \`stripe\` node for ops. Webhook endpoint with \`trigger.webhook\` + \`stripe_webhook: true\` (auto-verifies signature).
 - **Cron**: \`trigger.schedule: { cron: "0 9 * * *", timezone: "..." }\`. Same workflow syntax as HTTP endpoints.
-- **File upload**: frontend \`dypai.api.upload(endpoint, file)\`. Endpoint = one \`dypai_storage\` node. SDK handles signed-URL PUT.
+- **File upload**: frontend \`dypai.api.upload(endpoint, file, { params: { operation:'upload', file_path } })\`. Endpoint = one \`dypai_storage\` node with \`return:true\`. SDK handles signed-URL PUT and owns \`confirm\`/\`client_upload\`; never pass those flags from frontend params.
 - **Live dashboard**: normal endpoint + frontend \`useRealtime(table, { onInsert: refetch })\`.
 - **Multi-tenant**: every row has \`org_id\` or \`user_id\`. Every endpoint filters by \`\${current_user_id}\`.
 

package/src/tools/capability-kits.js

@@ -0,0 +1,567 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, copyFileSync } from "fs"
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "path"
+import { fileURLToPath } from "url"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const DEFAULT_LIMIT = 5
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"))
+}
+
+function isObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value)
+}
+
+function normalizeList(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.trim()) : []
+}
+
+function walkUp(start, predicate) {
+  let cursor = resolve(start)
+  for (let i = 0; i < 10; i++) {
+    if (predicate(cursor)) return cursor
+    const parent = dirname(cursor)
+    if (parent === cursor) break
+    cursor = parent
+  }
+  return null
+}
+
+function resolveKitsRoot(inputRoot) {
+  const candidates = [
+    inputRoot,
+    process.env.DYPAI_CAPABILITY_KITS_ROOT,
+  ].filter(Boolean)
+
+  for (const candidate of candidates) {
+    const root = resolve(candidate)
+    if (existsSync(join(root, "kits"))) return root
+  }
+
+  const fromCwd = walkUp(process.cwd(), (dir) => existsSync(join(dir, "dypai-capability-kits", "kits")))
+  if (fromCwd) return join(fromCwd, "dypai-capability-kits")
+
+  const fromThisFile = walkUp(__dirname, (dir) => existsSync(join(dir, "dypai-capability-kits", "kits")))
+  if (fromThisFile) return join(fromThisFile, "dypai-capability-kits")
+
+  throw new Error(
+    "Capability kit repo not found. Set DYPAI_CAPABILITY_KITS_ROOT to the local dypai-capability-kits directory.",
+  )
+}
+
+function resolveWorkspaceRoot(inputRoot) {
+  if (inputRoot) {
+    const root = resolve(inputRoot)
+    mkdirSync(root, { recursive: true })
+    return root
+  }
+
+  const envCandidates = [
+    process.env.CLAUDE_PROJECT_DIR,
+    process.env.DYPAI_WORKSPACE_ROOT,
+    process.env.PROJECT_ROOT,
+    process.env.WORKSPACE_FOLDER_PATHS?.split(delimiter)[0],
+  ].filter(Boolean)
+
+  for (const candidate of envCandidates) {
+    const root = resolve(candidate)
+    if (existsSync(root)) return root
+  }
+
+  const fromCwd = walkUp(process.cwd(), (dir) =>
+    existsSync(join(dir, ".git")) ||
+    existsSync(join(dir, "package.json")) ||
+    existsSync(join(dir, "dypai")) ||
+    existsSync(join(dir, "src")),
+  )
+  if (fromCwd) return fromCwd
+
+  throw new Error("Could not determine workspace root. Pass workspace_root as an absolute project path.")
+}
+
+function safeTarget(workspaceRoot, targetPath) {
+  if (!targetPath || typeof targetPath !== "string") throw new Error("Invalid target path")
+  if (isAbsolute(targetPath)) throw new Error(`Target must be workspace-relative, got absolute path: ${targetPath}`)
+  const normalized = targetPath.replace(/\\/g, "/").replace(/^\/+/, "")
+  if (normalized.includes("..")) throw new Error(`Target path cannot contain '..': ${targetPath}`)
+  const full = resolve(workspaceRoot, normalized)
+  const rel = relative(workspaceRoot, full)
+  if (rel.startsWith("..") || rel === "" || isAbsolute(rel)) {
+    throw new Error(`Target escapes workspace root: ${targetPath}`)
+  }
+  return full
+}
+
+function kitDir(kitsRoot, slug, version) {
+  if (!slug || !version) throw new Error("slug and version are required")
+  return join(kitsRoot, "kits", slug, version)
+}
+
+function loadKit(kitsRoot, slug, version) {
+  const dir = kitDir(kitsRoot, slug, version)
+  const manifestPath = join(dir, "kit.json")
+  if (!existsSync(manifestPath)) throw new Error(`Kit not found: ${slug}@${version}`)
+  const manifest = readJson(manifestPath)
+  return { dir, manifest }
+}
+
+function listKits(kitsRoot) {
+  const kitsDir = join(kitsRoot, "kits")
+  const kits = []
+  for (const slug of readdirSync(kitsDir)) {
+    const slugDir = join(kitsDir, slug)
+    if (!existsSync(slugDir) || slug === "index.json") continue
+    for (const version of readdirSync(slugDir)) {
+      const manifestPath = join(slugDir, version, "kit.json")
+      if (!existsSync(manifestPath)) continue
+      kits.push({ dir: join(slugDir, version), manifest: readJson(manifestPath) })
+    }
+  }
+  return kits
+}
+
+function searchText(kit) {
+  const parts = [
+    kit.slug,
+    kit.name,
+    kit.kitType,
+    kit.category,
+    kit.description,
+    kit.useWhen,
+    kit.avoidWhen,
+    kit.userFacingSummary,
+    kit.agentInstructions,
+    ...normalizeList(kit.appTypes),
+    ...normalizeList(kit.screenTypes),
+    ...normalizeList(kit.featureTags),
+    ...normalizeList(kit.visualStyles),
+    ...normalizeList(kit.provides),
+    ...normalizeList(kit.requires),
+    ...normalizeList(kit.dependencies),
+  ]
+  return parts.filter(Boolean).join(" ").toLowerCase()
+}
+
+function matchesFilter(kit, filters = {}) {
+  if (!isObject(filters)) return true
+  if (filters.category && kit.category !== filters.category) return false
+  if (filters.maturity) {
+    const allowed = Array.isArray(filters.maturity) ? filters.maturity : [filters.maturity]
+    if (!allowed.includes(kit.maturity)) return false
+  }
+  const listChecks = [
+    ["app_type", "appTypes"],
+    ["screen_type", "screenTypes"],
+    ["feature_tag", "featureTags"],
+  ]
+  for (const [filterKey, kitKey] of listChecks) {
+    if (filters[filterKey] && !normalizeList(kit[kitKey]).includes(filters[filterKey])) return false
+  }
+  if (Array.isArray(filters.requires)) {
+    const requires = normalizeList(kit.requires)
+    for (const required of filters.requires) {
+      if (!requires.includes(required)) return false
+    }
+  }
+  return true
+}
+
+function scoreKit(query, kit) {
+  const text = searchText(kit)
+  const terms = String(query || "")
+    .toLowerCase()
+    .split(/[^a-z0-9áéíóúñ]+/i)
+    .map((term) => term.trim())
+    .filter((term) => term.length >= 3)
+  if (!terms.length) return 0
+  let score = 0
+  for (const term of terms) {
+    if (kit.slug?.includes(term)) score += 5
+    if (kit.category?.toLowerCase() === term) score += 4
+    if (text.includes(term)) score += 1
+  }
+  return score
+}
+
+function assetIndex(dir) {
+  const out = []
+  function visit(abs, rel = "") {
+    for (const name of readdirSync(abs, { withFileTypes: true })) {
+      const childAbs = join(abs, name.name)
+      const childRel = rel ? `${rel}/${name.name}` : name.name
+      if (name.isDirectory()) visit(childAbs, childRel)
+      else out.push({ logicalPath: childRel, sizeBytes: readFileSync(childAbs).length })
+    }
+  }
+  visit(dir)
+  return out.sort((a, b) => a.logicalPath.localeCompare(b.logicalPath))
+}
+
+function stripFrontendPrefix(source) {
+  return source.replace(/^frontend\/src\//, "")
+}
+
+function defaultTargetForSource(manifest, source, kind) {
+  if (kind === "frontend") return `src/dypai-kits/${manifest.slug}/${stripFrontendPrefix(source)}`
+  if (kind === "backend") return `dypai/endpoints/${manifest.slug}/${source.split("/").pop()}`
+  if (kind === "database") return `dypai/kit-installations/${manifest.slug}/${manifest.version}/${source.split("/").pop()}`
+  return `.dypai/kits/${manifest.slug}/${source.split("/").pop()}`
+}
+
+function pluralize(word) {
+  if (!word) return word
+  if (word.endsWith("s")) return word
+  if (word.endsWith("y")) return `${word.slice(0, -1)}ies`
+  return `${word}s`
+}
+
+function namingContext(manifest, naming = {}) {
+  const adaptation = isObject(manifest.adaptation) ? manifest.adaptation : {}
+  const sourceEntity = adaptation.defaultEntity || normalizeList(adaptation.entityAliases)[0] || ""
+  const sourcePlural = adaptation.defaultEndpointPrefix || pluralize(sourceEntity)
+  const sourceTable = adaptation.defaultTableName || sourcePlural
+  const targetEntity = naming.entity || sourceEntity
+  const targetPlural = naming.endpointPrefix || pluralize(targetEntity)
+  const targetTable = naming.tableName || targetPlural
+  return { sourceEntity, sourcePlural, sourceTable, targetEntity, targetPlural, targetTable }
+}
+
+function replaceWholeWords(text, replacements) {
+  let out = text
+  for (const [from, to] of replacements) {
+    if (!from || !to || from === to) continue
+    out = out.replace(new RegExp(`\\b${from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "g"), to)
+  }
+  return out
+}
+
+function adaptText(content, manifest, naming, kind) {
+  const n = namingContext(manifest, naming)
+  if (!n.sourceEntity && !n.sourcePlural && !n.sourceTable) return content
+  if (kind === "frontend") return content
+
+  if (kind === "backend") {
+    const withEndpointName = content.replace(/^name:\s*([a-z0-9-]+)\s*$/m, (_line, endpointName) => {
+      return `name: ${adaptTarget(endpointName, manifest, naming)}`
+    })
+    return replaceWholeWords(withEndpointName, [
+      [n.sourceTable, n.targetTable],
+      [n.sourceEntity, n.targetEntity],
+    ])
+  }
+
+  return replaceWholeWords(content, [
+    [n.sourceTable, n.targetTable],
+    [n.sourcePlural, n.targetTable],
+    [n.sourceEntity, n.targetEntity],
+  ])
+}
+
+function adaptTarget(target, manifest, naming) {
+  const n = namingContext(manifest, naming)
+  return replaceWholeWords(target, [
+    [n.sourcePlural, n.targetPlural],
+    [n.sourceEntity, n.targetEntity],
+    [n.sourceTable, n.targetTable],
+  ])
+}
+
+function installRecordPath(workspaceRoot) {
+  return join(workspaceRoot, ".dypai", "kits", "installed.json")
+}
+
+function readInstallRecord(workspaceRoot) {
+  const path = installRecordPath(workspaceRoot)
+  if (!existsSync(path)) return { schemaVersion: 1, kits: [] }
+  try {
+    const parsed = readJson(path)
+    if (isObject(parsed) && Array.isArray(parsed.kits)) return parsed
+  } catch {}
+  return { schemaVersion: 1, kits: [] }
+}
+
+function writeInstallRecord(workspaceRoot, record) {
+  const path = installRecordPath(workspaceRoot)
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`)
+}
+
+function ownedTargets(record, slug, version) {
+  const targets = new Set()
+  for (const item of record.kits || []) {
+    if (item.slug === slug && item.version === version) {
+      for (const file of item.files || []) {
+        if (file.target) targets.add(file.target)
+      }
+    }
+  }
+  return targets
+}
+
+function writeTemplateFile({ sourceAbs, targetRel, workspaceRoot, manifest, naming, kind, overwrite, record, copied, skipped }) {
+  const targetAbs = safeTarget(workspaceRoot, targetRel)
+  const targetExists = existsSync(targetAbs)
+  if (targetExists) {
+    if (overwrite === "fail") throw new Error(`Target already exists: ${targetRel}`)
+    if (overwrite !== "replace" || !ownedTargets(record, manifest.slug, manifest.version).has(targetRel)) {
+      skipped.push(targetRel)
+      return
+    }
+  }
+
+  mkdirSync(dirname(targetAbs), { recursive: true })
+  const isText = /\.(tsx?|jsx?|ya?ml|json|md|sql|css|scss|html)$/i.test(sourceAbs)
+  if (isText) {
+    const content = adaptText(readFileSync(sourceAbs, "utf8"), manifest, naming, kind)
+    writeFileSync(targetAbs, content)
+  } else {
+    copyFileSync(sourceAbs, targetAbs)
+  }
+  copied.push(targetRel)
+}
+
+export const searchCapabilityKitsTool = {
+  name: "search_capability_kits",
+  description: "Search local DYPAI capability kits before building complex UI like calendars, maps, Kanban, upload flows, CRUD tables, dashboards, or editors.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Feature need and app domain, e.g. booking calendar for hotel reservations." },
+      limit: { type: "integer", default: DEFAULT_LIMIT, minimum: 1, maximum: 10 },
+      filters: { type: "object", description: "Optional filters: category, maturity, app_type, screen_type, feature_tag, requires." },
+      kits_root: { type: "string", description: "Optional local path to dypai-capability-kits. Defaults to DYPAI_CAPABILITY_KITS_ROOT or sibling repo." },
+    },
+    required: ["query"],
+  },
+  async execute({ query, limit = DEFAULT_LIMIT, filters = {}, kits_root }) {
+    const root = resolveKitsRoot(kits_root)
+    const kits = listKits(root)
+      .filter(({ manifest }) => matchesFilter(manifest, filters))
+      .map(({ manifest }) => ({ manifest, score: scoreKit(query, manifest) }))
+      .filter((item) => item.score > 0 || !query)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, Math.max(1, Math.min(Number(limit) || DEFAULT_LIMIT, 10)))
+
+    return {
+      ok: true,
+      source: "local_repo",
+      kitsRoot: root,
+      count: kits.length,
+      kits: kits.map(({ manifest, score }) => ({
+        slug: manifest.slug,
+        version: manifest.version,
+        name: manifest.name,
+        category: manifest.category,
+        maturity: manifest.maturity,
+        description: manifest.description,
+        useWhen: manifest.useWhen,
+        provides: manifest.provides,
+        requires: manifest.requires,
+        dependencies: manifest.dependencies,
+        frontendManifest: manifest.frontendManifest,
+        backendManifest: manifest.backendManifest,
+        databaseManifest: manifest.databaseManifest,
+        score,
+      })),
+    }
+  },
+}
+
+function inspectCapabilityKit({ slug, version = "1.0.0", kits_root }) {
+  const root = resolveKitsRoot(kits_root)
+  const { dir, manifest } = loadKit(root, slug, version)
+  return {
+    ok: true,
+    operation: "inspect",
+    source: "local_repo",
+    kitsRoot: root,
+    kit: manifest,
+    assets: assetIndex(dir),
+    agentNotes: existsSync(join(dir, "agent.md")) ? readFileSync(join(dir, "agent.md"), "utf8") : undefined,
+    checklist: existsSync(join(dir, "verification", "checklist.md"))
+      ? readFileSync(join(dir, "verification", "checklist.md"), "utf8")
+      : undefined,
+  }
+}
+
+async function applyCapabilityKit({
+  slug,
+  version = "1.0.0",
+  targetFeature = "",
+  install = {},
+  naming = {},
+  target = {},
+  overwrite = "skip",
+  workspace_root,
+  kits_root,
+}) {
+  const root = resolveKitsRoot(kits_root)
+  const workspaceRoot = resolveWorkspaceRoot(workspace_root)
+  const { dir, manifest } = loadKit(root, slug, version)
+  const record = readInstallRecord(workspaceRoot)
+  const previousEntries = (record.kits || []).filter((item) => item.slug === manifest.slug && item.version === manifest.version)
+  const copied = []
+  const skipped = []
+
+  const installFrontend = install.frontend !== false
+  const installBackend = install.backend !== false
+  const installDatabase = install.database !== false
+
+  if (installFrontend) {
+    for (const asset of manifest.frontendManifest || []) {
+      const sourceAbs = join(dir, asset.source)
+      if (!existsSync(sourceAbs)) throw new Error(`Missing kit asset: ${asset.source}`)
+      let targetRel = asset.suggestedTarget || defaultTargetForSource(manifest, asset.source, "frontend")
+      if (target.frontendDir) {
+        targetRel = join(target.frontendDir, stripFrontendPrefix(asset.source)).split(sep).join("/")
+      }
+      writeTemplateFile({ sourceAbs, targetRel, workspaceRoot, manifest, naming, kind: "frontend", overwrite, record, copied, skipped })
+    }
+  }
+
+  if (installBackend) {
+    for (const asset of manifest.backendManifest || []) {
+      const sourceAbs = join(dir, asset.source)
+      if (!existsSync(sourceAbs)) throw new Error(`Missing kit asset: ${asset.source}`)
+      let targetRel = asset.suggestedTarget || defaultTargetForSource(manifest, asset.source, "backend")
+      targetRel = join(dirname(targetRel), adaptTarget(basename(targetRel), manifest, naming)).split(sep).join("/")
+      if (target.endpointDir) {
+        targetRel = join(target.endpointDir, adaptTarget(asset.source.split("/").pop(), manifest, naming)).split(sep).join("/")
+      }
+      writeTemplateFile({ sourceAbs, targetRel, workspaceRoot, manifest, naming, kind: "backend", overwrite, record, copied, skipped })
+    }
+  }
+
+  if (installDatabase && isObject(manifest.databaseManifest)) {
+    for (const key of ["schema", "seed"]) {
+      const source = manifest.databaseManifest[key]
+      if (!source) continue
+      const sourceAbs = join(dir, source)
+      if (!existsSync(sourceAbs)) throw new Error(`Missing kit asset: ${source}`)
+      let targetRel = defaultTargetForSource(manifest, source, "database")
+      if (target.databaseDir) {
+        targetRel = join(target.databaseDir, source.split("/").pop()).split(sep).join("/")
+      }
+      writeTemplateFile({ sourceAbs, targetRel, workspaceRoot, manifest, naming, kind: "database", overwrite, record, copied, skipped })
+    }
+  }
+
+  const imported = (manifest.frontendManifest || []).map((asset) => ({
+    name: asset.exportName,
+    from: target.frontendDir
+      ? `@/${join(target.frontendDir, stripFrontendPrefix(asset.source)).replace(/^src\//, "").replace(/\\/g, "/").replace(/\.(tsx?|jsx?)$/, "")}`
+      : asset.importPath,
+  })).filter((item) => item.name && item.from)
+
+  const backendEndpoints = (manifest.backendManifest || []).map((asset) =>
+    adaptTarget(asset.endpointName || asset.source.split("/").pop().replace(/\.ya?ml$/, ""), manifest, naming),
+  )
+  const databaseTables = normalizeList(manifest.databaseManifest?.tables).map((table) =>
+    adaptTarget(table, manifest, naming),
+  )
+
+  const previousFiles = previousEntries.flatMap((item) => Array.isArray(item.files) ? item.files : [])
+  const fileMap = new Map()
+  for (const file of previousFiles) {
+    if (file?.target) fileMap.set(file.target, file)
+  }
+  for (const targetPath of copied) {
+    fileMap.set(targetPath, { target: targetPath })
+  }
+
+  const entry = {
+    slug: manifest.slug,
+    version: manifest.version,
+    installedAt: new Date().toISOString(),
+    targetFeature,
+    files: [...fileMap.values()],
+    skippedFiles: skipped,
+    naming,
+  }
+  record.kits = (record.kits || []).filter((item) => !(item.slug === manifest.slug && item.version === manifest.version))
+  record.kits.push(entry)
+  writeInstallRecord(workspaceRoot, record)
+
+  const dependencies = manifest.dependencies || []
+
+  return {
+    ok: true,
+    operation: "apply",
+    slug: manifest.slug,
+    version: manifest.version,
+    workspaceRoot,
+    installed: {
+      files: copied,
+      skipped,
+      recordFile: ".dypai/kits/installed.json",
+    },
+    imports: imported,
+    backend: {
+      endpoints: backendEndpoints,
+      requiresPublish: Boolean(manifest.install?.requiresBackendPublish || backendEndpoints.length),
+    },
+    database: {
+      tables: databaseTables,
+      requiresExecuteSql: Boolean(manifest.install?.requiresExecuteSql || databaseTables.length),
+    },
+    dependencies,
+    nextSteps: [
+      ...(dependencies.length
+        ? [`Add any missing package dependencies to the target workspace package.json, then install them locally before building: ${dependencies.join(", ")}.`]
+        : []),
+      "Wire installed frontend components into the selected app page or route.",
+      ...(databaseTables.length ? ["Apply the installed schema SQL with execute_sql if the tables do not already exist."] : []),
+      ...(backendEndpoints.length ? ["Run backend validation and endpoint tests for installed/renamed endpoints."] : []),
+      "Run frontend verification after wiring imports and data callbacks.",
+    ],
+  }
+}
+
+export const manageCapabilityKitTool = {
+  name: "manage_capability_kit",
+  description: "Inspect or install a local DYPAI capability kit. Use operation='inspect' after search when you need full manifest details, then operation='apply' to copy editable source into the workspace. Apply never executes SQL, publishes backend, deploys frontend, or installs npm packages.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      operation: { type: "string", enum: ["inspect", "apply"], description: "inspect returns manifest/assets. apply copies kit files into the workspace." },
+      slug: { type: "string" },
+      version: { type: "string", default: "1.0.0" },
+      targetFeature: { type: "string", description: "Domain/feature being built, e.g. hotel reservations." },
+      install: {
+        type: "object",
+        properties: {
+          frontend: { type: "boolean", default: true },
+          backend: { type: "boolean", default: true },
+          database: { type: "boolean", default: true },
+          examples: { type: "boolean", default: false },
+        },
+      },
+      naming: {
+        type: "object",
+        properties: {
+          entity: { type: "string", description: "Singular domain entity, e.g. reservation." },
+          endpointPrefix: { type: "string", description: "Plural endpoint/table-friendly domain name, e.g. reservations." },
+          tableName: { type: "string", description: "Database table name, e.g. reservations." },
+        },
+      },
+      target: {
+        type: "object",
+        properties: {
+          frontendDir: { type: "string" },
+          endpointDir: { type: "string" },
+          databaseDir: { type: "string" },
+        },
+      },
+      overwrite: { type: "string", enum: ["skip", "fail", "replace"], default: "skip" },
+      workspace_root: { type: "string", description: "Optional absolute path to the target app workspace." },
+      kits_root: { type: "string", description: "Optional local path to dypai-capability-kits." },
+    },
+    required: ["operation", "slug"],
+  },
+  async execute(args) {
+    if (args?.operation === "inspect") return inspectCapabilityKit(args)
+    if (args?.operation === "apply") return applyCapabilityKit(args)
+    throw new Error("manage_capability_kit requires operation 'inspect' or 'apply'.")
+  },
+}

package/src/tools/sync/planner.js

@@ -14,6 +14,8 @@ import YAML from "yaml"
 import { proxyToolCall } from "../proxy.js"
 import { deserializeEndpoint, serializeEndpoint } from "./codec.js"
 
+const ENDPOINT_NAME_RE = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/
+
 // ─── Remote ────────────────────────────────────────────────────────────────
 
 async function execSql(projectId, sql) {
@@ -198,6 +200,76 @@ async function findEndpointYamls(endpointsDir) {
   return out
 }
 
+function endpointFileSlug(rel) {
+  const filename = rel.split("/").pop() || ""
+  return filename.replace(/\.ya?ml$/i, "")
+}
+
+function validateEndpointNameContract(rel, doc) {
+  const expectedName = endpointFileSlug(rel)
+  if (!doc || typeof doc !== "object") {
+    return {
+      rule: "endpoint_yaml_root_invalid",
+      loc: "root",
+      error: "endpoint YAML must parse to an object",
+    }
+  }
+
+  if (typeof doc.name !== "string") {
+    return {
+      rule: "endpoint_missing_name",
+      loc: "name",
+      error: `endpoint name must be a string and must match the file basename '${expectedName}'`,
+      fix_hint: `Set name: ${expectedName}. The endpoint name is the public API slug and must match the file basename.`,
+    }
+  }
+
+  const name = doc.name.trim()
+  if (!name) {
+    return {
+      rule: "endpoint_missing_name",
+      loc: "name",
+      error: `endpoint is missing name; use name: ${expectedName}`,
+      fix_hint: `Set name: ${expectedName}.`,
+    }
+  }
+  if (name !== doc.name || !ENDPOINT_NAME_RE.test(name)) {
+    return {
+      rule: "endpoint_invalid_name_slug",
+      loc: "name",
+      error: `endpoint name '${doc.name}' is not a valid API slug; use lowercase letters, numbers, hyphens, or underscores only, with no spaces`,
+      fix_hint: "Do not put human titles in `name`; use `description` for labels.",
+    }
+  }
+  if (name !== expectedName) {
+    return {
+      rule: "endpoint_name_file_mismatch",
+      loc: "name",
+      error: `endpoint name '${name}' must match file basename '${expectedName}'`,
+      fix_hint: `Use name: ${expectedName}, or rename the file so both match.`,
+    }
+  }
+  if (doc.id != null) {
+    if (typeof doc.id !== "string" || doc.id.trim() !== doc.id || !doc.id.trim()) {
+      return {
+        rule: "endpoint_invalid_id",
+        loc: "id",
+        error: "endpoint id must be a non-empty string without surrounding spaces when present",
+        fix_hint: "Prefer omitting `id` in endpoint YAML. If present, it must exactly match `name`.",
+      }
+    }
+    if (doc.id !== name) {
+      return {
+        rule: "endpoint_id_name_mismatch",
+        loc: "id",
+        error: `endpoint id '${doc.id}' must match name '${name}'`,
+        fix_hint: "Prefer omitting `id` in endpoint YAML. If present, keep id, name, and file basename identical.",
+      }
+    }
+  }
+  return null
+}
+
 export async function readLocalState(rootDir) {
   const endpointsDir = join(rootDir, "endpoints")
   const yamls = await findEndpointYamls(endpointsDir)
@@ -209,8 +281,9 @@ export async function readLocalState(rootDir) {
     try {
       const raw = await readFile(join(endpointsDir, rel), "utf8")
       const doc = YAML.parse(raw)
-      if (!doc?.name) {
-        errors.push({ file: rel, error: "missing 'name' field" })
+      const nameError = validateEndpointNameContract(rel, doc)
+      if (nameError) {
+        errors.push({ file: rel, ...nameError })
         continue
       }
 
@@ -227,7 +300,7 @@ export async function readLocalState(rootDir) {
       )
       const fileMap = Object.fromEntries(refs.map((p, i) => [p, contents[i]]))
 
-      byName[doc.name] = { doc, fileMap }
+      byName[doc.name] = { doc, fileMap, file: rel, group }
     } catch (e) {
       errors.push({ file: rel, error: e.message })
     }

package/src/tools/sync/test.js

@@ -1,7 +1,8 @@
 /**
- * dypai_test — YAML-defined tests against endpoints. Zero engine changes:
- * orchestrates `execute_sql` + `test_workflow` (impersonation) + `execute_sql`
- * using what already exists.
+ * dypai_test — YAML-defined tests against endpoints. By default, endpoint
+ * names run through dypai_test_endpoint(mode:'local'), so tests execute the
+ * YAML currently on disk before dypai_push. UUID endpoint_id tests keep the
+ * legacy remote test_workflow path for backward compatibility.
  *
  * File layout (committable under dypai/tests/):
  *   endpoint: create-order        # or endpoint_id: <uuid>
@@ -26,6 +27,7 @@ import { join, resolve as resolvePath } from "path"
 import YAML from "yaml"
 import { proxyToolCall } from "../proxy.js"
 import { readLocalConfig } from "./planner.js"
+import { dypaiTestEndpointTool } from "./test-endpoint.js"
 
 // ─── Test file discovery ────────────────────────────────────────────────────
 
@@ -58,8 +60,8 @@ function firstCellOf(res) {
   return k ? row[k] : undefined
 }
 
-/** Resolve an endpoint name to its UUID via system.endpoints (the remote
- * test_workflow tool only accepts endpoint_id, not endpoint_name). */
+/** Resolve an endpoint name to its UUID via system.endpoints.
+ * Kept for legacy endpoint_id/remote test paths. */
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 async function resolveEndpointId(projectId, ref, cache) {
   if (UUID_RE.test(ref)) return ref
@@ -167,22 +169,41 @@ async function runSingleTest(test, fileCtx) {
   }
 
   try {
-    // Resolve endpoint → endpoint_id (remote only accepts UUIDs)
+    // Prefer testing the local endpoint YAML by name. This keeps the normal
+    // agent loop cheap: edit file -> dypai_test/dypai_test_endpoint -> push.
     const endpointRef = test.endpoint || test.endpoint_id || fileCtx.endpoint
     if (!endpointRef) {
       return { ...result, status: "error", errors: ["No endpoint specified. Set `endpoint` at file root or test level."] }
     }
-    const endpointId = await resolveEndpointId(fileCtx.projectId, endpointRef, fileCtx.endpointCache)
-
-    const execArgs = {
-      project_id: fileCtx.projectId,
-      endpoint_id: endpointId,
-      data: test.input || {},
-      trace_mode: "minimal",  // keep tests fast; detail on failure via dypai_trace
+    const testMode = test.mode || fileCtx.mode || "local"
+    let runResponse
+    if (!UUID_RE.test(endpointRef)) {
+      runResponse = await dypaiTestEndpointTool.execute({
+        endpoint: endpointRef,
+        mode: testMode,
+        input: test.input || {},
+        as_user: test.as_user,
+        trace_mode: "minimal",
+        root_dir: fileCtx.rootDir,
+        project_id: fileCtx.projectId,
+        // dypai_test is often a suite with many cases; run dypai_validate once
+        // before the suite if you want lint gating. Individual endpoint tests
+        // keep their own pre-flight validation by default.
+        skip_validation: test.skip_validation ?? fileCtx.skipValidation ?? true,
+      })
+    } else {
+      // Backward-compatible path for old tests that hard-code endpoint_id.
+      // This cannot read local YAML because UUIDs refer to remote rows.
+      const execArgs = {
+        project_id: fileCtx.projectId,
+        endpoint_id: endpointRef,
+        data: test.input || {},
+        trace_mode: "minimal",
+        draft_mode: testMode === "live" ? false : true,
+      }
+      if (test.as_user) execArgs.impersonated_user_id = test.as_user
+      runResponse = await proxyToolCall("test_workflow", execArgs)
     }
-    if (test.as_user) execArgs.impersonated_user_id = test.as_user
-
-    const runResponse = await proxyToolCall("test_workflow", execArgs)
 
     // Normalize what counts as the workflow "result body" (vary by engine version)
     const body = runResponse?.result ?? runResponse?.data ?? runResponse?.output ?? runResponse
@@ -194,12 +215,16 @@ async function runSingleTest(test, fileCtx) {
     // expect.success — did the workflow complete?
     if ("success" in expect) {
       const status = trace?.status ?? trace?.workflow?.status
-      const actualSuccess = status
+      const actualSuccess = runResponse?.success === false
+        ? false
+        : status
         ? status === "completed"
         : !runResponse?.error  // fallback: presence of error field
       if (actualSuccess !== expect.success) {
         result.errors.push(`expected success=${expect.success}, got ${actualSuccess}`)
       }
+    } else if (runResponse?.success === false) {
+      result.errors.push(`execution error: ${runResponse.error || "endpoint test failed"}`)
     }
 
     // expect.response — match body
@@ -260,19 +285,21 @@ async function runSingleTest(test, fileCtx) {
 export const dypaiTestTool = {
   name: "dypai_test",
   description:
-    "Run YAML-defined tests from dypai/tests/*.test.yaml. Each test does: setup_sql → test_workflow (with impersonation) → response assertions → db_queries assertions → teardown_sql. " +
-    "Uses existing remote tools (execute_sql, test_workflow) — no engine changes needed. " +
+    "Run YAML-defined tests from dypai/tests/*.test.yaml. By default, endpoint tests reference endpoint names and execute the LOCAL YAML from dypai/endpoints/** without requiring dypai_push. " +
+    "Each test does: setup_sql → dypai_test_endpoint/test_workflow (with impersonation) → response assertions → db_queries assertions → teardown_sql. " +
     "Pass `only` to run a subset (substring match on test name).",
   inputSchema: {
     type: "object",
     properties: {
       project_id: { type: "string", description: "Project UUID. Auto-resolved from dypai.config.yaml." },
       root_dir: { type: "string", default: "./dypai" },
+      mode: { type: "string", enum: ["local", "draft", "live"], default: "local", description: "Endpoint source for tests that reference endpoint names. local reads YAML on disk; draft/live test engine versions." },
+      skip_validation: { type: "boolean", default: true, description: "Pass through to local endpoint tests. Default true for suites; run dypai_validate separately for lint gating." },
       only: { type: "string", description: "Only run tests whose name includes this substring." },
       file: { type: "string", description: "Relative path to a single test file under dypai/tests/." },
     },
   },
-  async execute({ project_id, root_dir = "./dypai", only, file } = {}) {
+  async execute({ project_id, root_dir = "./dypai", mode = "local", skip_validation = true, only, file } = {}) {
     const rootDir = resolvePath(process.cwd(), root_dir)
     const config = await readLocalConfig(rootDir)
     const projectId = project_id || config?.project_id
@@ -316,6 +343,8 @@ export const dypaiTestTool = {
         endpoint: doc.endpoint || doc.endpoint_id,
         rootDir,
         endpointCache: new Map(),
+        mode: doc.mode || mode,
+        skipValidation: doc.skip_validation ?? skip_validation,
       }
       for (const t of tests) {
         if (only && !(t.name || "").toLowerCase().includes(only.toLowerCase())) continue

package/src/tools/sync/validate.js

@@ -235,24 +235,26 @@ function isRawCodePlaceholderSource(source, 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
- * operator. Examples:
- *   "input.limit | default(100)"  → "input.limit"
- *   "input.page ?? 1"              → "input.page"
- *   "nodes.foo.bar || 'x'"         → "nodes.foo.bar"
- *   "current_user_id | trim"       → "current_user_id"
- * Returns the trimmed/cleaned head (NOT just the leaf identifier — keeps
- * dotted paths intact so callers that split on '.' still work).
+ * Extract the first runtime path from an already-validated placeholder.
+ * Returns the trimmed/cleaned head (NOT just the leaf identifier), keeping
+ * dotted paths intact so callers that split on '.' still work.
  */
 function stripExprTail(expr) {
-  // Cut at the first character that can't be part of a path/identifier:
-  // whitespace, pipe (jinja-style filter), `?`, or `|`. Bracket access
-  // (e.g. items[0]) is preserved — callers split on '[' if they need to.
+  // Cut at the first character that can't be part of a path/identifier.
+  // Bracket access (e.g. items[0]) is preserved; callers split on '[' if
+  // they need to.
   const m = /^[\s]*([A-Za-z_$][A-Za-z_$0-9.\[\]]*)/.exec(expr)
   return m ? m[1] : expr.trim()
 }
 
+const RUNTIME_PLACEHOLDER_PATH_RE = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_-]*|\[[0-9]+\])*$/
+const RUNTIME_PLACEHOLDER_OPERATOR_RE = /(\|\||&&|\?\?|[?:+*/=<>!()]|\s+\b(?:or|and)\b\s+)/i
+
+function unsupportedRuntimePlaceholder(expr) {
+  const clean = expr.trim()
+  return expr !== clean || RUNTIME_PLACEHOLDER_OPERATOR_RE.test(clean) || !RUNTIME_PLACEHOLDER_PATH_RE.test(clean)
+}
+
 /** Minimal Levenshtein distance, caps at 3 for "did you mean" typo suggestions. */
 function levenshteinSmall(a, b) {
   if (a === b) return 0
@@ -407,11 +409,23 @@ function validateEndpoint(entry, ctx) {
   for (const { source, loc, value } of sources) {
     // --- Placeholder checks ---
     for (const expr of extractPlaceholders(value)) {
-      // Normalize: trim whitespace AND strip any template tail like
-      // ` | default(100)`, ` ?? 1`, ` || 'x'` — we only care about the
-      // path/identifier head. Without this, `${input.limit | default(100)}`
-      // would be parsed as property name "limit | default(100)" → false
-      // positive `input_placeholder_missing`.
+      if (unsupportedRuntimePlaceholder(expr)) {
+        diagnostics.push({
+          severity: "error",
+          rule: "unsupported_placeholder_expression",
+          endpoint: name, file, loc,
+          message: `\${${expr}} is not a simple runtime path the engine can resolve.`,
+          fix_hint:
+            `DYPAI placeholders are not JavaScript expressions. Use a single path like ` +
+            `\${input.file_path}, \${nodes.upload.storage_path}, or \${current_user_id}; ` +
+            `put fallback logic in the caller or split it into workflow nodes.`,
+        })
+        continue
+      }
+
+      // Normalize to the runtime path after rejecting expression syntax above.
+      // This keeps the downstream schema checks focused on the referenced
+      // input/node path instead of trying to interpret template logic.
       const e = stripExprTail(expr)
 
       // ${input.X} or ${input.X.Y}
@@ -1249,7 +1263,7 @@ export async function runValidation(rootDir, projectId) {
     schemaTables,
     catalog: nodeCatalog.schemas,
     knownTypes: nodeCatalog.knownTypes,
-    fileByName: Object.fromEntries(Object.values(local.byName).map(e => [e.doc.name, `endpoints/${e.doc.name}.yaml`])),
+    fileByName: Object.fromEntries(Object.values(local.byName).map(e => [e.doc.name, `endpoints/${e.file || `${e.doc.name}.yaml`}`])),
     // Collected during per-endpoint pass; resolved against the remote AFTER
     // all endpoints are checked (one batch query instead of N).
     suspectedMissingTables: [],
@@ -1329,9 +1343,11 @@ export async function runValidation(rootDir, projectId) {
   for (const err of local.errors || []) {
     diagnostics.push({
       severity: "error",
-      rule: "file_read_error",
+      rule: err.rule || "file_read_error",
       file: err.file,
+      loc: err.loc,
       message: err.error,
+      fix_hint: err.fix_hint,
     })
   }