@dypai-ai/mcp 1.5.10 → 1.5.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dypai-ai/mcp",
-  "version": "1.5.10",
+  "version": "1.5.12",
   "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
@@ -1014,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\`.
@@ -1039,6 +1059,7 @@ Mental translations: "edge function" → workflow with one code node; "cron" →
 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")\`.
 
@@ -1049,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}\`.
 
@@ -1100,7 +1121,7 @@ async function handleRequest(msg) {
     return makeResponse(id, {
       protocolVersion: "2024-11-05",
       capabilities: { tools: {} },
-      serverInfo: { name: "dypai", version: "1.3.1" },
+      serverInfo: { name: "dypai", version: "1.5.12" },
       instructions: SERVER_INSTRUCTIONS,
     })
   }

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/validate.js

@@ -235,24 +235,29 @@ 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()
+  if (expr !== clean) return true
+  if (RUNTIME_PLACEHOLDER_PATH_RE.test(clean)) return false
+  if (!RUNTIME_PLACEHOLDER_OPERATOR_RE.test(clean)) return true
+  return extractRuntimePaths(clean).length === 0
+}
+
 /** Minimal Levenshtein distance, caps at 3 for "did you mean" typo suggestions. */
 function levenshteinSmall(a, b) {
   if (a === b) return 0
@@ -285,6 +290,31 @@ async function readSchemaTables(rootDir) {
   }
 }
 
+/** Parse schema.sql to extract public table columns when available. */
+async function readSchemaColumns(rootDir) {
+  try {
+    const raw = await readFile(join(rootDir, "schema.sql"), "utf8")
+    const tables = {}
+    const tableRe = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?public\.(?:"([^"]+)"|([A-Za-z_]\w*))\s*\(([\s\S]*?)\);/gi
+    let m
+    while ((m = tableRe.exec(raw)) !== null) {
+      const tableName = m[1] || m[2]
+      const body = m[3] || ""
+      const cols = new Set()
+      for (const rawLine of body.split("\n")) {
+        const line = rawLine.trim().replace(/,$/, "")
+        if (!line || /^(CONSTRAINT|PRIMARY|FOREIGN|UNIQUE|CHECK|EXCLUDE)\b/i.test(line)) continue
+        const col = /^"?([A-Za-z_]\w*)"?\s+/.exec(line)?.[1]
+        if (col) cols.add(col)
+      }
+      tables[tableName] = cols
+    }
+    return tables
+  } catch {
+    return {}
+  }
+}
+
 /** Extract referenced table names from a SQL string: `FROM public.X`, `JOIN public.X`, `INTO public.X`, `UPDATE public.X`. */
 function extractSqlTables(sql) {
   const tables = new Set()
@@ -351,6 +381,288 @@ function lookupFileMapContent(fileMap, ref) {
   return fileMap[key] || fileMap[key.replace(/^dypai\//, "")] || fileMap[`dypai/${key}`] || ""
 }
 
+function stripSqlForInference(sql) {
+  return String(sql || "")
+    .replace(/--[^\n]*/g, " ")
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/'(?:[^']|'')*'/g, "''")
+    .replace(/\s+/g, " ")
+    .trim()
+}
+
+function isWordAt(sql, index, word) {
+  if (sql.slice(index, index + word.length).toLowerCase() !== word) return false
+  const before = index === 0 ? "" : sql[index - 1]
+  const after = sql[index + word.length] || ""
+  return !/[A-Za-z0-9_]/.test(before) && !/[A-Za-z0-9_]/.test(after)
+}
+
+function findOuterSelectList(sqlText) {
+  const sql = stripSqlForInference(sqlText)
+  if (!sql) return null
+  let depth = 0
+  let selectStart = -1
+  for (let i = 0; i < sql.length; i++) {
+    const ch = sql[i]
+    if (ch === "(") depth++
+    else if (ch === ")") depth = Math.max(0, depth - 1)
+
+    if (depth !== 0) continue
+    if (selectStart < 0 && isWordAt(sql, i, "select")) {
+      selectStart = i + "select".length
+      i += "select".length - 1
+      continue
+    }
+    if (selectStart >= 0 && isWordAt(sql, i, "from")) {
+      return sql.slice(selectStart, i).trim()
+    }
+  }
+  return null
+}
+
+function splitTopLevelComma(list) {
+  const parts = []
+  let depth = 0
+  let start = 0
+  for (let i = 0; i < list.length; i++) {
+    const ch = list[i]
+    if (ch === "(") depth++
+    else if (ch === ")") depth = Math.max(0, depth - 1)
+    else if (ch === "," && depth === 0) {
+      parts.push(list.slice(start, i).trim())
+      start = i + 1
+    }
+  }
+  const tail = list.slice(start).trim()
+  if (tail) parts.push(tail)
+  return parts
+}
+
+function inferSelectOutputColumns(sqlText) {
+  const selectList = findOuterSelectList(sqlText)
+  if (!selectList) return { properties: null, strict: false }
+
+  const props = new Set()
+  let strict = true
+  for (const itemRaw of splitTopLevelComma(selectList)) {
+    const item = itemRaw.trim()
+    if (!item || item === "*" || /\.\*$/.test(item)) {
+      strict = false
+      continue
+    }
+
+    const asAlias = /\bas\s+"?([A-Za-z_]\w*)"?$/i.exec(item)?.[1]
+    if (asAlias) {
+      props.add(asAlias)
+      continue
+    }
+
+    const simpleColumn = /^(?:(?:"?[A-Za-z_]\w*"?\.)?)"?([A-Za-z_]\w*)"?$/.exec(item)?.[1]
+    if (simpleColumn) {
+      props.add(simpleColumn)
+      continue
+    }
+
+    const trailingAlias = /\s+"?([A-Za-z_]\w*)"?$/.exec(item)?.[1]
+    if (trailingAlias && !SQL_KEYWORDS_AFTER_FROM.has(trailingAlias.toUpperCase())) {
+      props.add(trailingAlias)
+      continue
+    }
+
+    strict = false
+  }
+
+  return { properties: props.size > 0 ? props : null, strict }
+}
+
+function inferSqlCardinality(sqlText) {
+  const sql = stripSqlForInference(sqlText)
+  if (!sql) return null
+  if (/\blimit\s+1(?:\D|$)/i.test(sql)) return "single"
+  const startsLikeRead = /^(select|with)\b/i.test(sql)
+  const hasAggregate = /\b(count|sum|avg|min|max|json_agg|jsonb_agg|array_agg|string_agg)\s*\(/i.test(sql)
+  const hasGroupBy = /\bgroup\s+by\b/i.test(sql)
+  if (startsLikeRead && hasAggregate && !hasGroupBy) return "single"
+  return "many"
+}
+
+function returningColumns(returning, table, schemaColumns) {
+  if (Array.isArray(returning)) return new Set(returning.filter(v => typeof v === "string" && v !== "*"))
+  if (typeof returning === "string" && returning.trim() && returning.trim() !== "*") {
+    return new Set(returning.split(",").map(s => s.trim()).filter(Boolean))
+  }
+  if (table && schemaColumns?.[table]?.size) return new Set(schemaColumns[table])
+  return null
+}
+
+function buildNodeOutputContracts(nodes, fileMap, ctx) {
+  const contracts = new Map()
+  for (const node of nodes || []) {
+    if (!node || typeof node !== "object" || !node.id) continue
+    const nodeType = node.type ?? node.node_type
+    const params = nodeParams(node)
+
+    if (nodeType === "set_fields") {
+      const op = nodeField(node, params, "operation") || "set"
+      const fields = nodeField(node, params, "fields")
+      if (fields && typeof fields === "object" && !Array.isArray(fields)) {
+        contracts.set(node.id, {
+          type: "object",
+          properties: new Set(Object.keys(fields).map(k => k.split(".")[0])),
+          strict: op === "compose",
+        })
+      }
+      continue
+    }
+
+    if (nodeType !== "dypai_database") continue
+    const op = nodeField(node, params, "operation")
+    const table = nodeField(node, params, "table") ?? nodeField(node, params, "table_name")
+
+    if (op === "query" || op === "custom_query") {
+      const query = nodeField(node, params, "query") || lookupFileMapContent(fileMap, nodeField(node, params, "query_file"))
+      const inferred = inferSelectOutputColumns(query)
+      contracts.set(node.id, {
+        type: "array",
+        cardinality: inferSqlCardinality(query),
+        properties: inferred.properties,
+        strict: inferred.strict,
+      })
+      continue
+    }
+
+    if (op === "select") {
+      contracts.set(node.id, {
+        type: "array",
+        cardinality: "many",
+        properties: table ? ctx.schemaColumns?.[table] ?? null : null,
+        strict: Boolean(table && ctx.schemaColumns?.[table]),
+      })
+      continue
+    }
+
+    if (op === "aggregate") {
+      contracts.set(node.id, { type: "object", properties: new Set(["value"]), strict: true })
+      continue
+    }
+
+    if (op === "insert") {
+      const bulk = nodeField(node, params, "mode") === "bulk" || Array.isArray(nodeField(node, params, "data"))
+      contracts.set(node.id, {
+        type: bulk ? "array" : "object",
+        cardinality: bulk ? "many" : "single",
+        properties: table ? ctx.schemaColumns?.[table] ?? null : null,
+        strict: Boolean(table && ctx.schemaColumns?.[table]),
+      })
+      continue
+    }
+
+    if (op === "upsert") {
+      contracts.set(node.id, {
+        type: "object",
+        cardinality: "single",
+        properties: table ? ctx.schemaColumns?.[table] ?? null : null,
+        strict: Boolean(table && ctx.schemaColumns?.[table]),
+      })
+      continue
+    }
+
+    if (op === "update" || op === "delete" || op === "copy_to") {
+      contracts.set(node.id, {
+        type: "array",
+        cardinality: "many",
+        properties: table ? ctx.schemaColumns?.[table] ?? null : null,
+        strict: Boolean(table && ctx.schemaColumns?.[table]),
+      })
+      continue
+    }
+
+    if (op === "mutation") {
+      const insertValue = nodeField(node, params, "insert")
+      const updateValue = nodeField(node, params, "update")
+      const deleteValue = nodeField(node, params, "delete")
+      const returning = nodeField(node, params, "returning") ?? "*"
+      const props = returningColumns(returning, table, ctx.schemaColumns)
+      if (insertValue !== undefined && insertValue !== null) {
+        const bulk = nodeField(node, params, "mode") === "bulk" || Array.isArray(insertValue)
+        const hasConflict = nodeField(node, params, "on_conflict") !== undefined
+        contracts.set(node.id, {
+          type: bulk || hasConflict ? "array" : "object",
+          cardinality: bulk ? "many" : hasConflict ? "zero_or_one" : "single",
+          properties: props,
+          strict: Boolean(props),
+        })
+      } else if (updateValue !== undefined || deleteValue === true) {
+        contracts.set(node.id, {
+          type: "array",
+          cardinality: "many",
+          properties: props,
+          strict: Boolean(props),
+        })
+      }
+    }
+  }
+  return contracts
+}
+
+function extractRuntimePaths(expr) {
+  const clean = String(expr || "").replace(/'(?:[^']|'')*'|"(?:[^"\\]|\\.)*"/g, " ")
+  const paths = []
+  const re = /\b(?:input|nodes|vars|current_user)\.[A-Za-z_][A-Za-z0-9_-]*(?:\[[0-9]+\]|\.[A-Za-z_][A-Za-z0-9_-]*)*|\bcurrent_user_id\b|\bcurrent_user_role\b/g
+  let m
+  while ((m = re.exec(clean)) !== null) paths.push(m[0])
+  if (paths.length === 0 && RUNTIME_PLACEHOLDER_PATH_RE.test(expr.trim())) paths.push(expr.trim())
+  return [...new Set(paths)]
+}
+
+function parseNodeOutputRef(path) {
+  const m = /^nodes\.([A-Za-z_][A-Za-z0-9_-]*)(.*)$/.exec(path)
+  if (!m) return null
+  const nodeId = m[1]
+  let rest = m[2] || ""
+  let indexed = false
+  if (rest.startsWith("[")) {
+    const idx = /^\[[0-9]+\]/.exec(rest)?.[0]
+    if (idx) {
+      indexed = true
+      rest = rest.slice(idx.length)
+    }
+  }
+  const prop = rest.startsWith(".") ? /^\.([A-Za-z_][A-Za-z0-9_-]*)/.exec(rest)?.[1] : null
+  return { nodeId, indexed, prop }
+}
+
+function validateNodeOutputRef({ expr, path, contract, endpoint, file, loc }) {
+  const ref = parseNodeOutputRef(path)
+  if (!ref || !ref.prop || !contract) return null
+
+  if (contract.strict && contract.properties && !contract.properties.has(ref.prop)) {
+    const known = [...contract.properties]
+    const suggestions = known.filter(k => levenshteinSmall(k, ref.prop) <= 2).slice(0, 3)
+    return {
+      severity: "warn",
+      rule: "node_output_property_unknown",
+      endpoint, file, loc,
+      message: `\${${expr}} references '${ref.prop}', but node '${ref.nodeId}' is inferred to output: ${known.join(", ") || "(no known properties)"}.`,
+      fix_hint: suggestions.length
+        ? `Did you mean: ${suggestions.join(", ")}?`
+        : `Use one of: ${known.join(", ") || "(none)"}. If this is a dynamic SQL shape, verify with dypai_test_endpoint.`,
+    }
+  }
+
+  if (contract.type === "array" && contract.cardinality === "many" && !ref.indexed) {
+    return {
+      severity: "warn",
+      rule: "node_output_many_direct_property",
+      endpoint, file, loc,
+      message: `\${${expr}} reads property '${ref.prop}' directly from node '${ref.nodeId}', but that node is inferred to return many rows.`,
+      fix_hint: `Use \${nodes.${ref.nodeId}} for the full array, or \${nodes.${ref.nodeId}[0].${ref.prop}} if you intentionally want the first row.`,
+    }
+  }
+
+  return null
+}
+
 function collectMissingTableCandidates(ctx, referencedTables, endpoint, file) {
   if (!ctx.schemaTables) return
   for (const table of referencedTables) {
@@ -375,6 +687,7 @@ function validateEndpoint(entry, ctx) {
 
   const inputProps = doc.input?.properties || {}
   const nodeIds = new Set((doc.workflow?.nodes || []).map(n => n.id))
+  const outputContracts = buildNodeOutputContracts(doc.workflow?.nodes || [], fileMap, ctx)
 
   const jwt = ruleUsesJwt(doc.trigger)
 
@@ -407,12 +720,25 @@ 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`.
-      const e = stripExprTail(expr)
+      const runtimePaths = extractRuntimePaths(expr)
+      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 every runtime path we can find in this placeholder. Expressions
+      // such as `${nodes.x.stock >= input.qty}` are valid at runtime, so validate
+      // each referenced path instead of rejecting the whole expression.
+      for (const e of runtimePaths) {
 
       // ${input.X} or ${input.X.Y}
       // Only validate against the input schema if one is declared; DYPAI allows
@@ -448,6 +774,16 @@ function validateEndpoint(entry, ctx) {
           if (!missingNodeRefs.has(nodeId)) {
             missingNodeRefs.set(nodeId, { loc, expr })
           }
+        } else {
+          const outputDiag = validateNodeOutputRef({
+            expr,
+            path: e,
+            contract: outputContracts.get(nodeId),
+            endpoint: name,
+            file,
+            loc,
+          })
+          if (outputDiag) diagnostics.push(outputDiag)
         }
       }
 
@@ -463,6 +799,7 @@ function validateEndpoint(entry, ctx) {
           })
         }
       }
+      }
     }
 
     // NOTE: SQL table extraction used to live here (anywhere a string looked
@@ -1227,10 +1564,11 @@ export async function runValidation(rootDir, projectId) {
   const config = await readLocalConfig(rootDir)
   const targetProjectId = projectId || config?.project_id || null
 
-  const [local, remote, schemaTables, nodeCatalog] = await Promise.all([
+  const [local, remote, schemaTables, schemaColumns, nodeCatalog] = await Promise.all([
     readLocalState(rootDir),
     fetchRemoteState(targetProjectId),
     readSchemaTables(rootDir),
+    readSchemaColumns(rootDir),
     loadNodeCatalog(rootDir),
   ])
 
@@ -1247,9 +1585,10 @@ export async function runValidation(rootDir, projectId) {
     remoteCredentials,
     toolEndpoints,
     schemaTables,
+    schemaColumns,
     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 +1668,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,
     })
   }
 
@@ -1354,6 +1695,15 @@ export async function runValidation(rootDir, projectId) {
   }
 }
 
+export const __testing = {
+  buildNodeOutputContracts,
+  extractRuntimePaths,
+  inferSelectOutputColumns,
+  inferSqlCardinality,
+  unsupportedRuntimePlaceholder,
+  validateNodeOutputRef,
+}
+
 export const dypaiValidateTool = {
   name: "dypai_validate",
   description: