@sakupa/mcp 0.7.9 → 0.7.11

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.9";
+var SAKUPA_MCP_VERSION = "0.7.11";
 
 // ../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,10 +1358,30 @@ 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 };
 }
+var DNS_RETRY_AFTER_SECONDS = 300;
+var DNS_MAX_ATTEMPTS = 10;
+function toDnsChecklist(checks) {
+  return checks.map((c) => ({
+    name: c.record.name,
+    type: c.record.type,
+    shortHost: c.shortHost,
+    state: c.state,
+    ...c.fix ? { fix: c.fix } : {}
+  }));
+}
+function renderChecklistBlock(diag, fixTail) {
+  const cadence = `Re-check every ${DNS_RETRY_AFTER_SECONDS / 60} minutes, up to ${DNS_MAX_ATTEMPTS} times.`;
+  return `Live DNS checklist (host values are the SHORT panel form):
+${diag.checklist}
+
+${diag.layers}
+
+` + (diag.allOk ? "All records are live; certificate issuance completes automatically \u2014 re-check in a few minutes until the binding is active." : `${fixTail} ${cadence}`);
+}
 
 // src/version.ts
 var MCP_VERSION = SAKUPA_MCP_VERSION;
@@ -1417,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;
@@ -1609,8 +1633,52 @@ async function uploadAll(ctx, targets, files, outputAbs) {
   }
   return targets.length;
 }
-var DNS_RETRY_AFTER_SECONDS = 300;
-var DNS_MAX_ATTEMPTS = 10;
+async function describePendingBinding(client, credential, pb) {
+  const framing = `
+Domain binding IN PROGRESS: ${pb.apexDomain} \u2014 ` + (pb.phase === "provisioning" ? "ownership verified; certificates/serving are provisioning." : `awaiting DNS verification (challenge valid until ${pb.verificationExpiresAt}).`);
+  let check;
+  try {
+    check = await client.checkVerification(pb.verificationId, credential);
+  } catch {
+    return {
+      note: framing + "\n(Couldn't refresh binding progress from the server just now \u2014 try site_status again shortly.)"
+    };
+  }
+  try {
+    const diag = await diagnoseBinding({
+      apexDomain: check.apexDomain,
+      servingTarget: check.servingTarget,
+      ...check.verificationRecord ? { verificationRecord: check.verificationRecord } : {},
+      pendingDnsRecords: check.pendingDnsRecords,
+      verificationStatus: check.status,
+      provisioning: pb.phase === "provisioning"
+    });
+    const block = renderChecklistBlock(
+      diag,
+      "Relay every [MISSING]/[FIX] line to the user with its exact fix."
+    );
+    return { note: `${framing}
+${block}`, checklist: toDnsChecklist(diag.checks) };
+  } catch {
+    return {
+      note: framing + '\n(Live DNS lookups are unavailable right now \u2014 run bind_domain with action "status" for the per-record checklist.)'
+    };
+  }
+}
+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;
@@ -1671,6 +1739,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.")
       }
     },
@@ -1699,16 +1770,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) {
@@ -1871,9 +1960,11 @@ NO content was uploaded or changed by this call \u2014 to publish new or edited
         const ctx = withProjectDir(baseCtx, args.projectDir);
         const site = requireSiteFile(ctx);
         const res = await ctx.client.getSiteStatus(site.siteId, site.credential);
-        return textJson("site_status_returned", "Site status:", {
+        const binding = res.pendingDomainBinding ? await describePendingBinding(ctx.client, site.credential, res.pendingDomainBinding) : void 0;
+        return textJson("site_status_returned", `Site status:${binding?.note ?? ""}`, {
           ...res,
-          projectDir: ctx.projectDir
+          projectDir: ctx.projectDir,
+          ...binding?.checklist ? { dnsChecklist: binding.checklist } : {}
         });
       } catch (e) {
         return toolError(e);
@@ -1952,7 +2043,7 @@ Once payment confirms, the site becomes permanent on its current URL. Binding a
             writeSiteFile(ctx.projectDir, { ...site, boundDomain: res2.apexDomain });
           }
           const apex2 = res2.apexDomain;
-          const { checks, apexResolves, allOk, checklist, layers } = await diagnoseBinding({
+          const diag = await diagnoseBinding({
             apexDomain: apex2,
             servingTarget: res2.servingTarget,
             ...res2.verificationRecord ? { verificationRecord: res2.verificationRecord } : {},
@@ -1960,30 +2051,23 @@ Once payment confirms, the site becomes permanent on its current URL. Binding a
             verificationStatus: res2.status,
             provisioning: res2.provisioningJobId !== void 0
           });
+          const { apexResolves, allOk } = diag;
           return text(
             res2.status === "verified" ? "domain_verification_succeeded" : "domain_verification_pending",
             `Domain binding status for ${apex2}: ${res2.status}
 ${res2.message}
 
-Live DNS checklist (host values are the SHORT panel form):
-${checklist}
-
-${layers}
-
-` + (allOk && res2.status === "verified" ? "All records are live; certificate issuance completes automatically \u2014 check again in a few minutes until the binding is active." : "Fix any [MISSING]/[FIX] lines above, then re-run bind_domain status. Re-check every 5 minutes, up to 10 times; if still failing after that, show the user this checklist."),
+` + renderChecklistBlock(
+              diag,
+              "Fix any [MISSING]/[FIX] lines above, then re-run bind_domain status; if still failing after the attempts below, show the user this checklist."
+            ),
             {
               verificationId: res2.verificationId,
               status: res2.status,
               apexDomain: apex2,
               provisioningJobId: res2.provisioningJobId,
               servingTarget: res2.servingTarget,
-              dnsChecklist: checks.map((c) => ({
-                name: c.record.name,
-                type: c.record.type,
-                shortHost: c.shortHost,
-                state: c.state,
-                fix: c.fix || void 0
-              })),
+              dnsChecklist: toDnsChecklist(diag.checks),
               apexResolves,
               retryAfterSeconds: DNS_RETRY_AFTER_SECONDS,
               maxAttempts: DNS_MAX_ATTEMPTS,
@@ -2006,17 +2090,19 @@ ${layers}
           "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,
@@ -2291,6 +2377,12 @@ ${res.archiveUrl}`,
         deploymentId: z3.string().optional(),
         severity: severityEnum.optional(),
         description: z3.string().optional().describe("What happened, in the user's words (no secrets)."),
+        agentContext: z3.string().optional().describe(
+          "YOUR OWN factual account of the session as the AI: which tools you called, what they returned, expected vs actual. Write it yourself from your observations \u2014 never ask the user to compose it, and do not read it back to them; it travels alongside the user's description as a second witness. No secrets, no file contents."
+        ),
+        contactEmail: z3.string().optional().describe(
+          "OPTIONAL. Before submitting, ask the user ONCE whether they want to leave a contact for follow-up. Omit entirely if they decline \u2014 never require it."
+        ),
         confirmSubmit: z3.boolean().optional().describe("User reviewed the report payload and approved submission.")
       }
     },
@@ -2315,7 +2407,9 @@ ${res.archiveUrl}`,
           ...site ? { siteId: site.siteId } : {},
           ...args.severity !== void 0 ? { severity: args.severity } : {},
           diagnostics,
-          ...args.description !== void 0 ? { description: args.description } : {}
+          ...args.description !== void 0 ? { description: args.description } : {},
+          ...args.agentContext !== void 0 ? { agentContext: args.agentContext } : {},
+          ...args.contactEmail !== void 0 ? { contactEmail: args.contactEmail } : {}
         };
         if (args.confirmSubmit !== true) {
           return textJson(
@@ -2656,13 +2750,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.9";
+var SAKUPA_MCP_VERSION = "0.7.11";
 
 // ../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;
@@ -1414,7 +1418,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,10 +1566,30 @@ 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 };
 }
+var DNS_RETRY_AFTER_SECONDS = 300;
+var DNS_MAX_ATTEMPTS = 10;
+function toDnsChecklist(checks) {
+  return checks.map((c) => ({
+    name: c.record.name,
+    type: c.record.type,
+    shortHost: c.shortHost,
+    state: c.state,
+    ...c.fix ? { fix: c.fix } : {}
+  }));
+}
+function renderChecklistBlock(diag, fixTail) {
+  const cadence = `Re-check every ${DNS_RETRY_AFTER_SECONDS / 60} minutes, up to ${DNS_MAX_ATTEMPTS} times.`;
+  return `Live DNS checklist (host values are the SHORT panel form):
+${diag.checklist}
+
+${diag.layers}
+
+` + (diag.allOk ? "All records are live; certificate issuance completes automatically \u2014 re-check in a few minutes until the binding is active." : `${fixTail} ${cadence}`);
+}
 
 // src/tools/definitions.ts
 function text(resultCode, t, data = {}, outcome = "completed") {
@@ -1673,8 +1697,52 @@ async function uploadAll(ctx, targets, files, outputAbs) {
   }
   return targets.length;
 }
-var DNS_RETRY_AFTER_SECONDS = 300;
-var DNS_MAX_ATTEMPTS = 10;
+async function describePendingBinding(client, credential, pb) {
+  const framing = `
+Domain binding IN PROGRESS: ${pb.apexDomain} \u2014 ` + (pb.phase === "provisioning" ? "ownership verified; certificates/serving are provisioning." : `awaiting DNS verification (challenge valid until ${pb.verificationExpiresAt}).`);
+  let check;
+  try {
+    check = await client.checkVerification(pb.verificationId, credential);
+  } catch {
+    return {
+      note: framing + "\n(Couldn't refresh binding progress from the server just now \u2014 try site_status again shortly.)"
+    };
+  }
+  try {
+    const diag = await diagnoseBinding({
+      apexDomain: check.apexDomain,
+      servingTarget: check.servingTarget,
+      ...check.verificationRecord ? { verificationRecord: check.verificationRecord } : {},
+      pendingDnsRecords: check.pendingDnsRecords,
+      verificationStatus: check.status,
+      provisioning: pb.phase === "provisioning"
+    });
+    const block = renderChecklistBlock(
+      diag,
+      "Relay every [MISSING]/[FIX] line to the user with its exact fix."
+    );
+    return { note: `${framing}
+${block}`, checklist: toDnsChecklist(diag.checks) };
+  } catch {
+    return {
+      note: framing + '\n(Live DNS lookups are unavailable right now \u2014 run bind_domain with action "status" for the per-record checklist.)'
+    };
+  }
+}
+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;
@@ -1735,6 +1803,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.")
       }
     },
@@ -1763,16 +1834,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) {
@@ -1935,9 +2024,11 @@ NO content was uploaded or changed by this call \u2014 to publish new or edited
         const ctx = withProjectDir(baseCtx, args.projectDir);
         const site = requireSiteFile(ctx);
         const res = await ctx.client.getSiteStatus(site.siteId, site.credential);
-        return textJson("site_status_returned", "Site status:", {
+        const binding = res.pendingDomainBinding ? await describePendingBinding(ctx.client, site.credential, res.pendingDomainBinding) : void 0;
+        return textJson("site_status_returned", `Site status:${binding?.note ?? ""}`, {
           ...res,
-          projectDir: ctx.projectDir
+          projectDir: ctx.projectDir,
+          ...binding?.checklist ? { dnsChecklist: binding.checklist } : {}
         });
       } catch (e) {
         return toolError(e);
@@ -2016,7 +2107,7 @@ Once payment confirms, the site becomes permanent on its current URL. Binding a
             writeSiteFile(ctx.projectDir, { ...site, boundDomain: res2.apexDomain });
           }
           const apex2 = res2.apexDomain;
-          const { checks, apexResolves, allOk, checklist, layers } = await diagnoseBinding({
+          const diag = await diagnoseBinding({
             apexDomain: apex2,
             servingTarget: res2.servingTarget,
             ...res2.verificationRecord ? { verificationRecord: res2.verificationRecord } : {},
@@ -2024,30 +2115,23 @@ Once payment confirms, the site becomes permanent on its current URL. Binding a
             verificationStatus: res2.status,
             provisioning: res2.provisioningJobId !== void 0
           });
+          const { apexResolves, allOk } = diag;
           return text(
             res2.status === "verified" ? "domain_verification_succeeded" : "domain_verification_pending",
             `Domain binding status for ${apex2}: ${res2.status}
 ${res2.message}
 
-Live DNS checklist (host values are the SHORT panel form):
-${checklist}
-
-${layers}
-
-` + (allOk && res2.status === "verified" ? "All records are live; certificate issuance completes automatically \u2014 check again in a few minutes until the binding is active." : "Fix any [MISSING]/[FIX] lines above, then re-run bind_domain status. Re-check every 5 minutes, up to 10 times; if still failing after that, show the user this checklist."),
+` + renderChecklistBlock(
+              diag,
+              "Fix any [MISSING]/[FIX] lines above, then re-run bind_domain status; if still failing after the attempts below, show the user this checklist."
+            ),
             {
               verificationId: res2.verificationId,
               status: res2.status,
               apexDomain: apex2,
               provisioningJobId: res2.provisioningJobId,
               servingTarget: res2.servingTarget,
-              dnsChecklist: checks.map((c) => ({
-                name: c.record.name,
-                type: c.record.type,
-                shortHost: c.shortHost,
-                state: c.state,
-                fix: c.fix || void 0
-              })),
+              dnsChecklist: toDnsChecklist(diag.checks),
               apexResolves,
               retryAfterSeconds: DNS_RETRY_AFTER_SECONDS,
               maxAttempts: DNS_MAX_ATTEMPTS,
@@ -2070,17 +2154,19 @@ ${layers}
           "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,
@@ -2355,6 +2441,12 @@ ${res.archiveUrl}`,
         deploymentId: z3.string().optional(),
         severity: severityEnum.optional(),
         description: z3.string().optional().describe("What happened, in the user's words (no secrets)."),
+        agentContext: z3.string().optional().describe(
+          "YOUR OWN factual account of the session as the AI: which tools you called, what they returned, expected vs actual. Write it yourself from your observations \u2014 never ask the user to compose it, and do not read it back to them; it travels alongside the user's description as a second witness. No secrets, no file contents."
+        ),
+        contactEmail: z3.string().optional().describe(
+          "OPTIONAL. Before submitting, ask the user ONCE whether they want to leave a contact for follow-up. Omit entirely if they decline \u2014 never require it."
+        ),
         confirmSubmit: z3.boolean().optional().describe("User reviewed the report payload and approved submission.")
       }
     },
@@ -2379,7 +2471,9 @@ ${res.archiveUrl}`,
           ...site ? { siteId: site.siteId } : {},
           ...args.severity !== void 0 ? { severity: args.severity } : {},
           diagnostics,
-          ...args.description !== void 0 ? { description: args.description } : {}
+          ...args.description !== void 0 ? { description: args.description } : {},
+          ...args.agentContext !== void 0 ? { agentContext: args.agentContext } : {},
+          ...args.contactEmail !== void 0 ? { contactEmail: args.contactEmail } : {}
         };
         if (args.confirmSubmit !== true) {
           return textJson(
@@ -2651,13 +2745,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.9",
+  "version": "0.7.11",
   "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",