@sakupa/mcp 0.7.35 → 0.7.37

package/dist/bin.js

@@ -14,6 +14,7 @@ import {
   readFileSync,
   realpathSync,
   renameSync,
+  rmdirSync,
   statSync,
   unlinkSync,
   writeFileSync
@@ -151,6 +152,14 @@ function updateProjectOutputDir(projectDir, outputDir) {
   writeMarkerAtomically(canonical, marker);
   return marker;
 }
+function deleteProjectMarker(projectDir) {
+  const path = projectMarkerPath(projectDir);
+  if (existsSync(path)) unlinkSync(path);
+  try {
+    rmdirSync(join(projectDir, SAKUPA_DIR));
+  } catch {
+  }
+}
 function canonicalProjectDirectory(path) {
   const canonical = canonicalExistingPath(resolve(path));
   if (!statSync(canonical).isDirectory()) {
@@ -370,7 +379,7 @@ var FORBIDDEN_PATH_SEGMENTS = [
 var ALLOWED_HIDDEN_PATHS = [".well-known/"];
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "0.7.35";
+var SAKUPA_MCP_VERSION = "0.7.37";
 
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
@@ -929,9 +938,9 @@ var HttpApiClient = class {
 };
 
 // src/tools/definitions.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 import { promises as fs2 } from "node:fs";
-import { join as join6, resolve as resolve4 } from "node:path";
+import { join as join6, relative as relative3, resolve as resolve5, sep as sep4 } from "node:path";
 import { z as z2 } from "zod";
 
 // src/analyze/analyzer.ts
@@ -1369,7 +1378,7 @@ import {
   existsSync as existsSync2,
   mkdirSync as mkdirSync2,
   readFileSync as readFileSync2,
-  rmdirSync,
+  rmdirSync as rmdirSync2,
   rmSync,
   writeFileSync as writeFileSync2
 } from "node:fs";
@@ -1496,7 +1505,7 @@ function deleteSiteFile(projectDir) {
     rmSync(path, { force: true });
   }
   try {
-    rmdirSync(join3(projectDir, SITE_DIR));
+    rmdirSync2(join3(projectDir, SITE_DIR));
   } catch {
   }
 }
@@ -1940,15 +1949,15 @@ function strFromU8(dat, latin1) {
 var slzh = function(d, b) {
   return b + 30 + b2(d, b + 26) + b2(d, b + 28);
 };
-var zh = function(d, b, z5) {
+var zh = function(d, b, z6) {
   var fnl = b2(d, b + 28), efl = b2(d, b + 30), fn = strFromU8(d.subarray(b + 46, b + 46 + fnl), !(b2(d, b + 8) & 2048)), es = b + 46 + fnl;
-  var _a2 = z64hs(d, es, efl, z5, b4(d, b + 20), b4(d, b + 24), b4(d, b + 42)), sc = _a2[0], su = _a2[1], off = _a2[2];
+  var _a2 = z64hs(d, es, efl, z6, b4(d, b + 20), b4(d, b + 24), b4(d, b + 42)), sc = _a2[0], su = _a2[1], off = _a2[2];
   return [b2(d, b + 10), sc, su, fn, es + efl + b2(d, b + 32), off];
 };
-var z64hs = function(d, b, l, z5, sc, su, off) {
+var z64hs = function(d, b, l, z6, sc, su, off) {
   var nsc = sc == 4294967295, nsu = su == 4294967295, noff = off == 4294967295, e = b + l;
   var nf = nsc + nsu + noff;
-  if (z5 && nf) {
+  if (z6 && nf) {
     for (; b + 4 < e; b += 4 + b2(d, b + 2)) {
       if (b2(d, b) == 1) {
         return [
@@ -1959,7 +1968,7 @@ var z64hs = function(d, b, l, z5, sc, su, off) {
         ];
       }
     }
-    if (z5 < 2)
+    if (z6 < 2)
       err(13);
   }
   return [sc, su, off, 0];
@@ -1976,18 +1985,18 @@ function unzipSync(data, opts) {
   if (!c)
     return {};
   var o = b4(data, e + 16);
-  var z5 = b4(data, e - 20) == 117853008;
-  if (z5) {
+  var z6 = b4(data, e - 20) == 117853008;
+  if (z6) {
     var ze = b4(data, e - 12);
-    z5 = b4(data, ze) == 101075792;
-    if (z5) {
+    z6 = b4(data, ze) == 101075792;
+    if (z6) {
       c = b4(data, ze + 32);
       o = b4(data, ze + 48);
     }
   }
   var fltr = opts && opts.filter;
   for (var i = 0; i < c; ++i) {
-    var _a2 = zh(data, o, z5), c_2 = _a2[0], sc = _a2[1], su = _a2[2], fn = _a2[3], no = _a2[4], off = _a2[5], b = slzh(data, off);
+    var _a2 = zh(data, o, z6), c_2 = _a2[0], sc = _a2[1], su = _a2[2], fn = _a2[3], no = _a2[4], off = _a2[5], b = slzh(data, off);
     o = no;
     if (!fltr || fltr({
       name: fn,
@@ -2344,6 +2353,259 @@ ${diag.layers}
 var MCP_VERSION = SAKUPA_MCP_VERSION;
 var CLIENT_TYPE = "sakupa-mcp";
 
+// src/project-binding.ts
+import { fileURLToPath } from "node:url";
+import { resolve as resolve4 } from "node:path";
+var ProjectBindingError = class extends Error {
+  diagnostics;
+  constructor(diagnostics) {
+    super(diagnostics.guidance);
+    this.name = "ProjectBindingError";
+    this.diagnostics = diagnostics;
+  }
+};
+var ProjectBindingResolver = class {
+  constructor(processCwd, rootsProvider) {
+    this.processCwd = processCwd;
+    this.rootsProvider = rootsProvider;
+  }
+  bound;
+  boundState;
+  resolving;
+  async resolve() {
+    if (this.bound) return this.bound;
+    if (this.resolving) return this.resolving;
+    this.resolving = this.inspect().then((inspection) => {
+      if (!inspection.selected) throw new ProjectBindingError(inspection.diagnostics);
+      this.bound = inspection.selected;
+      this.boundState = inspection.diagnostics;
+      return inspection.selected;
+    }).finally(() => {
+      this.resolving = void 0;
+    });
+    return this.resolving;
+  }
+  async diagnose() {
+    if (this.bound) return this.boundState ?? boundDiagnostics(this.processCwd, this.bound);
+    const inspection = await this.inspect();
+    if (inspection.selected) {
+      this.bound = inspection.selected;
+      this.boundState = inspection.diagnostics;
+    }
+    return inspection.diagnostics;
+  }
+  async initialize() {
+    if (this.bound) return this.bound;
+    const inspection = await this.inspect(true);
+    if (inspection.selected) {
+      this.bound = inspection.selected;
+      this.boundState = inspection.diagnostics;
+      return inspection.selected;
+    }
+    if (!inspection.initializableRoot) {
+      throw new ProjectBindingError(inspection.diagnostics);
+    }
+    const initialized = initializeProject(inspection.initializableRoot);
+    this.bound = { ...initialized, bindingSource: "mcp_root" };
+    this.boundState = boundDiagnostics(
+      this.processCwd,
+      this.bound,
+      { supported: true, roots: [] },
+      inspection.diagnostics.rootCandidates
+    );
+    return this.bound;
+  }
+  async inspect(forInitialization = false) {
+    const snapshot = await safeRootsSnapshot(this.rootsProvider);
+    const rootCandidates = snapshot.roots.map(inspectRoot);
+    const initializedRoots = rootCandidates.filter(
+      (candidate) => candidate.initialized && candidate.path !== void 0
+    );
+    if (snapshot.supported && snapshot.error) {
+      return {
+        diagnostics: diagnostic(
+          "roots_request_failed",
+          snapshot,
+          this.processCwd,
+          rootCandidates,
+          "The IDE advertised MCP Roots, but the Roots request failed. Retry help after the IDE finishes loading the workspace. If it persists, restart the MCP connection; do not initialize or deploy from the IDE installation directory."
+        )
+      };
+    }
+    if (initializedRoots.length === 1) {
+      const initializedRoot = initializedRoots[0];
+      if (!initializedRoot) throw new Error("initialized Root disappeared during resolution");
+      const project = resolveLockedProjectRoot(initializedRoot.path);
+      const selected = { ...project, bindingSource: "mcp_root" };
+      return {
+        selected,
+        diagnostics: boundDiagnostics(this.processCwd, selected, snapshot, rootCandidates)
+      };
+    }
+    if (initializedRoots.length > 1) {
+      return {
+        diagnostics: diagnostic(
+          "multiple_initialized_roots",
+          snapshot,
+          this.processCwd,
+          rootCandidates,
+          "More than one IDE workspace Root is already initialized for Sakupa. Close the unrelated workspaces and retry help; Sakupa will not guess which site to manage."
+        )
+      };
+    }
+    const validRoots = rootCandidates.filter(
+      (candidate) => candidate.path !== void 0 && candidate.problem === void 0
+    );
+    if (forInitialization && snapshot.supported) {
+      if (validRoots.length === 1) {
+        const validRoot = validRoots[0];
+        if (!validRoot) throw new Error("workspace Root disappeared during initialization");
+        return {
+          initializableRoot: validRoot.path,
+          diagnostics: diagnostic(
+            "workspace_not_initialized",
+            snapshot,
+            this.processCwd,
+            rootCandidates,
+            `The active MCP workspace ${validRoot.path} is ready to initialize.`
+          )
+        };
+      }
+      if (validRoots.length > 1) {
+        return {
+          diagnostics: diagnostic(
+            "multiple_uninitialized_roots",
+            snapshot,
+            this.processCwd,
+            rootCandidates,
+            "The IDE exposes multiple uninitialized workspace Roots. Open only the intended project before calling init; Sakupa will not choose a directory for the user."
+          )
+        };
+      }
+    }
+    if (snapshot.supported && validRoots.length === 1) {
+      const validRoot = validRoots[0];
+      if (!validRoot) throw new Error("workspace Root disappeared during diagnosis");
+      return {
+        diagnostics: diagnostic(
+          "workspace_not_initialized",
+          snapshot,
+          this.processCwd,
+          rootCandidates,
+          `The IDE workspace ${validRoot.path} is not initialized. Call init with no path arguments; it will create .sakupa directly in that workspace Root.`
+        )
+      };
+    }
+    if (snapshot.supported && validRoots.length > 1) {
+      return {
+        diagnostics: diagnostic(
+          "multiple_uninitialized_roots",
+          snapshot,
+          this.processCwd,
+          rootCandidates,
+          "The IDE exposes multiple uninitialized workspace Roots. Open only the intended project, then call init. Sakupa will not guess a project directory."
+        )
+      };
+    }
+    if (snapshot.supported) {
+      return {
+        diagnostics: diagnostic(
+          "workspace_not_initialized",
+          snapshot,
+          this.processCwd,
+          rootCandidates,
+          "The IDE did not expose one usable file workspace Root. Open exactly one local project workspace, then retry help before calling init or deploy."
+        )
+      };
+    }
+    try {
+      const cwdProject = resolveLockedProjectRoot(this.processCwd);
+      const selected = { ...cwdProject, bindingSource: "process_cwd" };
+      return {
+        selected,
+        diagnostics: boundDiagnostics(this.processCwd, selected, snapshot, rootCandidates)
+      };
+    } catch {
+    }
+    const cwdProblem = inspectDirectory(this.processCwd);
+    return {
+      diagnostics: diagnostic(
+        cwdProblem.problem ? "invalid_process_cwd" : "process_cwd_is_not_workspace",
+        snapshot,
+        this.processCwd,
+        rootCandidates,
+        "This IDE did not provide MCP Roots and the MCP process cwd is not an initialized project. Do not write into the IDE installation directory. Run `npx -y @sakupa/mcp@latest init` with no path arguments from the intended project terminal, then configure/restart the MCP process in that directory."
+      )
+    };
+  }
+};
+function fileRootUriToPath(uri, windows = process.platform === "win32") {
+  const parsed = new URL(uri);
+  if (parsed.protocol !== "file:") throw new Error("Root URI is not a file URI");
+  return fileURLToPath(parsed, { windows });
+}
+async function safeRootsSnapshot(provider) {
+  if (!provider) return { supported: false, roots: [] };
+  try {
+    return await provider();
+  } catch (error) {
+    return {
+      supported: true,
+      roots: [],
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function inspectRoot(root) {
+  try {
+    const path = canonicalProjectDirectory(fileRootUriToPath(root.uri));
+    const marker = loadProjectMarker(path);
+    return {
+      uri: root.uri,
+      ...root.name !== void 0 ? { name: root.name } : {},
+      path,
+      initialized: marker.kind === "ok",
+      ...marker.kind === "corrupted" ? { problem: marker.problem } : {}
+    };
+  } catch (error) {
+    return {
+      uri: root.uri,
+      ...root.name !== void 0 ? { name: root.name } : {},
+      initialized: false,
+      problem: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function inspectDirectory(path) {
+  try {
+    return { path: canonicalProjectDirectory(resolve4(path)) };
+  } catch (error) {
+    return { problem: error instanceof Error ? error.message : String(error) };
+  }
+}
+function diagnostic(diagnosisCode, snapshot, processCwd, rootCandidates, guidance) {
+  return {
+    diagnosisCode,
+    mcpRootsSupported: snapshot.supported,
+    processCwd,
+    rootCandidates,
+    guidance,
+    reportRecommended: false
+  };
+}
+function boundDiagnostics(processCwd, selected, snapshot = { supported: false, roots: [] }, rootCandidates = []) {
+  return {
+    diagnosisCode: "project_bound",
+    mcpRootsSupported: snapshot.supported,
+    processCwd,
+    rootCandidates,
+    selectedProjectDir: selected.projectDir,
+    bindingSource: selected.bindingSource,
+    guidance: `Sakupa is locked to ${selected.projectDir} from ${selected.bindingSource}.`,
+    reportRecommended: false
+  };
+}
+
 // src/tools/result.ts
 import { z } from "zod";
 var STRUCTURED_TOOL_OUTPUT_SCHEMA = {
@@ -2386,22 +2648,39 @@ function structuredToolResult(envelope) {
 }
 
 // src/tools/context.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
 var LocalGuidanceError = class extends SakupaError {
   constructor(code, message) {
     super(code, message);
   }
 };
-function withProjectDir(ctx) {
+var fallbackResolvers = /* @__PURE__ */ new WeakMap();
+var reportAuthorizations = /* @__PURE__ */ new WeakMap();
+function resolverFor(ctx) {
+  if (ctx.projectBinding) return ctx.projectBinding;
+  let resolver = fallbackResolvers.get(ctx);
+  if (!resolver) {
+    resolver = new ProjectBindingResolver(ctx.projectDir, ctx.rootsProvider);
+    fallbackResolvers.set(ctx, resolver);
+  }
+  return resolver;
+}
+async function withProjectDir(ctx) {
   try {
-    const resolved = resolveLockedProjectRoot(ctx.projectDir);
+    const binding = await resolverFor(ctx).resolve();
+    const resolved = resolveLockedProjectRoot(binding.projectDir);
     return {
       ...ctx,
       projectDir: resolved.projectDir,
       requestedPath: resolved.requestedPath,
       markerKind: resolved.markerKind,
-      projectMarker: resolved.marker
+      projectMarker: resolved.marker,
+      bindingSource: binding.bindingSource
     };
   } catch (error) {
+    if (error instanceof ProjectBindingError) {
+      throw new LocalGuidanceError("not_found", error.message);
+    }
     if (error instanceof ProjectRootError) {
       throw new LocalGuidanceError(
         error.code === "not_initialized" ? "not_found" : "invalid_request",
@@ -2411,6 +2690,60 @@ function withProjectDir(ctx) {
     throw error;
   }
 }
+async function diagnoseProjectBinding(ctx) {
+  return resolverFor(ctx).diagnose();
+}
+async function initializeWorkspaceProject(ctx) {
+  try {
+    const resolved = await resolverFor(ctx).initialize();
+    return {
+      ...ctx,
+      projectDir: resolved.projectDir,
+      requestedPath: resolved.requestedPath,
+      markerKind: resolved.markerKind,
+      projectMarker: resolved.marker,
+      bindingSource: resolved.bindingSource
+    };
+  } catch (error) {
+    if (error instanceof ProjectBindingError) {
+      throw new LocalGuidanceError("invalid_request", error.message);
+    }
+    throw error;
+  }
+}
+async function optionalProjectContext(ctx) {
+  try {
+    return await withProjectDir(ctx);
+  } catch {
+    return null;
+  }
+}
+function reportAuthorizationStore(ctx) {
+  let store = reportAuthorizations.get(ctx);
+  if (!store) {
+    store = /* @__PURE__ */ new Map();
+    reportAuthorizations.set(ctx, store);
+  }
+  return store;
+}
+function issueReportAuthorization(ctx, failedTool) {
+  const token = randomUUID2();
+  reportAuthorizationStore(ctx).set(token, {
+    failedTool,
+    expiresAt: Date.now() + 10 * 60 * 1e3
+  });
+  return token;
+}
+function requireReportAuthorization(ctx, token, failedTool) {
+  const authorization = token ? reportAuthorizationStore(ctx).get(token) : void 0;
+  if (!authorization || authorization.expiresAt < Date.now() || authorization.failedTool !== failedTool) {
+    if (token) reportAuthorizationStore(ctx).delete(token);
+    throw new LocalGuidanceError(
+      "invalid_request",
+      'report is the last resort. Run help with topic:"diagnose", failedTool and the error code first. Only when help returns reportRecommended:true, copy its helpAuthorization into report.'
+    );
+  }
+}
 function requireSiteFile(ctx) {
   const state = loadSiteFile(ctx.projectDir);
   if (state.kind === "corrupted") {
@@ -2449,7 +2782,7 @@ function toolError(e) {
   ) : void 0;
   const minimumVersion = rawDetails && typeof rawDetails["minimumVersion"] === "string" ? rawDetails["minimumVersion"] : void 0;
   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." : opaqueUnclassified ? "This failed with an error Sakupa could not classify, and retrying will not help. Tell the user briefly, then offer to file it: run the report tool to send Sakupa a diagnostic report of what was being attempted so we can investigate." : "The operation failed; no server-internal details are exposed.");
+  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." : opaqueUnclassified ? "This failed with an error Sakupa could not classify, and retrying the same call will not help. Run help with the failed tool and error code first; only use report if help explicitly recommends it." : "The operation failed; no server-internal details are exposed.");
   const result = structuredToolResult({
     schemaVersion: 1,
     outcome: "failed",
@@ -2460,7 +2793,14 @@ function toolError(e) {
       retryable,
       ...safeDetails && Object.keys(safeDetails).length > 0 ? { details: safeDetails } : {}
     },
-    nextActions: []
+    nextActions: [
+      {
+        tool: "help",
+        arguments: { topic: "diagnose", failedTool: "unknown", errorCode },
+        allowed: true,
+        reasonCode: "diagnose_before_report"
+      }
+    ]
   });
   return { ...result, isError: true };
 }
@@ -2620,6 +2960,27 @@ If this list is stale (sites deleted or subscribed from another machine), remove
     "blocked"
   );
 }
+function outputDirectoryChain(projectRoot, outputAbs) {
+  const rel = relative3(projectRoot, outputAbs);
+  if (rel === "" || rel === ".") return [];
+  if (rel === ".." || rel.startsWith(`..${sep4}`)) return [];
+  const chain = [];
+  let cursor = projectRoot;
+  for (const part of rel.split(sep4).filter(Boolean)) {
+    cursor = join6(cursor, part);
+    chain.push(cursor);
+  }
+  return chain;
+}
+async function sakupaDirectoryEntries(projectDir) {
+  try {
+    return await fs2.readdir(join6(projectDir, ".sakupa"));
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT") return [];
+    throw error;
+  }
+}
 function registerTools(server, baseCtx) {
   const previewHostPattern = previewHostPatternFor(baseCtx.apiBaseUrl);
   server.registerTool(
@@ -2634,7 +2995,7 @@ function registerTools(server, baseCtx) {
     },
     async (args) => {
       try {
-        const ctx = withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx);
         const analysis = await analyzeProject(ctx.projectDir, {
           ...args.outputDir !== void 0 ? { outputDir: args.outputDir } : {}
         });
@@ -2662,6 +3023,9 @@ Next action: ${analysis.suggestedNextAction}`,
         outputDirChangeConfirmed: z2.boolean().optional().describe(
           "Required only when changing the previously successful publish directory. Confirm only after showing the old and new directories to the user."
         ),
+        sakupaRelocationConfirmed: z2.boolean().optional().describe(
+          "Required only when a nested directory is itself initialized with .sakupa/project.json. Confirm only after showing the source and authoritative project Root; Sakupa then migrates non-conflicting state without exposing credentials."
+        ),
         spaFallback: z2.boolean().optional().describe(
           "Override automatic SPA-fallback detection (single index.html + JS auto-enables rewriting unknown paths to index.html; multiple HTML pages auto-disable it). Pass only to force the behavior against the detected structure."
         ),
@@ -2676,14 +3040,14 @@ Next action: ${analysis.suggestedNextAction}`,
     },
     async (args) => {
       try {
-        const ctx = withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx);
         const analysis = await analyzeProject(ctx.projectDir, { outputDir: args.outputDir });
         if (!analysis.deployable || !analysis.files) {
           return notDeployableResult(analysis);
         }
         const effectiveOutputDir = analysis.recommendedOutputDir ?? ".";
         const recordedOutputDir = ctx.projectMarker?.outputDir;
-        if (recordedOutputDir !== void 0 && resolve4(ctx.projectDir, recordedOutputDir) !== resolve4(ctx.projectDir, effectiveOutputDir) && args.outputDirChangeConfirmed !== true) {
+        if (recordedOutputDir !== void 0 && resolve5(ctx.projectDir, recordedOutputDir) !== resolve5(ctx.projectDir, effectiveOutputDir) && args.outputDirChangeConfirmed !== true) {
           return structuredToolResult({
             schemaVersion: 1,
             outcome: "waiting_user",
@@ -2699,7 +3063,7 @@ Next action: ${analysis.suggestedNextAction}`,
           });
         }
         const files = analysis.files;
-        const outputAbs = resolve4(ctx.projectDir, effectiveOutputDir);
+        const outputAbs = resolve5(ctx.projectDir, effectiveOutputDir);
         const manifest = await buildHashedManifest(files, outputAbs);
         const siteFileState = loadSiteFile(ctx.projectDir);
         if (siteFileState.kind === "corrupted") {
@@ -2713,30 +3077,157 @@ Next action: ${analysis.suggestedNextAction}`,
           );
         }
         let existing = siteFileState.kind === "ok" ? siteFileState.file : null;
-        let credentialRelocatedFrom = null;
-        if (!existing && effectiveOutputDir !== ".") {
-          const outputProjectMarker = loadProjectMarker(outputAbs);
-          if (outputProjectMarker.kind !== "absent") {
+        const credentialRelocatedFrom = [];
+        const markerRelocatedFrom = [];
+        const nestedSiteFiles = [];
+        const nestedRecoveryFiles = [];
+        for (const candidateDir of outputDirectoryChain(ctx.projectDir, outputAbs)) {
+          const entries = await sakupaDirectoryEntries(candidateDir);
+          if (entries.length === 0) continue;
+          const unknownEntries = entries.filter(
+            (entry) => !["project.json", "site.json", "recovery.json"].includes(entry)
+          );
+          if (unknownEntries.length > 0) {
             return text(
-              "publish_directory_is_independent_project",
-              outputProjectMarker.kind === "corrupted" ? `The selected publish directory ${outputAbs} contains a damaged Sakupa project marker: ${outputProjectMarker.problem}. Nothing was deployed.` : `The selected publish directory ${outputAbs} is itself an explicitly initialized Sakupa project. Refusing to move or reuse its credential from ${ctx.projectDir}. Run deploy from that independent project instead, or choose a publish directory that is not another Sakupa project.`,
-              { projectRoot: ctx.projectDir, outputDir: effectiveOutputDir },
+              "nested_sakupa_contains_unknown_files",
+              `A nested .sakupa directory at ${candidateDir} contains unknown files ${JSON.stringify(unknownEntries)}. Nothing was moved or deployed. Run help; Sakupa will never delete unrecognized user files.`,
+              { projectRoot: ctx.projectDir, nestedDirectory: candidateDir, unknownEntries },
               "blocked"
             );
           }
-          const outputSiteState = loadSiteFile(outputAbs);
-          if (outputSiteState.kind === "corrupted") {
+          const nestedMarker = loadProjectMarker(candidateDir);
+          if (nestedMarker.kind === "corrupted") {
             return text(
-              "output_site_file_corrupted",
-              `A misplaced .sakupa/site.json exists in output directory ${outputAbs}, but it is damaged: ${outputSiteState.problem}. Repair that file before retrying with the MCP still opened at ${ctx.projectDir}. Nothing was deployed and no site was created.`,
-              { projectRoot: ctx.projectDir, outputDir: analysis.recommendedOutputDir },
+              "nested_project_marker_corrupted",
+              `The nested .sakupa/project.json at ${candidateDir} is damaged: ${nestedMarker.problem}. Nothing was moved or deployed.`,
+              { projectRoot: ctx.projectDir, nestedDirectory: candidateDir },
               "blocked"
             );
           }
-          if (outputSiteState.kind === "ok") {
-            existing = outputSiteState.file;
-            credentialRelocatedFrom = outputAbs;
+          if (nestedMarker.kind === "ok") {
+            if (args.sakupaRelocationConfirmed !== true) {
+              return structuredToolResult({
+                schemaVersion: 1,
+                outcome: "waiting_user",
+                resultCode: "sakupa_relocation_confirmation_required",
+                summary: `A nested Sakupa project marker exists at ${candidateDir}/.sakupa, but the active MCP Root is ${ctx.projectDir}. Nothing was moved or deployed. Show both paths to the user; after confirmation retry deploy with sakupaRelocationConfirmed:true. Sakupa will preserve credentials and refuse conflicts.`,
+                data: {
+                  projectRoot: ctx.projectDir,
+                  misplacedSakupaDirectory: join6(candidateDir, ".sakupa"),
+                  targetSakupaDirectory: join6(ctx.projectDir, ".sakupa"),
+                  confirmationField: "sakupaRelocationConfirmed"
+                },
+                nextActions: [
+                  {
+                    tool: "deploy",
+                    allowed: true,
+                    reasonCode: "explicit_sakupa_relocation_confirmation"
+                  }
+                ]
+              });
+            }
+            markerRelocatedFrom.push(candidateDir);
+          }
+          const nestedSite = loadSiteFile(candidateDir);
+          if (nestedSite.kind === "corrupted") {
+            return text(
+              "output_site_file_corrupted",
+              `A misplaced .sakupa/site.json exists at ${candidateDir}, but it is damaged: ${nestedSite.problem}. Nothing was moved or deployed.`,
+              { projectRoot: ctx.projectDir, nestedDirectory: candidateDir },
+              "blocked"
+            );
           }
+          if (nestedSite.kind === "ok")
+            nestedSiteFiles.push({ dir: candidateDir, file: nestedSite.file });
+          const nestedRecovery = loadRecoveryFile(candidateDir);
+          if (nestedRecovery) nestedRecoveryFiles.push({ dir: candidateDir, file: nestedRecovery });
+        }
+        const allSiteFiles = [
+          ...existing ? [{ dir: ctx.projectDir, file: existing }] : [],
+          ...nestedSiteFiles
+        ];
+        const uniqueSiteBindings = new Set(
+          allSiteFiles.map(({ file }) => `${file.siteId}\0${file.credential}`)
+        );
+        if (uniqueSiteBindings.size > 1) {
+          return text(
+            "sakupa_relocation_conflict",
+            "The project Root and nested publish path contain different Sakupa site bindings. Nothing was moved or deployed; run help. Sakupa will never overwrite one site credential with another.",
+            {
+              projectRoot: ctx.projectDir,
+              conflictingDirectories: allSiteFiles.map(({ dir }) => dir)
+            },
+            "blocked"
+          );
+        }
+        if (!existing && nestedSiteFiles[0]) existing = nestedSiteFiles[0].file;
+        credentialRelocatedFrom.push(...nestedSiteFiles.map(({ dir }) => dir));
+        const rootRecovery = loadRecoveryFile(ctx.projectDir);
+        const allRecoveries = [
+          ...rootRecovery ? [{ dir: ctx.projectDir, file: rootRecovery }] : [],
+          ...nestedRecoveryFiles
+        ];
+        const uniqueRecoveries = new Set(
+          allRecoveries.map(({ file }) => `${file.verificationId}\0${file.credential}`)
+        );
+        if (uniqueRecoveries.size > 1) {
+          return text(
+            "recovery_relocation_conflict",
+            "The project Root and nested publish path contain different recovery credentials. Nothing was moved or deployed; run help. Sakupa will not restart DNS recovery.",
+            {
+              projectRoot: ctx.projectDir,
+              conflictingDirectories: allRecoveries.map(({ dir }) => dir)
+            },
+            "blocked"
+          );
+        }
+        const localCredentials = /* @__PURE__ */ new Set([
+          ...allSiteFiles.map(({ file }) => file.credential),
+          ...allRecoveries.map(({ file }) => file.credential)
+        ]);
+        if (allSiteFiles.length > 0 && allRecoveries.length > 0 && localCredentials.size > 1) {
+          return text(
+            "site_recovery_relocation_conflict",
+            "The project Root and nested publish path contain site and recovery credentials that do not belong to the same recovered site. Nothing was moved or deployed; run help. Sakupa will never merge unrelated credentials.",
+            {
+              projectRoot: ctx.projectDir,
+              siteDirectories: allSiteFiles.map(({ dir }) => dir),
+              recoveryDirectories: allRecoveries.map(({ dir }) => dir)
+            },
+            "blocked"
+          );
+        }
+        if (nestedRecoveryFiles.length > 0) {
+          const recovery = rootRecovery ?? nestedRecoveryFiles[0]?.file;
+          if (!recovery) throw new Error("recovery relocation lost its source state");
+          if (!rootRecovery) writeRecoveryFile(ctx.projectDir, recovery);
+          for (const { dir } of nestedRecoveryFiles) deleteRecoveryFile(dir);
+          for (const dir of markerRelocatedFrom) deleteProjectMarker(dir);
+          return structuredToolResult({
+            schemaVersion: 1,
+            outcome: "blocked",
+            resultCode: "recovery_relocated_resume_required",
+            summary: `Recovery state was moved safely to ${ctx.projectDir}/.sakupa before any deploy. The credential remains intact. Do not repeat DNS verification; call recover with action:"download" and outputDir:"${effectiveOutputDir}".`,
+            data: {
+              projectRoot: ctx.projectDir,
+              relocatedFrom: nestedRecoveryFiles.map(({ dir }) => dir),
+              credentialStoredLocally: true,
+              dnsVerificationRepeated: false
+            },
+            nextActions: [
+              {
+                tool: "recover",
+                arguments: { action: "download", outputDir: effectiveOutputDir },
+                allowed: true,
+                reasonCode: "credential_first_recovery_resume"
+              }
+            ]
+          });
+        }
+        for (const dir of markerRelocatedFrom.filter(
+          (candidate) => !credentialRelocatedFrom.includes(candidate)
+        )) {
+          deleteProjectMarker(dir);
         }
         if (!existing) {
           const barrier = freeSiteCreationBarrier(ctx.apiBaseUrl);
@@ -2847,7 +3338,10 @@ ${JSON.stringify(finalized2.warnings, null, 2)}` : ""),
         }
         const { uploaded, finalized } = update;
         writeSiteFile(ctx.projectDir, { ...existing, url: finalized.url });
-        if (credentialRelocatedFrom !== null) deleteSiteFile(credentialRelocatedFrom);
+        for (const source of credentialRelocatedFrom) {
+          deleteSiteFile(source);
+          if (markerRelocatedFrom.includes(source)) deleteProjectMarker(source);
+        }
         updateProjectOutputDir(ctx.projectDir, effectiveOutputDir);
         noteSiteMode(existing.siteId, finalized.mode);
         return text(
@@ -2857,7 +3351,7 @@ Environment: ${environmentFor(ctx.apiBaseUrl).toUpperCase()} (${ctx.apiBaseUrl})
 Project directory: ${ctx.projectDir}
 Files uploaded: ${uploaded} (${finalized.totalBytes} bytes)
 ` + (finalized.expiresAt ? `Validity refreshed \u2014 expires at: ${finalized.expiresAt}
-` : "") + (credentialRelocatedFrom ? `Credential binding relocated from ${credentialRelocatedFrom}/.sakupa to ${ctx.projectDir}/.sakupa; the existing site was preserved.
+` : "") + (credentialRelocatedFrom.length > 0 ? `Credential binding relocated from ${credentialRelocatedFrom.join(", ")} to ${ctx.projectDir}/.sakupa; the existing site was preserved.
 ` : "") + (finalized.mode === "free" ? `
 Reminder: free sites stay live for ${FREE_SITE_TTL_HOURS} hours after the last deploy or refresh call. Subscribing (subscribe) makes the site permanent.
 ` : "\nThis site is subscribed and permanent \u2014 no expiry.\n") + (finalized.warnings.length > 0 ? `
@@ -2873,7 +3367,7 @@ ${JSON.stringify(finalized.warnings, null, 2)}` : ""),
             filesUploaded: uploaded,
             totalBytes: finalized.totalBytes,
             warnings: finalized.warnings,
-            ...credentialRelocatedFrom ? { credentialRelocatedFrom } : {}
+            ...credentialRelocatedFrom.length > 0 ? { credentialRelocatedFrom } : {}
           }
         );
       } catch (e) {
@@ -2891,7 +3385,7 @@ ${JSON.stringify(finalized.warnings, null, 2)}` : ""),
     },
     async () => {
       try {
-        const ctx = withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx);
         const site = requireSiteFile(ctx);
         const res = await ctx.client.refreshSite(site.siteId, site.credential);
         return text(
@@ -2915,7 +3409,7 @@ NO content was uploaded or changed by this call \u2014 to publish new or edited
     },
     async () => {
       try {
-        const ctx = withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx);
         const site = requireSiteFile(ctx);
         const res = await ctx.client.getSiteStatus(site.siteId, site.credential);
         noteSiteMode(res.siteId, res.mode);
@@ -2950,13 +3444,13 @@ NO content was uploaded or changed by this call \u2014 to publish new or edited
     },
     async (args) => {
       try {
-        const ctx = withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx);
         const site = requireSiteFile(ctx);
         const res = await ctx.client.createPlanCheckout(
           {
             siteId: site.siteId,
             plan: args.plan,
-            idempotencyKey: randomUUID2()
+            idempotencyKey: randomUUID3()
           },
           site.credential
         );
@@ -2998,7 +3492,7 @@ Once payment confirms, the site becomes permanent on its current URL. Binding a
     },
     async (args) => {
       try {
-        const ctx = withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx);
         const site = requireSiteFile(ctx);
         if (args.action === "status") {
           const res2 = args.verificationId ? await ctx.client.checkVerification(args.verificationId, site.credential) : await ctx.client.checkVerification("latest", site.credential, site.siteId);
@@ -3107,7 +3601,7 @@ When the user says the TXT is set, run bind "status". It verifies ownership and
     },
     async () => {
       try {
-        const ctx = withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx);
         const site = requireSiteFile(ctx);
         const res = await ctx.client.getBillingStatus(site.siteId, site.credential);
         noteSiteMode(res.siteId, res.mode);
@@ -3151,7 +3645,7 @@ Full status:`, res);
     async (args) => {
       try {
         if (args.scope === "site") {
-          const ctx = withProjectDir(baseCtx);
+          const ctx = await withProjectDir(baseCtx);
           const site = requireSiteFile(ctx);
           const res2 = await ctx.client.createBillingPortal(site.siteId, site.credential);
           return structuredToolResult({
@@ -3212,7 +3706,7 @@ Full status:`, res);
     },
     async (args) => {
       try {
-        const ctx = withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx);
         if ((args.action === "complete" || args.action === "download") && args.outputDir === void 0) {
           throw new LocalGuidanceError(
             "invalid_request",
@@ -3521,7 +4015,7 @@ Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
     },
     async (args) => {
       try {
-        const ctx = withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx);
         const site = requireSiteFile(ctx);
         const res = await ctx.client.createTicket(site.credential, {
           siteId: site.siteId,
@@ -3543,11 +4037,12 @@ Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
   server.registerTool(
     "report",
     {
-      description: "Prepare and submit a sanitized bug report when a Sakupa tool failed and the issue looks like a product bug. Only whitelisted structured diagnostics are sent (tool name, error code/message, site id, bound domain, deployment id, timestamps, client/MCP version, request id) \u2014 NEVER file contents, source code, secrets, .env values or credentials. Without confirmSubmit: true the exact payload is shown for user review and nothing is submitted.",
+      description: "LAST RESORT after help explicitly returns reportRecommended:true. Prepare and submit a sanitized product bug report using helpAuthorization from that diagnosis. Only whitelisted structured diagnostics are sent (tool name, error code/message, site id, bound domain, deployment id, timestamps, client/MCP version, request id) \u2014 NEVER file contents, source code, secrets, .env values or credentials. Without confirmSubmit: true the exact payload is shown for user review and nothing is submitted.",
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
       inputSchema: {
         toolName: z2.string().describe('The Sakupa tool that failed, e.g. "deploy".'),
+        helpAuthorization: z2.string().describe("Short-lived authorization returned only by help when report is recommended."),
         errorCode: z2.string().optional(),
         errorMessage: z2.string().optional().describe("Sanitized error message (no secrets)."),
         requestId: z2.string().optional(),
@@ -3565,8 +4060,9 @@ Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
     },
     async (args) => {
       try {
-        const ctx = withProjectDir(baseCtx);
-        const siteState = loadSiteFile(ctx.projectDir);
+        requireReportAuthorization(baseCtx, args.helpAuthorization, args.toolName);
+        const ctx = await optionalProjectContext(baseCtx);
+        const siteState = ctx ? loadSiteFile(ctx.projectDir) : { kind: "absent" };
         const site = siteState.kind === "ok" ? siteState.file : null;
         const diagnostics = {
           toolName: args.toolName,
@@ -3597,7 +4093,7 @@ Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
             "preview"
           );
         }
-        const res = await ctx.client.reportBug(payload, site?.credential);
+        const res = await baseCtx.client.reportBug(payload, site?.credential);
         return text(
           "bug_report_submitted",
           `Bug report submitted. Ticket: ${res.ticketId}
@@ -3650,7 +4146,7 @@ function registerBillingTools(server, baseCtx) {
     },
     async (args) => {
       try {
-        const ctx = withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx);
         const site = requireSiteFile(ctx);
         const result = await ctx.client.changeSubscriptionPlan(site.credential, {
           siteId: site.siteId,
@@ -3679,7 +4175,7 @@ function registerBillingTools(server, baseCtx) {
 }
 
 // src/tools/lifecycle.ts
-import { randomUUID as randomUUID3 } from "node:crypto";
+import { randomUUID as randomUUID4 } from "node:crypto";
 import { z as z4 } from "zod";
 var deleteConfirmation = z4.object({
   siteId: z4.string().min(1),
@@ -3711,9 +4207,9 @@ function registerLifecycleTools(server, baseCtx) {
     },
     async (args) => {
       try {
-        const ctx = withProjectDir(baseCtx);
+        const ctx = await withProjectDir(baseCtx);
         const site = requireSiteFile(ctx);
-        const operationId = args.operationId ?? randomUUID3();
+        const operationId = args.operationId ?? randomUUID4();
         if (args.action === "preview") {
           const preview = await ctx.client.previewDeleteSite(site.siteId, site.credential, {
             operationId
@@ -3794,6 +4290,314 @@ function registerLifecycleTools(server, baseCtx) {
   );
 }
 
+// src/tools/help.ts
+import { join as join7 } from "node:path";
+import { z as z5 } from "zod";
+var TOOL_TOPICS = [
+  "init",
+  "analyze",
+  "deploy",
+  "refresh",
+  "status",
+  "plans",
+  "subscribe",
+  "bind",
+  "billing",
+  "portal",
+  "recover",
+  "change",
+  "delete",
+  "support",
+  "report",
+  "help"
+];
+var HELP_TOPICS = ["diagnose", "overview", ...TOOL_TOPICS];
+var TOOL_MANUALS = {
+  init: {
+    purpose: "Initialize the active IDE workspace as one Sakupa project.",
+    sideEffects: "Creates only .sakupa/project.json locally; no API call, site or charge.",
+    preconditions: "Exactly one usable MCP workspace Root. Clients without Roots use CLI init.",
+    parameters: "No parameters and no path argument.",
+    warnings: [
+      "Never initialize the IDE installation directory.",
+      "Existing site.json and recovery.json are preserved."
+    ],
+    nextStep: "Call analyze, then deploy with the exact relative outputDir."
+  },
+  analyze: {
+    purpose: "Inspect a project or explicit output directory for safe static deployment.",
+    sideEffects: "Read-only local file inspection; no API call.",
+    preconditions: "An initialized, unambiguous project binding.",
+    parameters: "Optional outputDir relative to the bound project Root.",
+    warnings: ["Build locally first.", "Never publish source, secrets, server code or media."],
+    nextStep: "Fix reported blockers, then call deploy with the exact outputDir."
+  },
+  deploy: {
+    purpose: "Create or update the bound Sakupa static site.",
+    sideEffects: "Reads local output, uploads files and may create a public free site.",
+    preconditions: "Initialized project, exact outputDir and first-publication confirmation.",
+    parameters: "outputDir is required and relative to the project Root.",
+    warnings: [
+      ".sakupa must remain at the project Root and is never uploaded.",
+      "A changed outputDir requires explicit confirmation."
+    ],
+    nextStep: "Call status to verify the cloud result."
+  },
+  refresh: {
+    purpose: "Extend a free site lifetime without uploading content.",
+    sideEffects: "Updates the site expiry in Sakupa.",
+    preconditions: "A valid local site credential.",
+    parameters: "No parameters.",
+    warnings: ["Subscribed sites are permanent and do not need refresh."],
+    nextStep: "Call status to verify the new expiry."
+  },
+  status: {
+    purpose: "Read the bound site, deployment, domain and serving state.",
+    sideEffects: "Read-only API request.",
+    preconditions: "A valid local site credential.",
+    parameters: "No parameters.",
+    warnings: ["Billing truth comes from billing, not inferred status text."],
+    nextStep: "Follow only the returned real tool names."
+  },
+  plans: {
+    purpose: "Read the authoritative hosting plan catalog and rules.",
+    sideEffects: "Read-only public API request.",
+    preconditions: "None; project initialization is not required.",
+    parameters: "No parameters.",
+    warnings: ["JPY prices and cloud plan order are authoritative."],
+    nextStep: "Use subscribe for first payment or change for an existing subscription."
+  },
+  subscribe: {
+    purpose: "Create Stripe Checkout for the first subscription.",
+    sideEffects: "Creates a short-lived Stripe Checkout session; payment happens only on Stripe.",
+    preconditions: "A free bound site with a valid credential.",
+    parameters: "The selected plan from plans.",
+    warnings: ["Creating a link does not subscribe or charge the user."],
+    nextStep: "Show the complete URL, then query billing after Stripe confirmation."
+  },
+  bind: {
+    purpose: "Start, check or inspect custom-domain binding.",
+    sideEffects: "May create DNS verification and hostname provisioning state.",
+    preconditions: "A subscribed site and DNS control.",
+    parameters: "Action plus hostname or verificationId as returned by the prior step.",
+    warnings: ["www is mandatory; the apex is optional.", "Copy DNS values verbatim."],
+    nextStep: "Follow the returned DNS checklist and call bind status/check."
+  },
+  billing: {
+    purpose: "Read the single authoritative subscription and usage snapshot.",
+    sideEffects: "Read-only API reconciliation.",
+    preconditions: "A valid bound site.",
+    parameters: "No parameters.",
+    warnings: ["Never infer renewal state from user wording or an old link."],
+    nextStep: "Use change or portal only when the user wants billing management."
+  },
+  portal: {
+    purpose: "Open Stripe billing/customer management or public recovery login.",
+    sideEffects: "Creates or returns a Stripe-hosted management URL.",
+    preconditions: "Site scope needs a credential; public recovery does not.",
+    parameters: "Use the supported scope.",
+    warnings: ["Opening a link does not change subscription state."],
+    nextStep: "Query billing after the user confirms an operation in Stripe."
+  },
+  recover: {
+    purpose: "Recover a paid custom-domain site credential and download its content.",
+    sideEffects: "Creates DNS verification state and writes local credential/archive files.",
+    preconditions: "DNS control of a domain bound to an active paid site.",
+    parameters: "Use the returned action and verificationId; outputDir is relative to Root.",
+    warnings: [
+      "After site.json exists, resume download and never repeat DNS verification.",
+      "Credential is saved before archive creation/download."
+    ],
+    nextStep: "Call recover download when local credentials already exist."
+  },
+  change: {
+    purpose: "Open the unified Stripe subscription-management page.",
+    sideEffects: "Creates a short-lived Portal session and audit record only.",
+    preconditions: "An active subscription.",
+    parameters: "No plan direction or target is accepted from conversational intent.",
+    warnings: ["Only Stripe confirmation changes the subscription."],
+    nextStep: "Call billing after the user finishes on Stripe."
+  },
+  delete: {
+    purpose: "Preview and permanently delete a free site.",
+    sideEffects: "Confirm permanently removes content, URL and local site credential.",
+    preconditions: "Paid subscriptions must fully end and return the site to free mode first.",
+    parameters: "Preview first; confirm with the exact returned confirmArguments.",
+    warnings: [
+      "Never guess timestamps or confirmation fields from status.",
+      "Deletion is irreversible and does not secretly cancel payment."
+    ],
+    nextStep: "Use the preview userAction.resumeWith arguments verbatim."
+  },
+  support: {
+    purpose: "Create a customer-service ticket for billing, refund, payment or domain assistance.",
+    sideEffects: "Submits a support ticket.",
+    preconditions: "A bound subscribed site and user-provided issue description.",
+    parameters: "Category, subject, sanitized description and optional contact email.",
+    warnings: ["Never include credentials, source, card data or secrets."],
+    nextStep: "Wait for support follow-up."
+  },
+  report: {
+    purpose: "Last-resort product bug report after help recommends it.",
+    sideEffects: "Preview is local; confirmSubmit sends a sanitized diagnostic report.",
+    preconditions: "Call help first and show the exact report preview to the user.",
+    parameters: "Failed tool, helpAuthorization, sanitized diagnostics and explicit confirmSubmit.",
+    warnings: [
+      "Never report ordinary setup errors help can solve.",
+      "Submission requires approval."
+    ],
+    nextStep: "Submit only after the user reviews the preview."
+  },
+  help: {
+    purpose: "Diagnose the current MCP/project state or explain any Sakupa tool.",
+    sideEffects: "Read-only local diagnosis; no API call or file write.",
+    preconditions: "None; works even when project binding is broken.",
+    parameters: "topic defaults to diagnose; use overview or a tool name for its manual.",
+    warnings: ["Use help before repeating failed calls or suggesting report."],
+    nextStep: "Follow the returned diagnosis and nextActions."
+  }
+};
+function registerHelpTools(server, baseCtx) {
+  server.registerTool(
+    "init",
+    {
+      description: "Initialize the active MCP workspace Root as a Sakupa project. Takes no path argument, creates only .sakupa/project.json at that exact Root, preserves site/recovery state, makes no API call and is idempotent. Clients without MCP Roots must use the no-argument CLI init.",
+      inputSchema: {},
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
+    },
+    async () => {
+      try {
+        const ctx = await initializeWorkspaceProject(baseCtx);
+        const marker = loadProjectMarker(ctx.projectDir);
+        if (marker.kind !== "ok")
+          throw new Error("init postcondition failed: project marker missing");
+        const site = loadSiteFile(ctx.projectDir);
+        const recovery = loadRecoveryFile(ctx.projectDir);
+        const sakupaDirectory = join7(ctx.projectDir, ".sakupa");
+        return structuredToolResult({
+          schemaVersion: 1,
+          outcome: "completed",
+          resultCode: "project_initialized",
+          summary: `Sakupa project initialized and verified at the active workspace Root: ${ctx.projectDir}. .sakupa is at ${sakupaDirectory}; no cloud site was created and no charge occurred.`,
+          data: {
+            projectRoot: ctx.projectDir,
+            sakupaDirectory,
+            projectId: marker.marker.projectId,
+            bindingSource: ctx.bindingSource,
+            sakupaAtProjectRoot: true,
+            postconditionVerified: true,
+            existingSitePreserved: site.kind !== "absent",
+            existingRecoveryPreserved: recovery !== null,
+            cloudApiCalled: false
+          },
+          nextActions: [{ tool: "analyze", allowed: true, reasonCode: "project_ready" }]
+        });
+      } catch (error) {
+        return toolError(error);
+      }
+    }
+  );
+  server.registerTool(
+    "help",
+    {
+      description: "FIRST troubleshooting tool for every Sakupa difficulty. With topic diagnose (default), inspect MCP Roots, cwd, binding and local state without requiring a project or calling the API. Use overview or a tool name for complete usage, side effects, parameters and warnings. Only recommend report when help explicitly returns reportRecommended:true.",
+      inputSchema: {
+        topic: z5.enum(HELP_TOPICS).optional().default("diagnose"),
+        failedTool: z5.string().optional(),
+        errorCode: z5.string().optional(),
+        resultCode: z5.string().optional(),
+        requestId: z5.string().optional()
+      },
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
+    },
+    async (args) => {
+      try {
+        if (args.topic === "overview") {
+          const catalog = Object.fromEntries(
+            TOOL_TOPICS.map((tool) => [tool, { purpose: TOOL_MANUALS[tool].purpose }])
+          );
+          return structuredToolResult({
+            schemaVersion: 1,
+            outcome: "completed",
+            resultCode: "help_overview",
+            summary: 'Sakupa tool overview returned. On any failure call help with topic:"diagnose" before retrying, support or report.',
+            data: { tools: catalog, toolOrder: TOOL_TOPICS },
+            nextActions: []
+          });
+        }
+        if (args.topic !== "diagnose") {
+          const manual = TOOL_MANUALS[args.topic];
+          return structuredToolResult({
+            schemaVersion: 1,
+            outcome: "completed",
+            resultCode: "help_tool_manual",
+            summary: `${args.topic}: ${manual.purpose}
+Side effects: ${manual.sideEffects}
+Preconditions: ${manual.preconditions}
+Parameters: ${manual.parameters}
+Warnings: ${manual.warnings.join(" ")}
+Next: ${manual.nextStep}`,
+            data: { tool: args.topic, ...manual },
+            nextActions: []
+          });
+        }
+        const diagnosis = await diagnoseProjectBinding(baseCtx);
+        const selected = diagnosis.selectedProjectDir;
+        const marker = selected ? loadProjectMarker(selected) : { kind: "absent" };
+        const site = selected ? loadSiteFile(selected) : { kind: "absent" };
+        let recoveryState = "absent";
+        if (selected) {
+          try {
+            recoveryState = loadRecoveryFile(selected) === null ? "absent" : "ok";
+          } catch {
+            recoveryState = "corrupted";
+          }
+        }
+        const opaqueFailure = args.errorCode === "internal" || args.resultCode === "error_internal";
+        const reportRecommended = opaqueFailure && (diagnosis.diagnosisCode === "project_bound" || diagnosis.diagnosisCode === "roots_request_failed");
+        const helpAuthorization = reportRecommended ? issueReportAuthorization(baseCtx, args.failedTool ?? "unknown") : void 0;
+        const nextActions = reportRecommended ? [
+          {
+            tool: "report",
+            arguments: {
+              toolName: args.failedTool ?? "unknown",
+              helpAuthorization,
+              ...args.errorCode !== void 0 ? { errorCode: args.errorCode } : {},
+              ...args.requestId !== void 0 ? { requestId: args.requestId } : {}
+            },
+            allowed: true,
+            reasonCode: "help_confirmed_last_resort"
+          }
+        ] : diagnosis.diagnosisCode === "workspace_not_initialized" ? [{ tool: "init", allowed: true, reasonCode: "initialize_active_root" }] : [];
+        const summary = `Help diagnosis: ${diagnosis.diagnosisCode}. ${diagnosis.guidance} MCP version: ${MCP_VERSION}. ` + (reportRecommended ? diagnosis.diagnosisCode === "project_bound" ? "Local project binding is healthy but the failure is an unclassified internal error. report is now available as the last resort; preview it before submission." : "The MCP Roots request itself failed with an unclassified internal error. report is now available as the last resort; preview it before submission." : "Do not submit report for this diagnosis; follow the guidance and retry help.");
+        return structuredToolResult({
+          schemaVersion: 1,
+          outcome: diagnosis.diagnosisCode === "project_bound" ? "completed" : "blocked",
+          resultCode: `help_${diagnosis.diagnosisCode}`,
+          summary,
+          data: {
+            ...diagnosis,
+            mcpVersion: MCP_VERSION,
+            projectMarkerState: marker.kind,
+            siteState: site.kind,
+            recoveryState,
+            reportRecommended,
+            ...helpAuthorization !== void 0 ? { helpAuthorization } : {},
+            ...args.failedTool !== void 0 ? { failedTool: args.failedTool } : {},
+            ...args.errorCode !== void 0 ? { errorCode: args.errorCode } : {},
+            ...args.resultCode !== void 0 ? { failedResultCode: args.resultCode } : {}
+          },
+          nextActions
+        });
+      } catch (error) {
+        return toolError(error);
+      }
+    }
+  );
+}
+
 // src/transport.ts
 var FetchTransport = class {
   baseUrl;
@@ -3892,6 +4696,7 @@ var FetchTransport = class {
 };
 
 // src/server.ts
+import { resolve as resolve6 } from "node:path";
 var instructionsFor = (hostPattern) => `Sakupa publishes AI-made static websites. AI-made pages, live in seconds.
 
 Workflow:
@@ -3921,14 +4726,17 @@ Workflow:
    24h site and removes paid data after Stripe sends the signed final-cancellation webhook.
    Recovery writes the new local credential before downloading content. If a session stops after
    .sakupa/site.json exists, NEVER repeat DNS recovery: resume with recover action "download".
-5. support (subscribed sites) opens a support ticket; report sends a
-   sanitized diagnostic report after the user explicitly confirms it.
+5. If any Sakupa operation is difficult or fails, call help FIRST. support handles billing,
+   payment, refund and other customer-service requests. report is the LAST resort only when
+   help explicitly recommends a product bug report, and submission still requires user review.
 
 Project directory contract: before the first deploy or a new recovery, initialize the intended
-project once by running "npx -y @sakupa/mcp@latest init" with NO path argument from the AI
-tool's current project directory. This immediately creates the non-secret .sakupa/project.json
-there. ONE MCP process = ONE cwd-locked project = ONE site. Site tools do not accept projectDir
-and cannot select another root; plans and public_recovery portal remain project-independent.
+project by calling init with NO path argument. init uses the IDE's exact MCP Root and creates the
+non-secret .sakupa/project.json directly there. The CLI command
+"npx -y @sakupa/mcp@latest init" remains the safe fallback for clients without MCP Roots and
+also accepts NO path argument. ONE MCP process = ONE Roots-first locked project = ONE site.
+Site tools do not accept projectDir and cannot select another root; help, plans, report preview
+and public_recovery portal remain project-independent.
 Sakupa stores .sakupa/site.json and recovery state only in the locked directory; it never uses
 package.json, .git, framework names or output-directory names to guess. For deploy, ALWAYS pass
 outputDir separately as the exact path RELATIVE to the locked directory (use "." when publishing
@@ -3936,14 +4744,17 @@ the root); outputDir is
 required and may have ANY name, so inspect the current project. If it differs from the last
 successful publish directory, show the old and new paths and obtain explicit confirmation
 before retrying with outputDirChangeConfirmed: true.
+After init, require sakupaAtProjectRoot=true. Before deploy, Sakupa checks every directory segment
+between the project Root and outputDir for a misplaced .sakupa and safely relocates only validated,
+non-conflicting state; never copy, delete or overwrite site.json by shell command.
 After every deploy, TELL the user which environment it went to (deploy results carry an
 Explicit Environment line: TEST vs PRODUCTION). analyze, deploy, status,
 refresh and delete echo
-the cwd-locked directory they acted on.
+the Roots-first locked directory they acted on.
 
-When the same operation fails twice in a row, or the user is clearly stuck or
-frustrated, proactively offer report: it files the problem into Sakupa's ticket and
-alert stream, and you should attach your own factual account via agentContext.
+On any difficulty, call help before retrying or escalating. Only offer report when help returns
+reportRecommended:true; attach your own factual account via agentContext and show the exact
+sanitized preview before asking the user to confirm submission.
 
 Present every step as Sakupa's own: never attribute DNS, certificates or hosting to
 underlying infrastructure vendors in front of the user. Relay DNS record values and full
@@ -3977,14 +4788,32 @@ function createSakupaMcpServer(opts) {
     { name: "sakupa", version: MCP_VERSION },
     { instructions: instructionsFor(previewHostPatternFor(opts.apiBaseUrl)) }
   );
+  const processCwd = resolve6(opts.projectDir ?? process.cwd());
+  const rootsProvider = opts.rootsProvider ?? (async () => {
+    const capabilities = server.server.getClientCapabilities();
+    if (!capabilities?.roots) return { supported: false, roots: [] };
+    try {
+      const response = await server.server.listRoots();
+      return { supported: true, roots: response.roots };
+    } catch (error) {
+      return {
+        supported: true,
+        roots: [],
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  });
   const ctx = {
     client,
     apiBaseUrl: opts.apiBaseUrl,
-    projectDir: canonicalProjectDirectory(opts.projectDir ?? process.cwd())
+    projectDir: processCwd,
+    rootsProvider,
+    projectBinding: new ProjectBindingResolver(processCwd, rootsProvider)
   };
   registerTools(server, ctx);
   registerBillingTools(server, ctx);
   registerLifecycleTools(server, ctx);
+  registerHelpTools(server, ctx);
   return server;
 }
 
@@ -4007,7 +4836,7 @@ async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `[sakupa-mcp] v${MCP_VERSION} connected (api: ${config.apiBaseUrl}; project: ${process.cwd()})`
+    `[sakupa-mcp] v${MCP_VERSION} connected (api: ${config.apiBaseUrl}; process cwd fallback: ${process.cwd()}; MCP Roots preferred)`
   );
 }
 main().catch((err2) => {