@sakupa/mcp 0.7.10 → 0.7.12

package/dist/bin.js

@@ -129,7 +129,7 @@ var FORBIDDEN_PATH_SEGMENTS = [
 var ALLOWED_HIDDEN_PATHS = [".well-known/"];
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "0.7.10";
+var SAKUPA_MCP_VERSION = "0.7.12";
 
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
@@ -686,7 +686,7 @@ var HttpApiClient = class {
 
 // src/tools/definitions.ts
 import { randomUUID } from "node:crypto";
-import { promises as fs2 } from "node:fs";
+import { existsSync as existsSync3, promises as fs2 } from "node:fs";
 import { join as join4, resolve as resolve3 } from "node:path";
 import { z as z3 } from "zod";
 
@@ -1196,14 +1196,18 @@ function deleteSiteFile(projectDir) {
     rmSync(path, { force: true });
   }
 }
-function isInsideGitRepo(projectDir) {
-  let dir = projectDir;
-  for (; ; ) {
-    if (existsSync(join2(dir, ".git"))) return true;
-    const parent = dirname(dir);
-    if (parent === dir) return false;
-    dir = parent;
+function findAncestor(startDir, predicate, maxLevels = Number.POSITIVE_INFINITY) {
+  let cursor = startDir;
+  for (let i = 0; i < maxLevels; i += 1) {
+    const parent = dirname(cursor);
+    if (parent === cursor) return null;
+    if (predicate(parent)) return parent;
+    cursor = parent;
   }
+  return null;
+}
+function isInsideGitRepo(projectDir) {
+  return existsSync(join2(projectDir, ".git")) || findAncestor(projectDir, (dir) => existsSync(join2(dir, ".git"))) !== null;
 }
 function credentialGitReminder(projectDir) {
   if (!isInsideGitRepo(projectDir)) return "";
@@ -1354,7 +1358,7 @@ async function diagnoseBinding(input) {
   const apexResolves = apexAnswers.length > 0;
   const allOk = checks.every((c) => c.state === "ok");
   const checklist = checks.map(renderCheck).join("\n") + `
-  [${apexResolves ? "OK" : "MISSING"}] APEX ${apex} \u2014 ` + (apexResolves ? "resolves." : `does not resolve yet: point it at ${input.servingTarget} using your DNS panel's ALIAS / ANAME / CNAME-flattening feature (an apex cannot use a plain CNAME).`);
+  [${apexResolves ? "OK" : "MISSING"}] APEX ${apex} \u2014 ` + (apexResolves ? "resolves." : `does not resolve yet. Three-step fix, stop at the first that works: (1) try adding a plain record \u2014 type CNAME, host @, value ${input.servingTarget} (most panels and Cloudflare accept this directly; confirm past any MX-conflict warning if the domain sends no email). (2) If rejected, look for ALIAS / ANAME / CNAME-flattening in the record-type list \u2014 same host and value. (3) If the panel has neither, skip the apex: www alone works fine (certificates do not depend on the apex record); optionally add a URL redirect from @ to www.`);
   const layers = `Pipeline: [1] public DNS (checked LIVE above) -> [2] Sakupa ownership verification: ${input.verificationStatus} -> [3] HTTPS certificate & serving: ` + (input.provisioning ? "provisioning (Cloudflare validates and issues within minutes once the records above are all OK; Sakupa retries automatically every ~5 minutes)." : "starts after verification.");
   return { checks, apexResolves, allOk, checklist, layers };
 }
@@ -1437,7 +1441,7 @@ var LocalGuidanceError = class extends SakupaError {
   }
 };
 var projectDirInput = z2.string().optional().describe(
-  "Absolute path of the project directory the user is CURRENTLY working in (the folder holding the site files and .sakupa). Always pass it explicitly; when omitted the server falls back to its startup directory, which may not be where the user is working now."
+  "Absolute path of the user's PROJECT ROOT \u2014 the folder the user opened/works in (for framework projects: where package.json lives, NEVER the build-output subfolder like dist/out; the analyzer locates the output automatically). .sakupa/site.json lives here, so PASS THE SAME DIRECTORY EVERY TIME for the same project. When omitted the server falls back to its startup directory, which may not be where the user is working now."
 );
 function withProjectDir(ctx, projectDirArg) {
   if (projectDirArg === void 0) return ctx;
@@ -1479,16 +1483,7 @@ function requireSiteFile(ctx) {
   }
   return state.file;
 }
-var STATIC_SUMMARY = {
-  not_found: "The required local project binding or resource is unavailable; if this project has no .sakupa/site.json yet, run deploy_site first.",
-  unauthorized: "The server rejected the site credential: the one in .sakupa/site.json no longer matches the server-side verifier. The site itself is intact on the server \u2014 only the local binding file is the problem. Repair the file (restore a backup or undo the local edit). Do NOT delete the .sakupa directory to work around this: the credential is unrecoverable by design, so abandoning it permanently orphans the existing site.",
-  invalid_request: "The request arguments or local project checks did not pass.",
-  validation_failed: "The request arguments or local project checks did not pass.",
-  state_conflict: "The resource state has changed; re-query the current status before deciding the next step.",
-  confirmation_required: "The site or billing state changed, so the previous confirmation is stale; run the preview again and confirm against the fresh snapshot.",
-  payment_required: "This operation requires an active subscription; check billing_status first.",
-  rate_limited: "The server rate limit was reached; retry after the returned wait time."
-};
+var UNAUTHORIZED_SUMMARY = "The server rejected the site credential: the one in .sakupa/site.json no longer matches the server-side verifier. The site itself is intact on the server \u2014 only the local binding file is the problem. Repair the file (restore a backup or undo the local edit). Do NOT delete the .sakupa directory to work around this: the credential is unrecoverable by design, so abandoning it permanently orphans the existing site.";
 function toolError(e) {
   const errorCode = isSakupaError(e) ? e.code : "internal";
   const retryable = errorCode === "rate_limited" || errorCode === "internal";
@@ -1507,7 +1502,8 @@ function toolError(e) {
     )
   ) : void 0;
   const minimumVersion = rawDetails && typeof rawDetails["minimumVersion"] === "string" ? rawDetails["minimumVersion"] : void 0;
-  const safeSummary = e instanceof LocalGuidanceError ? e.message : errorCode === "upgrade_required" ? `This Sakupa MCP client is v${MCP_VERSION}, older than the server's minimum supported version${minimumVersion !== void 0 ? ` (v${minimumVersion})` : ""}, so the server refused the call. To fix it: ask the user to fully restart their MCP client session \u2014 "npx -y @sakupa/mcp@latest" setups fetch the current version on restart (run "npx clear-npx-cache" first if the old version persists); global installs need "npm install -g @sakupa/mcp@latest". After the restart, retry this exact tool call.` : STATIC_SUMMARY[errorCode] ?? (retryable ? "An upstream service is temporarily unavailable or busy; retry shortly." : "The operation failed; no server-internal details are exposed.");
+  const serverGuidance = isSakupaError(e) && errorCode !== "internal" && errorCode !== "unauthorized" && errorCode !== "upgrade_required" && e.message.trim().length > 0 ? e.message : void 0;
+  const safeSummary = e instanceof LocalGuidanceError ? e.message : errorCode === "upgrade_required" ? `This Sakupa MCP client is v${MCP_VERSION}, older than the server's minimum supported version${minimumVersion !== void 0 ? ` (v${minimumVersion})` : ""}, so the server refused the call. To fix it: ask the user to fully restart their MCP client session \u2014 "npx -y @sakupa/mcp@latest" setups fetch the current version on restart (run "npx clear-npx-cache" first if the old version persists); global installs need "npm install -g @sakupa/mcp@latest". After the restart, retry this exact tool call.` : errorCode === "unauthorized" ? UNAUTHORIZED_SUMMARY : serverGuidance ?? (retryable ? "An upstream service is temporarily unavailable or busy; retry shortly." : "The operation failed; no server-internal details are exposed.");
   const result = structuredToolResult({
     schemaVersion: 1,
     outcome: "failed",
@@ -1661,6 +1657,20 @@ ${block}`, checklist: toDnsChecklist(diag.checks) };
     };
   }
 }
+function projectRootAbove(projectDir) {
+  if (existsSync3(join4(projectDir, "package.json"))) return null;
+  return findAncestor(projectDir, (dir) => existsSync3(join4(dir, "package.json")), 4);
+}
+function findNeighborBinding(projectDir, outputRel) {
+  const bound = (dir) => loadSiteFile(dir).kind !== "absent";
+  const above = findAncestor(projectDir, bound, 3);
+  if (above) return above;
+  if (outputRel && outputRel !== ".") {
+    const outputAbs = resolve3(projectDir, outputRel);
+    if (bound(outputAbs)) return outputAbs;
+  }
+  return null;
+}
 function freeSiteCreationBarrier() {
   const recent = listRecentCreations(Date.now());
   if (recent.length < FREE_ACTIVE_SITES_PER_IP) return null;
@@ -1721,6 +1731,9 @@ Next action: ${analysis.suggestedNextAction}`,
         publicConfirmed: z3.boolean().optional().describe(
           "Required only for the first deployment: user explicitly confirmed creation of a public 24-hour URL."
         ),
+        subprojectConfirmed: z3.boolean().optional().describe(
+          "Only when creating a NEW site in a subfolder of a package.json project: the user explicitly confirmed this subfolder is an INDEPENDENT site, not the project's build output."
+        ),
         lang: z3.string().optional().describe("Site language override (en | ja | zh-CN); defaults to the html lang.")
       }
     },
@@ -1749,16 +1762,34 @@ Next action: ${analysis.suggestedNextAction}`,
         }
         const existing = siteFileState.kind === "ok" ? siteFileState.file : null;
         if (!existing) {
+          const rootAbove = args.subprojectConfirmed === true ? null : projectRootAbove(ctx.projectDir);
+          if (rootAbove) {
+            return text(
+              "not_project_root",
+              `${ctx.projectDir} has no package.json but ${rootAbove} does \u2014 this directory is a SUBFOLDER of that project (typically its build output), and .sakupa must live at the project ROOT. Re-run deploy_site with projectDir: ${rootAbove}. Only if the user explicitly says this subfolder is an INDEPENDENT site (e.g. a docs/ site inside a repo), re-run with subprojectConfirmed: true. Nothing was deployed and no site was created.`,
+              { projectRoot: rootAbove, confirmationField: "subprojectConfirmed" },
+              "blocked"
+            );
+          }
+          const neighbor = findNeighborBinding(ctx.projectDir, analysis.recommendedOutputDir);
+          if (neighbor) {
+            return text(
+              "neighbor_binding_found",
+              `No .sakupa binding in ${ctx.projectDir}, but one EXISTS at ${neighbor} \u2014 this looks like the same project addressed at a different directory level. To update that existing site, re-run deploy_site with projectDir: ${neighbor}. Only if the user explicitly wants a SEPARATE new site, move this deploy to a directory outside that project. Nothing was deployed and no site was created.`,
+              { neighborProjectDir: neighbor },
+              "blocked"
+            );
+          }
           const barrier = freeSiteCreationBarrier();
           if (barrier) return barrier;
-        }
-        if (!existing && args.publicConfirmed !== true) {
-          return text(
-            "public_deployment_confirmation_required",
-            `First deployment creates a public URL that anyone with the link can open. The free preview stays live for ${FREE_SITE_TTL_HOURS} hours. Explain this to the user and obtain explicit confirmation before retrying deploy_site with publicConfirmed: true.`,
-            { publicUrlLifetimeHours: FREE_SITE_TTL_HOURS, confirmationField: "publicConfirmed" },
-            "waiting_user"
-          );
+          if (args.publicConfirmed !== true) {
+            return text(
+              "public_deployment_confirmation_required",
+              `First deployment creates a public URL that anyone with the link can open. The free preview stays live for ${FREE_SITE_TTL_HOURS} hours. Explain this to the user and obtain explicit confirmation before retrying deploy_site with publicConfirmed: true.`,
+              { publicUrlLifetimeHours: FREE_SITE_TTL_HOURS, confirmationField: "publicConfirmed" },
+              "waiting_user"
+            );
+          }
         }
         ensureUploadSizeWithinLimits(manifest, !existing);
         if (!existing) {
@@ -1982,7 +2013,7 @@ Once payment confirms, the site becomes permanent on its current URL. Binding a
   server.registerTool(
     "bind_domain",
     {
-      description: `Bind a custom domain to this subscribed site \u2014 an OPTIONAL extra serving surface; the permanent ${previewHostPattern} URL keeps working alongside it. The binding unit is the APEX domain: binding example.com automatically includes www.example.com (both serve the same content, one apex TXT verification covers both), and one site binds at most ONE apex domain \u2014 a second domain needs a second subscribed site. Requires an ACTIVE subscription (subscribe_site). Ownership is proven ONLY by DNS control of the apex \u2014 payment never grants ownership. A binding request never reserves the domain: whoever proves DNS control first gets it, and unverified requests expire after 72 hours. Call again with verificationId to check progress.`,
+      description: `Bind a custom domain to this subscribed site \u2014 an OPTIONAL extra serving surface; the permanent ${previewHostPattern} URL keeps working alongside it. The binding unit is the APEX domain: binding example.com automatically includes www.example.com (both serve the same content, one apex TXT verification covers both), and one site binds at most ONE apex domain \u2014 a second domain needs a second subscribed site. Requires an ACTIVE subscription (subscribe_site). Ownership is proven ONLY by DNS control of the apex \u2014 payment never grants ownership, and bindings are ALWAYS challengeable: whoever proves CURRENT DNS control takes the domain, even from an existing binding (the displaced site keeps its subscription, content and permanent URL). Unverified requests expire after 72 hours. Call again with action "status" to check progress.`,
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
       inputSchema: {
@@ -2051,17 +2082,19 @@ ${res2.message}
           "domain_verification_started",
           `Domain binding started for ${apex} (includes: ${res.includedHostnames.join(", ")} \u2014 both will serve this site).
 
-Add ALL THREE DNS records NOW (adding them together lets verification, certificate issuance and serving complete without further record changes):
+STEP 1 of 2 \u2014 add ALL THREE records NOW:
 
   1) TXT    host: ${txtShort}   value: ${res.verificationRecord.value}
   2) CNAME  host: www   value: ${res.servingTarget}
-  3) APEX   host: @   -> ${res.servingTarget} via your DNS panel's ALIAS / ANAME / CNAME-flattening feature (an apex cannot use a plain CNAME).
+  3) APEX   host: @   -> ${res.servingTarget}. Try a plain CNAME at host @ first (most panels accept it); if rejected use ALIAS / ANAME / CNAME-flattening; if the panel has neither, skip it \u2014 www alone works, and a URL redirect from @ to www covers bare-domain visitors.
 
 Host fields above are the SHORT form: most DNS panels append the domain automatically. After saving, the record list must NOT show ${apex} twice in one name \u2014 that means the full name was pasted into an auto-appending field.
 
 Ownership comes ONLY from DNS control; paying never grants it. The first verified request wins and this challenge expires after 72 hours.
 
-Then run bind_domain with action "status" \u2014 it live-checks every record and names the exact fix for anything wrong. Re-check every 5 minutes (up to 10 times). Any later session can resume with action "status" alone; the verificationId is optional.`,
+STEP 2 (after ownership verifies): Cloudflare issues certificate-validation TXT records \u2014 the verification result and bind_domain "status" list them the moment they exist; relay each to the user and add them too. Everything then completes automatically.
+
+Drive the whole flow with bind_domain "status": it live-checks every record and names the exact fix for anything wrong. Re-check every 5 minutes (up to 10 times). Any later session can resume with action "status" alone; the verificationId is optional.`,
           {
             verificationId: res.verificationId,
             apexDomain: apex,
@@ -2371,9 +2404,10 @@ ${res.archiveUrl}`,
           ...args.contactEmail !== void 0 ? { contactEmail: args.contactEmail } : {}
         };
         if (args.confirmSubmit !== true) {
+          const contactNote = args.contactEmail !== void 0 ? "note that their contact email is attached for follow-up. " : "ASK THEM ONCE whether they want to attach a contact email for follow-up (optional \u2014 omit if declined; include it as contactEmail when they do). ";
           return textJson(
             "bug_report_preview_ready",
-            "Bug report prepared but NOT submitted. This is the exact payload that would be sent (structured diagnostics only \u2014 no file contents, source code or secrets). Please show it to the user; re-run report_bug with confirmSubmit: true to submit.",
+            `Bug report prepared but NOT submitted. This is the exact payload that would be sent (structured diagnostics only \u2014 no file contents, source code or secrets). Show it to the user, and ${contactNote}Then re-run report_bug with confirmSubmit: true to submit.`,
             payload,
             "preview"
           );
@@ -2709,13 +2743,18 @@ Workflow:
 
 Project directory contract: ONE directory = ONE site (its .sakupa/site.json holds the
 binding). Every project-scoped tool accepts projectDir \u2014 ALWAYS pass the absolute path of
-the directory the user is currently working in, on every call. Without it the server falls
-back to its startup directory, which may be a different project than the one the user is
-looking at. After every deploy, TELL the user which environment it went to (deploy results carry an
+the user's PROJECT ROOT, the SAME directory every time for the same project: the folder
+the user opened (for framework projects, where package.json lives \u2014 never the dist/out
+build folder; output is auto-detected). Without it the server falls back to its startup
+directory, which may be a different project than the one the user is looking at. After every deploy, TELL the user which environment it went to (deploy results carry an
 Explicit Environment line: TEST vs PRODUCTION). analyze_site, deploy_site, site_status,
 refresh_site, delete_site and unbind_domain echo
 the directory they acted on \u2014 verify it matches the user's active project.
 
+When the same operation fails twice in a row, or the user is clearly stuck or
+frustrated, proactively offer report_bug: it files the problem into Sakupa's ticket and
+alert stream, and you should attach your own factual account via agentContext.
+
 Safety boundaries:
 - Static output only: no SSR, API routes, middleware, server actions, databases or online builds.
 - Never upload source projects, secrets, .env files, private keys, archives, videos or audio.

package/dist/index.js

@@ -124,7 +124,7 @@ var FORBIDDEN_PATH_SEGMENTS = [
 var ALLOWED_HIDDEN_PATHS = [".well-known/"];
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "0.7.10";
+var SAKUPA_MCP_VERSION = "0.7.12";
 
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
@@ -839,14 +839,18 @@ function deleteSiteFile(projectDir) {
     rmSync(path, { force: true });
   }
 }
-function isInsideGitRepo(projectDir) {
-  let dir = projectDir;
-  for (; ; ) {
-    if (existsSync(join(dir, ".git"))) return true;
-    const parent = dirname(dir);
-    if (parent === dir) return false;
-    dir = parent;
+function findAncestor(startDir, predicate, maxLevels = Number.POSITIVE_INFINITY) {
+  let cursor = startDir;
+  for (let i = 0; i < maxLevels; i += 1) {
+    const parent = dirname(cursor);
+    if (parent === cursor) return null;
+    if (predicate(parent)) return parent;
+    cursor = parent;
   }
+  return null;
+}
+function isInsideGitRepo(projectDir) {
+  return existsSync(join(projectDir, ".git")) || findAncestor(projectDir, (dir) => existsSync(join(dir, ".git"))) !== null;
 }
 function credentialGitReminder(projectDir) {
   if (!isInsideGitRepo(projectDir)) return "";
@@ -1326,7 +1330,7 @@ var LocalGuidanceError = class extends SakupaError {
   }
 };
 var projectDirInput = z2.string().optional().describe(
-  "Absolute path of the project directory the user is CURRENTLY working in (the folder holding the site files and .sakupa). Always pass it explicitly; when omitted the server falls back to its startup directory, which may not be where the user is working now."
+  "Absolute path of the user's PROJECT ROOT \u2014 the folder the user opened/works in (for framework projects: where package.json lives, NEVER the build-output subfolder like dist/out; the analyzer locates the output automatically). .sakupa/site.json lives here, so PASS THE SAME DIRECTORY EVERY TIME for the same project. When omitted the server falls back to its startup directory, which may not be where the user is working now."
 );
 function withProjectDir(ctx, projectDirArg) {
   if (projectDirArg === void 0) return ctx;
@@ -1368,16 +1372,7 @@ function requireSiteFile(ctx) {
   }
   return state.file;
 }
-var STATIC_SUMMARY = {
-  not_found: "The required local project binding or resource is unavailable; if this project has no .sakupa/site.json yet, run deploy_site first.",
-  unauthorized: "The server rejected the site credential: the one in .sakupa/site.json no longer matches the server-side verifier. The site itself is intact on the server \u2014 only the local binding file is the problem. Repair the file (restore a backup or undo the local edit). Do NOT delete the .sakupa directory to work around this: the credential is unrecoverable by design, so abandoning it permanently orphans the existing site.",
-  invalid_request: "The request arguments or local project checks did not pass.",
-  validation_failed: "The request arguments or local project checks did not pass.",
-  state_conflict: "The resource state has changed; re-query the current status before deciding the next step.",
-  confirmation_required: "The site or billing state changed, so the previous confirmation is stale; run the preview again and confirm against the fresh snapshot.",
-  payment_required: "This operation requires an active subscription; check billing_status first.",
-  rate_limited: "The server rate limit was reached; retry after the returned wait time."
-};
+var UNAUTHORIZED_SUMMARY = "The server rejected the site credential: the one in .sakupa/site.json no longer matches the server-side verifier. The site itself is intact on the server \u2014 only the local binding file is the problem. Repair the file (restore a backup or undo the local edit). Do NOT delete the .sakupa directory to work around this: the credential is unrecoverable by design, so abandoning it permanently orphans the existing site.";
 function toolError(e) {
   const errorCode = isSakupaError(e) ? e.code : "internal";
   const retryable = errorCode === "rate_limited" || errorCode === "internal";
@@ -1396,7 +1391,8 @@ function toolError(e) {
     )
   ) : void 0;
   const minimumVersion = rawDetails && typeof rawDetails["minimumVersion"] === "string" ? rawDetails["minimumVersion"] : void 0;
-  const safeSummary = e instanceof LocalGuidanceError ? e.message : errorCode === "upgrade_required" ? `This Sakupa MCP client is v${MCP_VERSION}, older than the server's minimum supported version${minimumVersion !== void 0 ? ` (v${minimumVersion})` : ""}, so the server refused the call. To fix it: ask the user to fully restart their MCP client session \u2014 "npx -y @sakupa/mcp@latest" setups fetch the current version on restart (run "npx clear-npx-cache" first if the old version persists); global installs need "npm install -g @sakupa/mcp@latest". After the restart, retry this exact tool call.` : STATIC_SUMMARY[errorCode] ?? (retryable ? "An upstream service is temporarily unavailable or busy; retry shortly." : "The operation failed; no server-internal details are exposed.");
+  const serverGuidance = isSakupaError(e) && errorCode !== "internal" && errorCode !== "unauthorized" && errorCode !== "upgrade_required" && e.message.trim().length > 0 ? e.message : void 0;
+  const safeSummary = e instanceof LocalGuidanceError ? e.message : errorCode === "upgrade_required" ? `This Sakupa MCP client is v${MCP_VERSION}, older than the server's minimum supported version${minimumVersion !== void 0 ? ` (v${minimumVersion})` : ""}, so the server refused the call. To fix it: ask the user to fully restart their MCP client session \u2014 "npx -y @sakupa/mcp@latest" setups fetch the current version on restart (run "npx clear-npx-cache" first if the old version persists); global installs need "npm install -g @sakupa/mcp@latest". After the restart, retry this exact tool call.` : errorCode === "unauthorized" ? UNAUTHORIZED_SUMMARY : serverGuidance ?? (retryable ? "An upstream service is temporarily unavailable or busy; retry shortly." : "The operation failed; no server-internal details are exposed.");
   const result = structuredToolResult({
     schemaVersion: 1,
     outcome: "failed",
@@ -1414,7 +1410,7 @@ function toolError(e) {
 
 // src/tools/definitions.ts
 import { randomUUID } from "node:crypto";
-import { promises as fs2 } from "node:fs";
+import { existsSync as existsSync3, promises as fs2 } from "node:fs";
 import { join as join4, resolve as resolve3 } from "node:path";
 import { z as z3 } from "zod";
 
@@ -1562,7 +1558,7 @@ async function diagnoseBinding(input) {
   const apexResolves = apexAnswers.length > 0;
   const allOk = checks.every((c) => c.state === "ok");
   const checklist = checks.map(renderCheck).join("\n") + `
-  [${apexResolves ? "OK" : "MISSING"}] APEX ${apex} \u2014 ` + (apexResolves ? "resolves." : `does not resolve yet: point it at ${input.servingTarget} using your DNS panel's ALIAS / ANAME / CNAME-flattening feature (an apex cannot use a plain CNAME).`);
+  [${apexResolves ? "OK" : "MISSING"}] APEX ${apex} \u2014 ` + (apexResolves ? "resolves." : `does not resolve yet. Three-step fix, stop at the first that works: (1) try adding a plain record \u2014 type CNAME, host @, value ${input.servingTarget} (most panels and Cloudflare accept this directly; confirm past any MX-conflict warning if the domain sends no email). (2) If rejected, look for ALIAS / ANAME / CNAME-flattening in the record-type list \u2014 same host and value. (3) If the panel has neither, skip the apex: www alone works fine (certificates do not depend on the apex record); optionally add a URL redirect from @ to www.`);
   const layers = `Pipeline: [1] public DNS (checked LIVE above) -> [2] Sakupa ownership verification: ${input.verificationStatus} -> [3] HTTPS certificate & serving: ` + (input.provisioning ? "provisioning (Cloudflare validates and issues within minutes once the records above are all OK; Sakupa retries automatically every ~5 minutes)." : "starts after verification.");
   return { checks, apexResolves, allOk, checklist, layers };
 }
@@ -1725,6 +1721,20 @@ ${block}`, checklist: toDnsChecklist(diag.checks) };
     };
   }
 }
+function projectRootAbove(projectDir) {
+  if (existsSync3(join4(projectDir, "package.json"))) return null;
+  return findAncestor(projectDir, (dir) => existsSync3(join4(dir, "package.json")), 4);
+}
+function findNeighborBinding(projectDir, outputRel) {
+  const bound = (dir) => loadSiteFile(dir).kind !== "absent";
+  const above = findAncestor(projectDir, bound, 3);
+  if (above) return above;
+  if (outputRel && outputRel !== ".") {
+    const outputAbs = resolve3(projectDir, outputRel);
+    if (bound(outputAbs)) return outputAbs;
+  }
+  return null;
+}
 function freeSiteCreationBarrier() {
   const recent = listRecentCreations(Date.now());
   if (recent.length < FREE_ACTIVE_SITES_PER_IP) return null;
@@ -1785,6 +1795,9 @@ Next action: ${analysis.suggestedNextAction}`,
         publicConfirmed: z3.boolean().optional().describe(
           "Required only for the first deployment: user explicitly confirmed creation of a public 24-hour URL."
         ),
+        subprojectConfirmed: z3.boolean().optional().describe(
+          "Only when creating a NEW site in a subfolder of a package.json project: the user explicitly confirmed this subfolder is an INDEPENDENT site, not the project's build output."
+        ),
         lang: z3.string().optional().describe("Site language override (en | ja | zh-CN); defaults to the html lang.")
       }
     },
@@ -1813,16 +1826,34 @@ Next action: ${analysis.suggestedNextAction}`,
         }
         const existing = siteFileState.kind === "ok" ? siteFileState.file : null;
         if (!existing) {
+          const rootAbove = args.subprojectConfirmed === true ? null : projectRootAbove(ctx.projectDir);
+          if (rootAbove) {
+            return text(
+              "not_project_root",
+              `${ctx.projectDir} has no package.json but ${rootAbove} does \u2014 this directory is a SUBFOLDER of that project (typically its build output), and .sakupa must live at the project ROOT. Re-run deploy_site with projectDir: ${rootAbove}. Only if the user explicitly says this subfolder is an INDEPENDENT site (e.g. a docs/ site inside a repo), re-run with subprojectConfirmed: true. Nothing was deployed and no site was created.`,
+              { projectRoot: rootAbove, confirmationField: "subprojectConfirmed" },
+              "blocked"
+            );
+          }
+          const neighbor = findNeighborBinding(ctx.projectDir, analysis.recommendedOutputDir);
+          if (neighbor) {
+            return text(
+              "neighbor_binding_found",
+              `No .sakupa binding in ${ctx.projectDir}, but one EXISTS at ${neighbor} \u2014 this looks like the same project addressed at a different directory level. To update that existing site, re-run deploy_site with projectDir: ${neighbor}. Only if the user explicitly wants a SEPARATE new site, move this deploy to a directory outside that project. Nothing was deployed and no site was created.`,
+              { neighborProjectDir: neighbor },
+              "blocked"
+            );
+          }
           const barrier = freeSiteCreationBarrier();
           if (barrier) return barrier;
-        }
-        if (!existing && args.publicConfirmed !== true) {
-          return text(
-            "public_deployment_confirmation_required",
-            `First deployment creates a public URL that anyone with the link can open. The free preview stays live for ${FREE_SITE_TTL_HOURS} hours. Explain this to the user and obtain explicit confirmation before retrying deploy_site with publicConfirmed: true.`,
-            { publicUrlLifetimeHours: FREE_SITE_TTL_HOURS, confirmationField: "publicConfirmed" },
-            "waiting_user"
-          );
+          if (args.publicConfirmed !== true) {
+            return text(
+              "public_deployment_confirmation_required",
+              `First deployment creates a public URL that anyone with the link can open. The free preview stays live for ${FREE_SITE_TTL_HOURS} hours. Explain this to the user and obtain explicit confirmation before retrying deploy_site with publicConfirmed: true.`,
+              { publicUrlLifetimeHours: FREE_SITE_TTL_HOURS, confirmationField: "publicConfirmed" },
+              "waiting_user"
+            );
+          }
         }
         ensureUploadSizeWithinLimits(manifest, !existing);
         if (!existing) {
@@ -2046,7 +2077,7 @@ Once payment confirms, the site becomes permanent on its current URL. Binding a
   server.registerTool(
     "bind_domain",
     {
-      description: `Bind a custom domain to this subscribed site \u2014 an OPTIONAL extra serving surface; the permanent ${previewHostPattern} URL keeps working alongside it. The binding unit is the APEX domain: binding example.com automatically includes www.example.com (both serve the same content, one apex TXT verification covers both), and one site binds at most ONE apex domain \u2014 a second domain needs a second subscribed site. Requires an ACTIVE subscription (subscribe_site). Ownership is proven ONLY by DNS control of the apex \u2014 payment never grants ownership. A binding request never reserves the domain: whoever proves DNS control first gets it, and unverified requests expire after 72 hours. Call again with verificationId to check progress.`,
+      description: `Bind a custom domain to this subscribed site \u2014 an OPTIONAL extra serving surface; the permanent ${previewHostPattern} URL keeps working alongside it. The binding unit is the APEX domain: binding example.com automatically includes www.example.com (both serve the same content, one apex TXT verification covers both), and one site binds at most ONE apex domain \u2014 a second domain needs a second subscribed site. Requires an ACTIVE subscription (subscribe_site). Ownership is proven ONLY by DNS control of the apex \u2014 payment never grants ownership, and bindings are ALWAYS challengeable: whoever proves CURRENT DNS control takes the domain, even from an existing binding (the displaced site keeps its subscription, content and permanent URL). Unverified requests expire after 72 hours. Call again with action "status" to check progress.`,
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
       inputSchema: {
@@ -2115,17 +2146,19 @@ ${res2.message}
           "domain_verification_started",
           `Domain binding started for ${apex} (includes: ${res.includedHostnames.join(", ")} \u2014 both will serve this site).
 
-Add ALL THREE DNS records NOW (adding them together lets verification, certificate issuance and serving complete without further record changes):
+STEP 1 of 2 \u2014 add ALL THREE records NOW:
 
   1) TXT    host: ${txtShort}   value: ${res.verificationRecord.value}
   2) CNAME  host: www   value: ${res.servingTarget}
-  3) APEX   host: @   -> ${res.servingTarget} via your DNS panel's ALIAS / ANAME / CNAME-flattening feature (an apex cannot use a plain CNAME).
+  3) APEX   host: @   -> ${res.servingTarget}. Try a plain CNAME at host @ first (most panels accept it); if rejected use ALIAS / ANAME / CNAME-flattening; if the panel has neither, skip it \u2014 www alone works, and a URL redirect from @ to www covers bare-domain visitors.
 
 Host fields above are the SHORT form: most DNS panels append the domain automatically. After saving, the record list must NOT show ${apex} twice in one name \u2014 that means the full name was pasted into an auto-appending field.
 
 Ownership comes ONLY from DNS control; paying never grants it. The first verified request wins and this challenge expires after 72 hours.
 
-Then run bind_domain with action "status" \u2014 it live-checks every record and names the exact fix for anything wrong. Re-check every 5 minutes (up to 10 times). Any later session can resume with action "status" alone; the verificationId is optional.`,
+STEP 2 (after ownership verifies): Cloudflare issues certificate-validation TXT records \u2014 the verification result and bind_domain "status" list them the moment they exist; relay each to the user and add them too. Everything then completes automatically.
+
+Drive the whole flow with bind_domain "status": it live-checks every record and names the exact fix for anything wrong. Re-check every 5 minutes (up to 10 times). Any later session can resume with action "status" alone; the verificationId is optional.`,
           {
             verificationId: res.verificationId,
             apexDomain: apex,
@@ -2435,9 +2468,10 @@ ${res.archiveUrl}`,
           ...args.contactEmail !== void 0 ? { contactEmail: args.contactEmail } : {}
         };
         if (args.confirmSubmit !== true) {
+          const contactNote = args.contactEmail !== void 0 ? "note that their contact email is attached for follow-up. " : "ASK THEM ONCE whether they want to attach a contact email for follow-up (optional \u2014 omit if declined; include it as contactEmail when they do). ";
           return textJson(
             "bug_report_preview_ready",
-            "Bug report prepared but NOT submitted. This is the exact payload that would be sent (structured diagnostics only \u2014 no file contents, source code or secrets). Please show it to the user; re-run report_bug with confirmSubmit: true to submit.",
+            `Bug report prepared but NOT submitted. This is the exact payload that would be sent (structured diagnostics only \u2014 no file contents, source code or secrets). Show it to the user, and ${contactNote}Then re-run report_bug with confirmSubmit: true to submit.`,
             payload,
             "preview"
           );
@@ -2704,13 +2738,18 @@ Workflow:
 
 Project directory contract: ONE directory = ONE site (its .sakupa/site.json holds the
 binding). Every project-scoped tool accepts projectDir \u2014 ALWAYS pass the absolute path of
-the directory the user is currently working in, on every call. Without it the server falls
-back to its startup directory, which may be a different project than the one the user is
-looking at. After every deploy, TELL the user which environment it went to (deploy results carry an
+the user's PROJECT ROOT, the SAME directory every time for the same project: the folder
+the user opened (for framework projects, where package.json lives \u2014 never the dist/out
+build folder; output is auto-detected). Without it the server falls back to its startup
+directory, which may be a different project than the one the user is looking at. After every deploy, TELL the user which environment it went to (deploy results carry an
 Explicit Environment line: TEST vs PRODUCTION). analyze_site, deploy_site, site_status,
 refresh_site, delete_site and unbind_domain echo
 the directory they acted on \u2014 verify it matches the user's active project.
 
+When the same operation fails twice in a row, or the user is clearly stuck or
+frustrated, proactively offer report_bug: it files the problem into Sakupa's ticket and
+alert stream, and you should attach your own factual account via agentContext.
+
 Safety boundaries:
 - Static output only: no SSR, API routes, middleware, server actions, databases or online builds.
 - Never upload source projects, secrets, .env files, private keys, archives, videos or audio.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sakupa/mcp",
-  "version": "0.7.10",
+  "version": "0.7.12",
   "description": "Sakupa MCP server: publish AI-made static sites from your AI tool. AI-made pages, live in seconds.",
   "type": "module",
   "main": "dist/index.js",