@sakupa/mcp 0.7.41 → 0.7.43

package/dist/bin.js

@@ -258,6 +258,7 @@ var SERVICE_DOMAIN = "sakupa.com";
 var DEFAULT_API_BASE_URL = "https://api.sakupa.com";
 var FREE_SITE_URL_SUFFIX = `.${SERVICE_DOMAIN}`;
 var TEST_ACCESS_HEADER = "x-sakupa-test-token";
+var CREDENTIAL_ROTATION_RECOMMEND_AFTER_SECONDS = 7 * 24 * 60 * 60;
 var FREE_SITE_TTL_HOURS = 24;
 var FREE_SITE_MAX_TOTAL_BYTES = 10 * 1024 * 1024;
 var FREE_ACTIVE_SITES_PER_IP = 3;
@@ -379,7 +380,7 @@ var FORBIDDEN_PATH_SEGMENTS = [
 var ALLOWED_HIDDEN_PATHS = [".well-known/"];
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "0.7.41";
+var SAKUPA_MCP_VERSION = "0.7.43";
 
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
@@ -835,6 +836,20 @@ var HttpApiClient = class {
       credential
     });
   }
+  async getCredentialStatus(siteId, credential) {
+    return this.call(
+      "GET",
+      `/v1/sites/${encodeURIComponent(siteId)}/credential`,
+      { credential }
+    );
+  }
+  async rotateCredential(siteId, credential, req) {
+    return this.call(
+      "POST",
+      `/v1/sites/${encodeURIComponent(siteId)}/credential/rotate`,
+      { credential, body: req }
+    );
+  }
   async getSiteArchive(siteId, credential) {
     return this.call(
       "GET",
@@ -938,9 +953,9 @@ var HttpApiClient = class {
 };
 
 // src/tools/definitions.ts
-import { randomUUID as randomUUID3 } from "node:crypto";
+import { randomUUID as randomUUID5 } from "node:crypto";
 import { promises as fs2 } from "node:fs";
-import { join as join7, relative as relative3, resolve as resolve5, sep as sep4 } from "node:path";
+import { join as join8, relative as relative3, resolve as resolve5, sep as sep4 } from "node:path";
 import { z as z2 } from "zod";
 
 // src/analyze/analyzer.ts
@@ -1378,10 +1393,12 @@ import {
   existsSync as existsSync2,
   mkdirSync as mkdirSync2,
   readFileSync as readFileSync2,
+  renameSync as renameSync2,
   rmdirSync as rmdirSync2,
   rmSync,
   writeFileSync as writeFileSync2
 } from "node:fs";
+import { randomUUID as randomUUID2 } from "node:crypto";
 import { dirname, join as join3 } from "node:path";
 var SITE_DIR = ".sakupa";
 var SITE_FILE = "site.json";
@@ -1492,12 +1509,22 @@ function writeSiteFile(projectDir, file, opts = {}) {
   const dir = join3(projectDir, SITE_DIR);
   mkdirSync2(dir, { recursive: true });
   const path = join3(dir, SITE_FILE);
-  writeFileSync2(path, `${JSON.stringify(file, null, 2)}
-`, "utf8");
+  const temporary = join3(dir, `.site-${randomUUID2()}.tmp`);
+  writeFileSync2(temporary, `${JSON.stringify(file, null, 2)}
+`, {
+    encoding: "utf8",
+    mode: 384
+  });
   try {
-    chmodSync2(path, 384);
+    chmodSync2(temporary, 384);
   } catch {
   }
+  try {
+    renameSync2(temporary, path);
+  } catch (error) {
+    rmSync(temporary, { force: true });
+    throw error;
+  }
 }
 function deleteSiteFile(projectDir) {
   const path = siteFilePath(projectDir);
@@ -1959,15 +1986,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 [
@@ -1978,7 +2005,7 @@ var z64hs = function(d, b, l, z5, sc, su, off) {
         ];
       }
     }
-    if (z5 < 2)
+    if (z6 < 2)
       err(13);
   }
   return [sc, su, off, 0];
@@ -1995,18 +2022,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,
@@ -2285,34 +2312,37 @@ function resolveReusableSite(rawUrl, currentProjectDir, nowMs, apiBaseUrl) {
   });
   if (matches2.length === 0) {
     throw new Error(
-      `No reusable local free-site slot matches ${siteUrl}. Run deploy again for a current list.`
+      `No existing local free site eligible for handoff matches ${siteUrl}. Run deploy again for a current list.`
     );
   }
-  if (matches2.length > 1) throw new Error(`More than one local slot matches ${siteUrl}.`);
+  if (matches2.length > 1)
+    throw new Error(`More than one local free-site record matches ${siteUrl}.`);
   const record = matches2[0];
-  if (!record) throw new Error("The reusable slot disappeared during resolution.");
+  if (!record) throw new Error("The selected existing free site disappeared during resolution.");
   if (!isAbsolute3(record.projectDir)) {
-    throw new Error("The reusable slot project path is not absolute; refusing cwd lookup.");
+    throw new Error("The selected free-site project path is not absolute; refusing cwd lookup.");
   }
   const sourceProjectDir = canonicalProjectDirectory(record.projectDir);
   if (sourceProjectDir === canonicalProjectDirectory(currentProjectDir)) {
-    throw new Error("The selected reusable slot already belongs to the current project.");
+    throw new Error("The selected existing free site already belongs to the current project.");
   }
   const state = loadSiteFile(sourceProjectDir);
   if (state.kind === "absent") {
-    throw new Error("The selected slot no longer has its original local management credential.");
+    throw new Error(
+      "The selected existing free site no longer has its original local management credential."
+    );
   }
   if (state.kind === "corrupted") {
-    throw new Error(`The selected slot credential is damaged: ${state.problem}`);
+    throw new Error(`The selected existing free-site credential is damaged: ${state.problem}`);
   }
   if (state.file.siteId !== record.siteId) {
-    throw new Error("The slot registry and original project refer to different sites.");
+    throw new Error("The local free-site record and original project refer to different sites.");
   }
   if (!state.file.url || normalizeSiteUrl(state.file.url) !== siteUrl) {
-    throw new Error("The slot URL does not match the original project binding.");
+    throw new Error("The selected free-site URL does not match the original project binding.");
   }
   if (state.file.apiBaseUrl !== "" && state.file.apiBaseUrl !== apiBaseUrl) {
-    throw new Error("The selected slot belongs to another Sakupa environment.");
+    throw new Error("The selected existing free site belongs to another Sakupa environment.");
   }
   return { record, sourceProjectDir, site: state.file, siteUrl };
 }
@@ -2334,7 +2364,7 @@ function acquireSiteHandoffLock(siteId) {
     fd2 = openSync(path, "wx", 384);
   } catch {
     throw new Error(
-      "Another Sakupa process is already reassigning this free-site slot. Wait for it to finish and retry deploy."
+      "Another Sakupa process is already performing a site handoff for this free site. Wait for it to finish and retry deploy."
     );
   }
   writeFileSync4(fd2, JSON.stringify({ siteId, createdAt: (/* @__PURE__ */ new Date()).toISOString() }));
@@ -2518,6 +2548,172 @@ ${diag.layers}
 var MCP_VERSION = SAKUPA_MCP_VERSION;
 var CLIENT_TYPE = "sakupa-mcp";
 
+// src/credential-rotation.ts
+import {
+  chmodSync as chmodSync3,
+  existsSync as existsSync6,
+  mkdirSync as mkdirSync5,
+  readFileSync as readFileSync4,
+  renameSync as renameSync3,
+  rmSync as rmSync2,
+  writeFileSync as writeFileSync5
+} from "node:fs";
+import { randomUUID as randomUUID3 } from "node:crypto";
+import { join as join7 } from "node:path";
+var ROTATION_FILE = "rotation.json";
+function credentialRotationPath(projectDir) {
+  return join7(projectDir, ".sakupa", ROTATION_FILE);
+}
+function loadCredentialRotation(projectDir) {
+  const path = credentialRotationPath(projectDir);
+  if (!existsSync6(path)) return { kind: "absent" };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync4(path, "utf8"));
+  } catch (error) {
+    return {
+      kind: "corrupted",
+      problem: `the file cannot be read as JSON (${error instanceof Error ? error.message : String(error)})`
+    };
+  }
+  if (typeof parsed.siteId !== "string" || parsed.siteId.length === 0) {
+    return { kind: "corrupted", problem: "siteId is missing or empty" };
+  }
+  if (typeof parsed.candidateCredential !== "string" || !CREDENTIAL_PATTERN.test(parsed.candidateCredential)) {
+    return { kind: "corrupted", problem: "candidateCredential has an invalid shape" };
+  }
+  if (typeof parsed.createdAt !== "string" || !Number.isFinite(Date.parse(parsed.createdAt))) {
+    return { kind: "corrupted", problem: "createdAt is missing or invalid" };
+  }
+  if (typeof parsed.apiBaseUrl !== "string" || parsed.apiBaseUrl.length === 0) {
+    return { kind: "corrupted", problem: "apiBaseUrl is missing or empty" };
+  }
+  return {
+    kind: "ok",
+    file: {
+      siteId: parsed.siteId,
+      candidateCredential: parsed.candidateCredential,
+      createdAt: parsed.createdAt,
+      apiBaseUrl: parsed.apiBaseUrl
+    }
+  };
+}
+function writeCredentialRotation(projectDir, file) {
+  if (!CREDENTIAL_PATTERN.test(file.candidateCredential)) {
+    throw new Error("Refusing to persist an invalid credential rotation candidate.");
+  }
+  const current = loadCredentialRotation(projectDir);
+  if (current.kind === "corrupted") {
+    throw new Error(
+      `Refusing to overwrite damaged credential rotation state: ${current.problem}. Run help.`
+    );
+  }
+  if (current.kind === "ok") {
+    if (current.file.siteId === file.siteId && current.file.candidateCredential === file.candidateCredential && current.file.apiBaseUrl === file.apiBaseUrl) {
+      return;
+    }
+    throw new Error(
+      "A different credential rotation is already pending. Run rotate to resume it; no state was overwritten."
+    );
+  }
+  const directory = join7(projectDir, ".sakupa");
+  mkdirSync5(directory, { recursive: true, mode: 448 });
+  const target = credentialRotationPath(projectDir);
+  const temporary = join7(directory, `.rotation-${randomUUID3()}.tmp`);
+  writeFileSync5(temporary, `${JSON.stringify(file, null, 2)}
+`, {
+    encoding: "utf8",
+    mode: 384
+  });
+  try {
+    chmodSync3(temporary, 384);
+  } catch {
+  }
+  try {
+    renameSync3(temporary, target);
+  } catch (error) {
+    rmSync2(temporary, { force: true });
+    throw error;
+  }
+}
+function deleteCredentialRotation(projectDir) {
+  rmSync2(credentialRotationPath(projectDir), { force: true });
+}
+function promoteRotatedCredential(projectDir, site, rotation, credentialCreatedAt) {
+  if (rotation.siteId !== site.siteId || rotation.apiBaseUrl !== site.apiBaseUrl) {
+    throw new Error(
+      "Credential rotation state belongs to a different site or Sakupa environment; no file was changed."
+    );
+  }
+  if (!Number.isFinite(Date.parse(credentialCreatedAt))) {
+    throw new Error(
+      "The server returned an invalid credential creation time; no file was changed."
+    );
+  }
+  const updated = {
+    ...site,
+    credential: rotation.candidateCredential,
+    createdAt: credentialCreatedAt
+  };
+  writeSiteFile(projectDir, updated);
+  deleteCredentialRotation(projectDir);
+  return updated;
+}
+async function resumeCredentialRotation(client, projectDir, site, apiBaseUrl) {
+  const state = loadCredentialRotation(projectDir);
+  if (state.kind === "absent") return null;
+  if (state.kind === "corrupted") {
+    throw new Error(
+      `Credential rotation state is damaged (${state.problem}). Nothing was overwritten; run help.`
+    );
+  }
+  const pending = state.file;
+  const siteEnvironment = site.apiBaseUrl || apiBaseUrl;
+  if (pending.siteId !== site.siteId || pending.apiBaseUrl !== apiBaseUrl || siteEnvironment !== apiBaseUrl) {
+    throw new Error(
+      "Credential rotation state belongs to a different site or Sakupa environment. Nothing was changed; run help."
+    );
+  }
+  try {
+    const status = await client.getCredentialStatus(site.siteId, pending.candidateCredential);
+    return {
+      site: promoteRotatedCredential(
+        projectDir,
+        { ...site, apiBaseUrl },
+        pending,
+        status.credentialCreatedAt
+      ),
+      status,
+      rotation: null,
+      resumed: true
+    };
+  } catch (error) {
+    if (!isSakupaError(error) || error.code !== "unauthorized") throw error;
+  }
+  try {
+    await client.getCredentialStatus(site.siteId, site.credential);
+  } catch (error) {
+    if (!isSakupaError(error) || error.code !== "unauthorized") throw error;
+    throw new Error(
+      "Neither the current nor pending credential is accepted. No local file was overwritten; run help before retrying."
+    );
+  }
+  const rotation = await client.rotateCredential(site.siteId, site.credential, {
+    newCredential: pending.candidateCredential
+  });
+  return {
+    site: promoteRotatedCredential(
+      projectDir,
+      { ...site, apiBaseUrl },
+      pending,
+      rotation.credentialCreatedAt
+    ),
+    status: rotation,
+    rotation,
+    resumed: true
+  };
+}
+
 // src/project-binding.ts
 import { fileURLToPath } from "node:url";
 import { resolve as resolve4 } from "node:path";
@@ -2820,7 +3016,7 @@ function structuredToolResult(envelope) {
 }
 
 // src/tools/context.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID4 } from "node:crypto";
 var LocalGuidanceError = class extends SakupaError {
   constructor(code, message) {
     super(code, message);
@@ -2899,7 +3095,7 @@ function reportAuthorizationStore(ctx) {
   return store;
 }
 function issueReportAuthorization(ctx, failedTool) {
-  const token = randomUUID2();
+  const token = randomUUID4();
   reportAuthorizationStore(ctx).set(token, {
     failedTool,
     expiresAt: Date.now() + 10 * 60 * 1e3
@@ -2978,14 +3174,14 @@ function toolError(e) {
 }
 
 // src/tools/definitions.ts
-function text(resultCode, t, data = {}, outcome = "completed") {
+function text(resultCode, t, data = {}, outcome = "completed", nextActions = []) {
   return structuredToolResult({
     schemaVersion: 1,
     outcome,
     resultCode,
     summary: t,
     data,
-    nextActions: []
+    nextActions
   });
 }
 function textJson(resultCode, header, obj, outcome = "completed") {
@@ -3053,7 +3249,7 @@ function ensureUploadSizeWithinLimits(manifest, isFirstFreeDeploy) {
 async function buildHashedManifest(files, outputAbs) {
   const manifest = [];
   for (const file of files) {
-    const bytes = new Uint8Array(await fs2.readFile(join7(outputAbs, file.path)));
+    const bytes = new Uint8Array(await fs2.readFile(join8(outputAbs, file.path)));
     manifest.push({ path: file.path, size: file.size, contentHash: await sha256Hex(bytes) });
   }
   return manifest;
@@ -3072,7 +3268,7 @@ async function uploadAll(ctx, targets, files, outputAbs) {
         `No local file matches upload target "${target.path}"; aborting upload.`
       );
     }
-    const bytes = new Uint8Array(await fs2.readFile(join7(outputAbs, match.path)));
+    const bytes = new Uint8Array(await fs2.readFile(join8(outputAbs, match.path)));
     if (bytes.byteLength !== match.size) {
       throw new SakupaError(
         "validation_failed",
@@ -3121,11 +3317,11 @@ function freeSiteCreationBarrier(apiBaseUrl, deployArguments) {
   const userSiteOptions = recent.map((record) => ({
     label: `Replace content at ${record.siteUrl}`,
     value: record.siteUrl,
-    expectedOutcome: "The current project takes over this reusable free-site slot and replaces its online content."
+    expectedOutcome: "A site handoff keeps this existing free-site URL and cloud credential, replaces its online content, and moves the sole local binding to the current project."
   }));
   const summary = `LOCAL PRECHECK by this MCP client (its own creation registry \u2014 the server was NOT contacted): this machine already created ${recent.length} sites in this environment in the last 24 hours, matching the server's limit of ${FREE_ACTIVE_SITES_PER_IP} active free sites per IP. No new site was created.
 
-` + recent.map((record) => `- ${record.siteUrl}`).join("\n") + "\n\nAsk the user which existing free URL may be REPLACED by the current project. Selecting one authorizes deploy to overwrite that URL with the current files and transfer its local management binding to this project. The cloud site is NOT deleted. The previous project is unbound and its matching credential file is removed after a successful publish; tell the user not to manage this URL from the previous project. YOU then call deploy with the exact nextAction arguments. Never switch workspaces, never ask the user to run a CLI, and never recommend another hosting provider.";
+` + recent.map((record) => `- ${record.siteUrl}`).join("\n") + "\n\nThe free-site allowance is full. Ask the user which existing free URL may have its content REPLACED by the current project. Selecting one authorizes a site handoff: deploy keeps that URL and cloud credential, overwrites its online content with the current files, and moves its sole local management binding to this project. The cloud site is NOT deleted. The previous project is unbound and its matching credential file is removed after a successful publish; tell the user not to manage this URL from the previous project. YOU then call deploy with the exact nextAction arguments. Never switch workspaces, never ask the user to run a CLI, and never recommend another hosting provider.";
   return structuredToolResult({
     schemaVersion: 1,
     outcome: "waiting_user",
@@ -3165,14 +3361,14 @@ function outputDirectoryChain(projectRoot, outputAbs) {
   const chain = [];
   let cursor = projectRoot;
   for (const part of rel.split(sep4).filter(Boolean)) {
-    cursor = join7(cursor, part);
+    cursor = join8(cursor, part);
     chain.push(cursor);
   }
   return chain;
 }
 async function sakupaDirectoryEntries(projectDir) {
   try {
-    return await fs2.readdir(join7(projectDir, ".sakupa"));
+    return await fs2.readdir(join8(projectDir, ".sakupa"));
   } catch (error) {
     const code = error.code;
     if (code === "ENOENT") return [];
@@ -3231,7 +3427,7 @@ Next action: ${analysis.suggestedNextAction}`,
           "Required only for the first deployment: user explicitly confirmed creation of a public 24-hour URL."
         ),
         reuseSiteUrl: z2.string().url().optional().describe(
-          "Exact existing free-site URL selected by the user when all three reusable slots are occupied. Never invent this value; copy it from deploy nextActions."
+          "Exact existing free-site URL selected by the user when the three-site free-site allowance is full. Never invent this value; copy it from deploy nextActions."
         ),
         reuseConfirmed: z2.boolean().optional().describe(
           "True only after the user selected reuseSiteUrl knowing its online content will be replaced and its previous project will be unbound."
@@ -3283,6 +3479,8 @@ Next action: ${analysis.suggestedNextAction}`,
         }
         let existing = siteFileState.kind === "ok" ? siteFileState.file : null;
         let handoff = null;
+        let credentialSecurity = null;
+        let credentialRotationResumed = false;
         const resumedHandoffCleanup = existing ? resumeLocalSiteHandoff(ctx.projectDir, existing, Date.now()) : null;
         const credentialRelocatedFrom = [];
         const markerRelocatedFrom = [];
@@ -3320,8 +3518,8 @@ Next action: ${analysis.suggestedNextAction}`,
                 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: join7(candidateDir, ".sakupa"),
-                  targetSakupaDirectory: join7(ctx.projectDir, ".sakupa"),
+                  misplacedSakupaDirectory: join8(candidateDir, ".sakupa"),
+                  targetSakupaDirectory: join8(ctx.projectDir, ".sakupa"),
                   confirmationField: "sakupaRelocationConfirmed"
                 },
                 nextActions: [
@@ -3434,7 +3632,7 @@ Next action: ${analysis.suggestedNextAction}`,
         if (existing && args.reuseSiteUrl !== void 0) {
           return text(
             "current_project_already_bound",
-            `The current project already manages ${existing.url ?? existing.siteId}. reuseSiteUrl is only valid for an unbound project choosing one of its three existing free slots. Nothing was uploaded or rebound.`,
+            `The current project already manages ${existing.url ?? existing.siteId}. reuseSiteUrl is only valid for an unbound project choosing an existing free site for a site handoff. Nothing was uploaded or rebound.`,
             { currentSiteId: existing.siteId, currentUrl: existing.url },
             "blocked"
           );
@@ -3493,6 +3691,17 @@ Next action: ${analysis.suggestedNextAction}`,
               ctx.apiBaseUrl
             );
             releaseHandoffLock = acquireSiteHandoffLock(handoff.site.siteId);
+            const resumedSourceRotation = await resumeCredentialRotation(
+              ctx.client,
+              handoff.sourceProjectDir,
+              handoff.site,
+              ctx.apiBaseUrl
+            );
+            if (resumedSourceRotation) {
+              handoff = { ...handoff, site: resumedSourceRotation.site };
+              credentialSecurity = resumedSourceRotation.status;
+              credentialRotationResumed = true;
+            }
             const cloud = await ctx.client.getSiteStatus(
               handoff.site.siteId,
               handoff.site.credential
@@ -3501,7 +3710,7 @@ Next action: ${analysis.suggestedNextAction}`,
               noteSiteMode(cloud.siteId, cloud.mode);
               return text(
                 "selected_site_no_longer_uses_free_slot",
-                `${handoff.siteUrl} is now paid and does not consume a free-site slot. It was not changed or rebound. Call deploy again; Sakupa can now create a new free site.`,
+                `${handoff.siteUrl} is now paid and does not count toward the free-site allowance. It was not changed or rebound. Call deploy again; Sakupa can now create a new free site.`,
                 { siteUrl: handoff.siteUrl, mode: cloud.mode },
                 "blocked"
               );
@@ -3509,7 +3718,7 @@ Next action: ${analysis.suggestedNextAction}`,
             if (cloud.status !== "active") {
               return text(
                 "selected_free_site_not_active",
-                `${handoff.siteUrl} is no longer an active reusable free site. Nothing was changed; call deploy again for a current slot list.`,
+                `${handoff.siteUrl} is no longer an active free site eligible for handoff. Nothing was changed; call deploy again for a current existing-site list.`,
                 { siteUrl: handoff.siteUrl, status: cloud.status },
                 "blocked"
               );
@@ -3529,6 +3738,39 @@ Next action: ${analysis.suggestedNextAction}`,
             );
           }
         }
+        if (existing) {
+          try {
+            if (!handoff) {
+              const resumed = await resumeCredentialRotation(
+                ctx.client,
+                ctx.projectDir,
+                existing,
+                ctx.apiBaseUrl
+              );
+              if (resumed) {
+                existing = resumed.site;
+                credentialSecurity = resumed.status;
+                credentialRotationResumed = true;
+              }
+            }
+            credentialSecurity ??= await ctx.client.getCredentialStatus(
+              existing.siteId,
+              existing.credential
+            );
+          } catch (error) {
+            if (isSakupaError(error) && error.code === "unauthorized") {
+              return text(
+                "credential_mismatch",
+                `The server rejected the credential in .sakupa/site.json for site ${existing.siteId}.
+
+` + siteFileRecoveryGuidance(ctx.projectDir) + "\n\nNothing was deployed and no new site was created.",
+                { siteId: existing.siteId },
+                "blocked"
+              );
+            }
+            throw error;
+          }
+        }
         ensureUploadSizeWithinLimits(manifest, !existing);
         if (!existing) {
           const created = await ctx.client.createSite({
@@ -3657,12 +3899,14 @@ Project directory: ${ctx.projectDir}
 Files uploaded: ${uploaded} (${finalized.totalBytes} bytes)
 ` + (finalized.expiresAt ? `Validity refreshed \u2014 expires at: ${finalized.expiresAt}
 ` : "") + (credentialRelocatedFrom.length > 0 ? `Credential binding relocated from ${credentialRelocatedFrom.join(", ")} to ${ctx.projectDir}/.sakupa; the existing site was preserved.
-` : "") + (handoff ? `Reusable free-site slot transferred to the current project. The cloud site was NOT deleted; its content was replaced. Previous project: ${handoff.sourceProjectDir}. ` + (handoffCleanup?.sourceCredentialRemoved ? "Its matching .sakupa/site.json credential was removed. Do not use that previous project to manage this URL.\n" : handoffCleanup?.sourceRemovalState === "absent" ? "Its .sakupa/site.json credential was already absent. Do not use that previous project to manage this URL.\n" : `Its credential could not be safely removed because the file was ${handoffCleanup?.sourceRemovalState}. Do not use the previous project to manage this URL; run help before touching its .sakupa directory.
-`) : "") + (finalized.mode === "free" ? `
+` : "") + (handoff ? `Site handoff completed. The existing free-site URL and cloud credential stayed the same, the cloud site was NOT deleted, and its content was replaced. Previous project: ${handoff.sourceProjectDir}. ` + (handoffCleanup?.sourceCredentialRemoved ? "Its matching .sakupa/site.json credential was removed. Do not use that previous project to manage this URL.\n" : handoffCleanup?.sourceRemovalState === "absent" ? "Its .sakupa/site.json credential was already absent. Do not use that previous project to manage this URL.\n" : `Its credential could not be safely removed because the file was ${handoffCleanup?.sourceRemovalState}. Do not use the previous project to manage this URL; run help before touching its .sakupa directory.
+`) : "") + (credentialRotationResumed ? "A previously confirmed credential rotation was resumed safely before this deploy; every older credential is revoked.\n" : "") + (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 ? `
 Warnings:
-${JSON.stringify(finalized.warnings, null, 2)}` : ""),
+${JSON.stringify(finalized.warnings, null, 2)}` : "") + (credentialSecurity?.rotationRecommended ? `
+
+Optional security recommendation: this management credential was created at ${credentialSecurity.credentialCreatedAt} and is older than 7 days. The deploy SUCCEEDED and rotation is not required. Ask the user whether they want to rotate; call rotate without confirmed:true to show the exact revocation preview. Never rotate automatically.` : ""),
           {
             siteId: existing.siteId,
             url: finalized.url,
@@ -3673,6 +3917,13 @@ ${JSON.stringify(finalized.warnings, null, 2)}` : ""),
             filesUploaded: uploaded,
             totalBytes: finalized.totalBytes,
             warnings: finalized.warnings,
+            credentialSecurity: credentialSecurity ? {
+              credentialCreatedAt: credentialSecurity.credentialCreatedAt,
+              ageSeconds: credentialSecurity.ageSeconds,
+              rotationRecommended: credentialSecurity.rotationRecommended,
+              optional: true,
+              resumedAfterInterruption: credentialRotationResumed
+            } : null,
             ...credentialRelocatedFrom.length > 0 ? { credentialRelocatedFrom } : {},
             ...handoff ? {
               handoff: {
@@ -3685,7 +3936,15 @@ ${JSON.stringify(finalized.warnings, null, 2)}` : ""),
                 sourceRemovalState: handoffCleanup?.sourceRemovalState
               }
             } : {}
-          }
+          },
+          "completed",
+          credentialSecurity?.rotationRecommended ? [
+            {
+              tool: "rotate",
+              allowed: true,
+              reasonCode: "credential_older_than_seven_days_optional_rotation"
+            }
+          ] : []
         );
       } catch (e) {
         return toolError(e);
@@ -3778,7 +4037,7 @@ NO content was uploaded or changed by this call \u2014 to publish new or edited
           {
             siteId: site.siteId,
             plan: args.plan,
-            idempotencyKey: randomUUID3()
+            idempotencyKey: randomUUID5()
           },
           site.credential
         );
@@ -4503,7 +4762,7 @@ function registerBillingTools(server, baseCtx) {
 }
 
 // src/tools/help.ts
-import { join as join8 } from "node:path";
+import { join as join9 } from "node:path";
 import { z as z4 } from "zod";
 var TOOL_TOPICS = [
   "init",
@@ -4511,6 +4770,7 @@ var TOOL_TOPICS = [
   "deploy",
   "refresh",
   "status",
+  "rotate",
   "plans",
   "subscribe",
   "bind",
@@ -4522,12 +4782,43 @@ var TOOL_TOPICS = [
   "report",
   "help"
 ];
-var HELP_TOPICS = ["diagnose", "overview", ...TOOL_TOPICS];
+var HELP_TOPICS = ["diagnose", "overview", "terminology", ...TOOL_TOPICS];
+var HELP_TERMINOLOGY = {
+  freeSiteAllowance: {
+    preferredTerm: "free-site allowance",
+    meaning: "Up to three concurrently active free sites per IP; this is not a deploy-count limit."
+  },
+  siteHandoff: {
+    preferredTerm: "site handoff",
+    meaning: "An existing free site keeps its URL and cloud credential while current project content replaces its online content and the sole local project binding moves here.",
+    credentialValueChanges: false,
+    previousCredentialsRevoked: false
+  },
+  credentialRotation: {
+    preferredTerm: "credential rotation",
+    meaning: "A newly generated management credential becomes authoritative and every previous credential for the site is revoked.",
+    credentialValueChanges: true,
+    previousCredentialsRevoked: true
+  },
+  credentialRelocation: {
+    preferredTerm: "credential-file relocation",
+    meaning: "The same local credential file moves to the authoritative project Root; cloud authority and the credential value do not change.",
+    credentialValueChanges: false,
+    previousCredentialsRevoked: false
+  },
+  siteRecovery: {
+    preferredTerm: "site recovery",
+    meaning: "DNS control restores management of a paid custom-domain site, issues a fresh credential and downloads content; previous credentials are revoked by default unless explicitly preserved.",
+    credentialValueChanges: true,
+    previousCredentialsRevoked: "by_default"
+  }
+};
 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.",
+    parameterNames: [],
     parameters: "No parameters and no path argument.",
     warnings: [
       "Never initialize the IDE installation directory.",
@@ -4539,6 +4830,7 @@ var TOOL_MANUALS = {
     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.",
+    parameterNames: ["outputDir"],
     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."
@@ -4547,19 +4839,32 @@ var TOOL_MANUALS = {
     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.",
+    parameterNames: [
+      "outputDir",
+      "outputDirChangeConfirmed",
+      "sakupaRelocationConfirmed",
+      "spaFallback",
+      "publicConfirmed",
+      "reuseSiteUrl",
+      "reuseConfirmed",
+      "subprojectConfirmed",
+      "lang"
+    ],
     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.",
-      "Three free sites are reusable slots. When full, let the user select a returned URL; call deploy with its exact nextAction to replace content and transfer the local binding.",
+      "Each IP has a three-site free-site allowance. At the count limit, let the user select one returned existing free-site URL; call deploy with its exact nextAction to perform a site handoff.",
       "After handoff, tell the user the previous project is unbound and must not manage that URL."
     ],
-    nextStep: "Call status to verify the cloud result."
+    nextStep: "Call status to verify the cloud result.",
+    terminology: ["freeSiteAllowance", "siteHandoff", "credentialRelocation"]
   },
   refresh: {
     purpose: "Extend a free site lifetime without uploading content.",
     sideEffects: "Updates the site expiry in Sakupa.",
     preconditions: "A valid local site credential.",
+    parameterNames: [],
     parameters: "No parameters.",
     warnings: ["Subscribed sites are permanent and do not need refresh."],
     nextStep: "Call status to verify the new expiry."
@@ -4568,14 +4873,26 @@ var TOOL_MANUALS = {
     purpose: "Read the bound site, deployment, domain and serving state.",
     sideEffects: "Read-only API request.",
     preconditions: "A valid local site credential.",
+    parameterNames: [],
     parameters: "No parameters.",
     warnings: ["Billing truth comes from billing, not inferred status text."],
     nextStep: "Follow only the returned real tool names."
   },
+  rotate: {
+    purpose: "Rotate the current site management credential after explicit confirmation.",
+    sideEffects: "Confirmed rotation revokes every previous credential for this site.",
+    preconditions: "A valid local site credential; preview is required before confirmation.",
+    parameterNames: ["confirmed"],
+    parameters: "confirmed=true only from the exact preview resume arguments.",
+    warnings: ["Rotation is optional and never blocks deploy.", "Never expose credential values."],
+    nextStep: "Use the preview resumeWith arguments only after the user confirms.",
+    terminology: ["credentialRotation"]
+  },
   plans: {
     purpose: "Read the authoritative hosting plan catalog and rules.",
     sideEffects: "Read-only public API request.",
     preconditions: "None; project initialization is not required.",
+    parameterNames: [],
     parameters: "No parameters.",
     warnings: ["JPY prices and cloud plan order are authoritative."],
     nextStep: "Use subscribe for first payment or change for an existing subscription."
@@ -4584,6 +4901,7 @@ var TOOL_MANUALS = {
     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.",
+    parameterNames: ["plan"],
     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."
@@ -4592,6 +4910,7 @@ var TOOL_MANUALS = {
     purpose: "Start, check or inspect custom-domain binding.",
     sideEffects: "May create DNS verification and hostname provisioning state.",
     preconditions: "A subscribed site and DNS control.",
+    parameterNames: ["action", "hostname", "verificationId"],
     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."
@@ -4600,6 +4919,7 @@ var TOOL_MANUALS = {
     purpose: "Read the single authoritative subscription and usage snapshot.",
     sideEffects: "Read-only API reconciliation.",
     preconditions: "A valid bound site.",
+    parameterNames: [],
     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."
@@ -4608,6 +4928,7 @@ var TOOL_MANUALS = {
     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.",
+    parameterNames: ["scope"],
     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."
@@ -4616,17 +4937,26 @@ var TOOL_MANUALS = {
     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.",
+    parameterNames: [
+      "action",
+      "hostname",
+      "verificationId",
+      "outputDir",
+      "preserveExistingCredentials"
+    ],
     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."
+    nextStep: "Call recover download when local credentials already exist.",
+    terminology: ["siteRecovery"]
   },
   change: {
     purpose: "Open the unified Stripe subscription-management page.",
     sideEffects: "Creates a short-lived Portal session and audit record only.",
     preconditions: "An active subscription.",
+    parameterNames: ["operationId"],
     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."
@@ -4635,6 +4965,7 @@ var TOOL_MANUALS = {
     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.",
+    parameterNames: ["category", "subject", "description", "contactEmail"],
     parameters: "Category, subject, sanitized description and optional contact email.",
     warnings: ["Never include credentials, source, card data or secrets."],
     nextStep: "Wait for support follow-up."
@@ -4643,6 +4974,19 @@ var TOOL_MANUALS = {
     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.",
+    parameterNames: [
+      "toolName",
+      "helpAuthorization",
+      "errorCode",
+      "errorMessage",
+      "requestId",
+      "deploymentId",
+      "severity",
+      "description",
+      "agentContext",
+      "contactEmail",
+      "confirmSubmit"
+    ],
     parameters: "Failed tool, helpAuthorization, sanitized diagnostics and explicit confirmSubmit.",
     warnings: [
       "Never report ordinary setup errors help can solve.",
@@ -4654,7 +4998,8 @@ var TOOL_MANUALS = {
     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.",
+    parameterNames: ["topic", "failedTool", "errorCode", "resultCode", "requestId"],
+    parameters: "topic defaults to diagnose; use overview, terminology, or a tool name for its manual.",
     warnings: ["Use help before repeating failed calls or suggesting report."],
     nextStep: "Follow the returned diagnosis and nextActions."
   }
@@ -4676,7 +5021,7 @@ function registerHelpTools(server, baseCtx) {
           throw new Error("init postcondition failed: project marker missing");
         const site = loadSiteFile(ctx.projectDir);
         const recovery = loadRecoveryFile(ctx.projectDir);
-        const sakupaDirectory = join8(ctx.projectDir, ".sakupa");
+        const sakupaDirectory = join9(ctx.projectDir, ".sakupa");
         return structuredToolResult({
           schemaVersion: 1,
           outcome: "completed",
@@ -4703,7 +5048,7 @@ function registerHelpTools(server, baseCtx) {
   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.",
+      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, terminology, or a tool name for complete usage, side effects, parameters and warnings. Only recommend report when help explicitly returns reportRecommended:true.",
       inputSchema: {
         topic: z4.enum(HELP_TOPICS).optional().default("diagnose"),
         failedTool: z4.string().optional(),
@@ -4718,19 +5063,39 @@ function registerHelpTools(server, baseCtx) {
       try {
         if (args.topic === "overview") {
           const catalog = Object.fromEntries(
-            TOOL_TOPICS.map((tool) => [tool, { purpose: TOOL_MANUALS[tool].purpose }])
+            TOOL_TOPICS.map((tool) => [
+              tool,
+              {
+                purpose: TOOL_MANUALS[tool].purpose,
+                parameterNames: TOOL_MANUALS[tool].parameterNames
+              }
+            ])
           );
           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 },
+            summary: 'Sakupa tool overview and parameter names returned. Site handoff keeps the cloud credential value; credential rotation changes it and revokes every prior value. Use help topic:"terminology" for every site/credential distinction. On any failure call help with topic:"diagnose" before retrying, support or report.',
+            data: { tools: catalog, toolOrder: TOOL_TOPICS, terminology: HELP_TERMINOLOGY },
+            nextActions: []
+          });
+        }
+        if (args.topic === "terminology") {
+          return structuredToolResult({
+            schemaVersion: 1,
+            outcome: "completed",
+            resultCode: "help_terminology",
+            summary: "Sakupa terminology returned. Site handoff keeps the credential value; credential rotation changes it and revokes every prior credential; credential-file relocation only moves the same local file; site recovery uses DNS control to issue a fresh credential. The free-site allowance is a concurrent-site count, not a deploy-count limit.",
+            data: { terminology: HELP_TERMINOLOGY },
             nextActions: []
           });
         }
         if (args.topic !== "diagnose") {
           const manual = TOOL_MANUALS[args.topic];
+          const relatedTerminology = Object.fromEntries(
+            (manual.terminology ?? []).map((key) => [key, HELP_TERMINOLOGY[key]])
+          );
+          const terminologyText = Object.values(relatedTerminology).map((term) => `${term.preferredTerm}: ${term.meaning}`).join(" ");
           return structuredToolResult({
             schemaVersion: 1,
             outcome: "completed",
@@ -4740,8 +5105,9 @@ Side effects: ${manual.sideEffects}
 Preconditions: ${manual.preconditions}
 Parameters: ${manual.parameters}
 Warnings: ${manual.warnings.join(" ")}
-Next: ${manual.nextStep}`,
-            data: { tool: args.topic, ...manual },
+Next: ${manual.nextStep}` + (terminologyText.length > 0 ? `
+Terminology: ${terminologyText}` : ""),
+            data: { tool: args.topic, ...manual, relatedTerminology },
             nextActions: []
           });
         }
@@ -4750,12 +5116,26 @@ Next: ${manual.nextStep}`,
         const marker = selected ? loadProjectMarker(selected) : { kind: "absent" };
         const site = selected ? loadSiteFile(selected) : { kind: "absent" };
         let recoveryState = "absent";
+        let credentialRotationState = "absent";
+        let credentialRotationDetails;
         if (selected) {
           try {
             recoveryState = loadRecoveryFile(selected) === null ? "absent" : "ok";
           } catch {
             recoveryState = "corrupted";
           }
+          const rotation = loadCredentialRotation(selected);
+          if (rotation.kind === "ok") {
+            credentialRotationState = "pending";
+            credentialRotationDetails = {
+              siteId: rotation.file.siteId,
+              createdAt: rotation.file.createdAt,
+              apiBaseUrl: rotation.file.apiBaseUrl
+            };
+          } else if (rotation.kind === "corrupted") {
+            credentialRotationState = "corrupted";
+            credentialRotationDetails = { problem: rotation.problem };
+          }
         }
         const opaqueFailure = args.errorCode === "internal" || args.resultCode === "error_internal";
         const reportRecommended = opaqueFailure && (diagnosis.diagnosisCode === "project_bound" || diagnosis.diagnosisCode === "roots_request_failed");
@@ -4772,8 +5152,9 @@ Next: ${manual.nextStep}`,
             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.");
+        ] : credentialRotationState === "pending" ? [{ tool: "rotate", allowed: true, reasonCode: "resume_confirmed_rotation" }] : diagnosis.diagnosisCode === "workspace_not_initialized" ? [{ tool: "init", allowed: true, reasonCode: "initialize_active_root" }] : [];
+        const rotationGuidance = credentialRotationState === "pending" ? "A previously confirmed credential rotation is pending; call rotate with no arguments to resume it. The candidate credential is intentionally hidden." : credentialRotationState === "corrupted" ? "The local credential rotation journal is damaged. Preserve .sakupa/rotation.json, do not print, edit or delete it, and do not retry deploy or rotate until the file is recovered from a trusted backup or Sakupa support confirms the recovery path." : "";
+        const summary = `Help diagnosis: ${diagnosis.diagnosisCode}. ${diagnosis.guidance} MCP version: ${MCP_VERSION}. ${rotationGuidance} ` + (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",
@@ -4785,6 +5166,8 @@ Next: ${manual.nextStep}`,
             projectMarkerState: marker.kind,
             siteState: site.kind,
             recoveryState,
+            credentialRotationState,
+            ...credentialRotationDetails !== void 0 ? { credentialRotationDetails } : {},
             reportRecommended,
             ...helpAuthorization !== void 0 ? { helpAuthorization } : {},
             ...args.failedTool !== void 0 ? { failedTool: args.failedTool } : {},
@@ -4800,6 +5183,128 @@ Next: ${manual.nextStep}`,
   );
 }
 
+// src/tools/credential.ts
+import { z as z5 } from "zod";
+function registerCredentialTools(server, baseCtx) {
+  server.registerTool(
+    "rotate",
+    {
+      description: "Optionally rotate this site management credential. The first call is a read-only preview. Only confirmed:true after explicit user approval installs a locally generated new credential and revokes every previous credential. Rotation is never required to deploy.",
+      inputSchema: {
+        confirmed: z5.boolean().optional().describe(
+          "True only after showing the rotate preview and the user explicitly approves revoking every old credential."
+        )
+      },
+      outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true }
+    },
+    async (args) => {
+      let releaseLock;
+      try {
+        const ctx = await withProjectDir(baseCtx);
+        let site = requireSiteFile(ctx);
+        const pending = loadCredentialRotation(ctx.projectDir);
+        if (pending.kind !== "absent" || args.confirmed === true) {
+          releaseLock = acquireSiteHandoffLock(site.siteId);
+        }
+        if (pending.kind !== "absent") {
+          const resumed = await resumeCredentialRotation(
+            ctx.client,
+            ctx.projectDir,
+            site,
+            ctx.apiBaseUrl
+          );
+          if (!resumed) throw new Error("Credential rotation resume state disappeared.");
+          site = resumed.site;
+          return structuredToolResult({
+            schemaVersion: 1,
+            outcome: "completed",
+            resultCode: "credential_rotation_resumed",
+            summary: `Credential rotation resumed and completed for ${site.url ?? site.siteId}. The new credential is stored only in this project .sakupa/site.json. Every previous credential is revoked; old project folders and backup copies can no longer manage this site. No credential value is shown.`,
+            data: {
+              siteId: site.siteId,
+              credentialCreatedAt: resumed.status.credentialCreatedAt,
+              rotationRecommended: false,
+              previousCredentialsRevoked: true,
+              resumedAfterInterruption: true,
+              credentialStoredLocally: true
+            },
+            nextActions: [{ tool: "status", allowed: true }]
+          });
+        }
+        const status = await ctx.client.getCredentialStatus(site.siteId, site.credential);
+        const confirmation = { confirmed: true };
+        if (args.confirmed !== true) {
+          return structuredToolResult({
+            schemaVersion: 1,
+            outcome: "waiting_user",
+            resultCode: "credential_rotation_confirmation_required",
+            summary: `Nothing was changed. Rotating the management credential for ${site.url ?? site.siteId} will generate a new credential locally, save it as the current credential in this project .sakupa/site.json, and revoke EVERY previous credential for this site\u2014including copies in old folders and backups. Rotation is optional and deploy remains available. Current credential created at: ${status.credentialCreatedAt}. Exact confirm arguments: ${JSON.stringify(confirmation)}. Ask the user for explicit approval; never expose credential values.`,
+            data: {
+              siteId: site.siteId,
+              credentialCreatedAt: status.credentialCreatedAt,
+              credentialAgeSeconds: status.ageSeconds,
+              rotationRecommended: status.rotationRecommended,
+              confirmation,
+              confirmArguments: confirmation,
+              previousCredentialsWillBeRevoked: true,
+              optional: true
+            },
+            userAction: {
+              type: "confirm_in_mcp",
+              provider: "sakupa",
+              expectedOutcome: "Generate one new local credential and revoke every previous credential for this site.",
+              resumeWith: { tool: "rotate", arguments: confirmation }
+            },
+            nextActions: [
+              {
+                tool: "rotate",
+                arguments: confirmation,
+                allowed: true,
+                reasonCode: "explicit_credential_rotation_confirmation"
+              }
+            ]
+          });
+        }
+        writeCredentialRotation(ctx.projectDir, {
+          siteId: site.siteId,
+          candidateCredential: generateCredential(),
+          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          apiBaseUrl: ctx.apiBaseUrl
+        });
+        const completed = await resumeCredentialRotation(
+          ctx.client,
+          ctx.projectDir,
+          site,
+          ctx.apiBaseUrl
+        );
+        if (!completed) throw new Error("Credential rotation did not produce resumable state.");
+        site = completed.site;
+        return structuredToolResult({
+          schemaVersion: 1,
+          outcome: "completed",
+          resultCode: "credential_rotated",
+          summary: `Management credential rotated for ${site.url ?? site.siteId}. The new credential is stored only in this project .sakupa/site.json. Every previous credential is revoked; old project folders and backup copies can no longer manage this site. No credential value is shown.`,
+          data: {
+            siteId: site.siteId,
+            credentialCreatedAt: completed.status.credentialCreatedAt,
+            rotationRecommended: false,
+            previousCredentialsRevoked: true,
+            revokedPreviousCredentials: completed.rotation?.revokedPreviousCredentials ?? null,
+            resumedAfterInterruption: false,
+            credentialStoredLocally: true
+          },
+          nextActions: [{ tool: "status", allowed: true }]
+        });
+      } catch (error) {
+        return toolError(error);
+      } finally {
+        releaseLock?.();
+      }
+    }
+  );
+}
+
 // src/transport.ts
 var FetchTransport = class {
   baseUrl;
@@ -4909,7 +5414,9 @@ Workflow:
    site (public URL ${hostPattern}, valid 24 hours, free banner shown) and stores the
    management credential in .sakupa/site.json. Deploying again updates the site and refreshes
    its validity; refresh extends validity without uploading; status shows the
-   current deployment and serving state at any time.
+   current deployment and serving state at any time. Every update checks the credential's
+   server-side issue time. When it is older than 7 days, deploy succeeds and only SUGGESTS the
+   optional rotate tool; never rotate without the user's explicit confirmation.
 3. To make the site PERMANENT, subscribe it to a monthly hosting plan (plans
    shows the catalog; subscribe -> Stripe-hosted checkout;
    water/personal/share/business). Paying makes the
@@ -4957,12 +5464,13 @@ On any difficulty, call help before retrying or escalating. Only offer report wh
 reportRecommended:true; attach your own factual account via agentContext and show the exact
 sanitized preview before asking the user to confirm submission.
 
-The three free sites created by one IP are REUSABLE SLOTS, not disposable quota. When all three are
-occupied, deploy returns existing free URLs. Ask the user which URL may have its online content
-REPLACED, then call deploy with the exact returned arguments. The cloud site is never deleted:
-deploy transfers its sole local binding to the current project after a successful update and removes
-the matching credential from the previous project. Tell the user not to manage that URL from the
-previous project. NEVER switch workspaces, ask the user to run CLI, or recommend another host.
+Each IP has a FREE-SITE ALLOWANCE of three concurrently active free sites; this is not a deploy-count
+limit. When the count limit is reached, deploy returns existing free URLs. Ask the user which URL may
+have its online content REPLACED, then call deploy with the exact returned arguments to perform a SITE
+HANDOFF. The URL and cloud credential stay the same; the cloud site is never deleted. After a
+successful update, deploy moves its sole local binding to the current project and removes the matching
+credential file from the previous project. Tell the user not to manage that URL from the previous
+project. NEVER switch workspaces, ask the user to run CLI, or recommend another host.
 
 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
@@ -4977,6 +5485,9 @@ Safety boundaries:
 - Never repeat, echo, or memorize the credential value from .sakupa/site.json \u2014 quoting it
   into the conversation copies the site's only key outside the protected local file. Read it
   only through the tools.
+- rotate always previews first. confirmed:true revokes EVERY prior credential, including old
+  folders and backups. Show that consequence and obtain explicit user approval; rotation is
+  optional and never a condition for deploy.
 - Before deploying, if the entry HTML lacks a lang attribute, add one matching the content
   language (infer it from the content) and then deploy; only skip when the user explicitly
   wants no lang attribute.
@@ -5020,6 +5531,7 @@ function createSakupaMcpServer(opts) {
   };
   registerTools(server, ctx);
   registerBillingTools(server, ctx);
+  registerCredentialTools(server, ctx);
   registerHelpTools(server, ctx);
   return server;
 }