@sakupa/mcp 1.2.0 → 1.3.0

package/dist/bin.js

@@ -402,7 +402,7 @@ function isFreeSiteAllowanceNetworkReference(value) {
 }
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "1.2.0";
+var SAKUPA_MCP_VERSION = "1.3.0";
 
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
@@ -770,8 +770,10 @@ function environmentFor(apiBaseUrl) {
 import {
   CLIENT_CAPABILITIES_META_KEY,
   McpServer,
+  createRequestStateCodec,
   inputResponse
 } from "@modelcontextprotocol/server";
+import { randomBytes as randomBytes2 } from "node:crypto";
 
 // src/api-client.ts
 var KNOWN_ERROR_CODES = /* @__PURE__ */ new Set([
@@ -3411,10 +3413,51 @@ function structuredToolResult(envelope) {
   return {
     content: [{ type: "text", text: `${envelope.summary}
 
+---
 ${presentationFallback}` }],
     structuredContent: structuredEnvelope
   };
 }
+var SUMMARY_HEADINGS = {
+  steps: "Do this yourself",
+  notes: "Notes",
+  next: "Next"
+};
+function tableCell(value) {
+  return String(value).replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+function summaryMarkdown(sections) {
+  const blocks = [`## ${sections.title.trim()}`];
+  if (sections.lead?.trim()) blocks.push(sections.lead.trim());
+  const facts = (sections.facts ?? []).filter(
+    (row) => row[1] !== void 0 && row[1] !== ""
+  );
+  if (facts.length > 0) {
+    blocks.push(
+      [
+        "| Item | Value |",
+        "|---|---|",
+        ...facts.map(([k, v]) => `| ${tableCell(k)} | ${tableCell(v)} |`)
+      ].join("\n")
+    );
+  }
+  if (sections.steps?.length) {
+    blocks.push(
+      `### ${SUMMARY_HEADINGS.steps}
+${sections.steps.map((step, i) => `${i + 1}. ${step}`).join("\n")}`
+    );
+  }
+  if (sections.notes?.length) {
+    blocks.push(`### ${SUMMARY_HEADINGS.notes}
+${sections.notes.map((n) => `- ${n}`).join("\n")}`);
+  }
+  if (sections.next?.length) {
+    blocks.push(`### ${SUMMARY_HEADINGS.next}
+${sections.next.map((n) => `- ${n}`).join("\n")}`);
+  }
+  if (sections.raw?.trim()) blocks.push(sections.raw.trim());
+  return blocks.join("\n\n");
+}
 function timestampForAgent(exactTimestamp) {
   return timestampForAgentInZone(exactTimestamp, clientRuntimeTimeZone());
 }
@@ -3608,8 +3651,14 @@ function toolError(e) {
   const serverGuidance = isSakupaError(e) && errorCode !== "internal" && errorCode !== "unauthorized" && errorCode !== "upgrade_required" && e.message.trim().length > 0 ? e.message : void 0;
   const safeSummary = timeoutSummary ?? (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 customerMeaning = timedOut ? timeoutRetrySafe ? "Sakupa did not receive this read result before the deadline; no automatic retry occurred." : "Sakupa did not receive a final result before the deadline, so the AI must check current state before attempting another write." : errorCode === "unauthorized" ? "The cloud site is still intact, but this project no longer has a valid management credential for it." : errorCode === "upgrade_required" ? "The installed Sakupa MCP version is too old for the current API and must be refreshed before retrying." : errorCode === "payment_required" ? "This action needs an active subscription or a payment issue must be resolved first." : errorCode === "rate_limited" ? "Sakupa temporarily refused this operation because a usage or frequency limit was reached." : errorCode === "not_found" ? "The requested Sakupa site, project binding, or operation could not be found." : errorCode === "forbidden" ? "Sakupa refused this operation because the current authority or site state does not allow it." : errorCode === "conflict" || errorCode === "state_conflict" || errorCode === "confirmation_required" ? "Sakupa safely stopped because the site, billing state, or required confirmation no longer matches." : errorCode === "invalid_request" || errorCode === "validation_failed" ? "Sakupa could not complete the operation because required input or current state was invalid." : retryable ? "A temporary Sakupa dependency problem prevented completion." : "Sakupa did not complete the operation; use the retained diagnostics to determine the safe next step.";
-  const userFacingSummary = `Customer meaning: ${customerMeaning}
-Technical context for the AI: ${safeSummary}`;
+  const userFacingSummary = summaryMarkdown({
+    title: `Sakupa could not complete this operation (${errorCode})`,
+    lead: `Customer meaning: ${customerMeaning}`,
+    notes: [`Technical context for the AI: ${safeSummary}`],
+    next: [
+      '`help` with topic "diagnose", the failed tool name and this error code \u2014 before any retry, support request or report'
+    ]
+  });
   const result = structuredToolResult({
     schemaVersion: 1,
     outcome: "failed",
@@ -3638,6 +3687,7 @@ Technical context for the AI: ${safeSummary}`;
 }
 
 // src/tools/decision.ts
+import { acceptedContent, inputRequired as inputRequired2 } from "@modelcontextprotocol/server";
 var DECISION_PRESENTATION_POLICY = {
   translateFields: [
     "decision.prompt",
@@ -3730,11 +3780,14 @@ function buildDecisionContract(prompt, options) {
 function formatDecisionFallback(decision) {
   const options = decision.options.map((option, index) => {
     const consequences = option.consequences.length === 0 ? "" : `
-   Consequences: ${option.consequences.join(" ")}`;
+   - Consequences: ${option.consequences.join(" ")}`;
     let exactAction;
     switch (option.nextAction.type) {
       case "call_tool":
-        exactAction = `If the user selects this option, call ${option.nextAction.tool} with these exact arguments: ${JSON.stringify(option.nextAction.arguments)}.`;
+        exactAction = `If the user selects this option, call \`${option.nextAction.tool}\` with these exact arguments:
+   \`\`\`json
+   ${JSON.stringify(option.nextAction.arguments)}
+   \`\`\``;
         break;
       case "open_url":
         exactAction = `If the user selects this option, present this exact URL: ${option.nextAction.url}.`;
@@ -3743,11 +3796,13 @@ function formatDecisionFallback(decision) {
         exactAction = "If the user selects this option, call no tool and make no change.";
         break;
     }
-    return `${index + 1}. [${option.id}] ${option.label}
+    return `${index + 1}. [${option.id}] **${option.label}**
    ${option.description}${consequences}
    ${exactAction}`;
   });
-  return `USER DECISION REQUIRED: ${decision.prompt}
+  return `### USER DECISION REQUIRED
+${decision.prompt}
+
 No option is selected by default. Present every option to the user, do not choose on their behalf, and never reconstruct or guess tool arguments.
 
 ` + options.join("\n\n");
@@ -3827,6 +3882,76 @@ function noActionDecisionOption(input) {
     nextAction: { type: "none" }
   };
 }
+var DECISION_INPUT_KEY = "decision";
+var declinedCalls = /* @__PURE__ */ new WeakSet();
+function formatElicitationMessage(decision) {
+  const lines = decision.options.map((option, index) => {
+    const consequences = option.consequences.length === 0 ? "" : ` Consequences: ${option.consequences.join(" ")}`;
+    return `${index + 1}. ${option.label} \u2014 ${option.description}${consequences}`;
+  });
+  return `${decision.prompt}
+
+${lines.join("\n")}`;
+}
+function presentDecision(runtime, call, tool, input) {
+  const decision = buildDecisionContract(input.prompt, input.options);
+  if (!runtime || !call || declinedCalls.has(call) || !runtime.supportsFormElicitation(call)) {
+    return Promise.resolve(decisionToolResult(input));
+  }
+  const args = {};
+  for (const option of decision.options) {
+    if (option.nextAction.type === "call_tool" && option.nextAction.tool === tool) {
+      args[option.id] = option.nextAction.arguments;
+    }
+  }
+  if (Object.keys(args).length === 0) return Promise.resolve(decisionToolResult(input));
+  return runtime.codec.mint({ v: 1, tool, decisionId: input.resultCode, arguments: args }, call).then(
+    (requestState) => inputRequired2({
+      requestState,
+      inputRequests: {
+        [DECISION_INPUT_KEY]: inputRequired2.elicit({
+          message: formatElicitationMessage(decision),
+          requestedSchema: {
+            type: "object",
+            properties: {
+              choice: {
+                type: "string",
+                title: "Your choice",
+                description: decision.prompt,
+                oneOf: decision.options.map((option) => ({
+                  const: option.id,
+                  title: option.label
+                }))
+              }
+            },
+            required: ["choice"]
+          }
+        })
+      }
+    })
+  );
+}
+function restoreDecisionChoice(call, tool) {
+  const responses = call?.mcpReq.inputResponses;
+  if (!call || !responses || !(DECISION_INPUT_KEY in responses)) return null;
+  const state = call.mcpReq.requestState();
+  if (!state || typeof state !== "object" || state.v !== 1 || state.tool !== tool) return null;
+  const content = acceptedContent(responses, DECISION_INPUT_KEY);
+  const choice = typeof content?.choice === "string" ? content.choice : void 0;
+  const args = choice !== void 0 ? state.arguments[choice] : void 0;
+  if (!args) {
+    declinedCalls.add(call);
+    return { kind: "declined" };
+  }
+  return { kind: "chosen", optionId: choice, arguments: args };
+}
+function withDecisionReentry(tool, handler) {
+  return (args, call) => {
+    const restored = restoreDecisionChoice(call, tool);
+    if (restored?.kind === "chosen") return handler({ ...args, ...restored.arguments }, call);
+    return handler(args, call);
+  };
+}
 
 // src/tools/definitions.ts
 function text(resultCode, t, data = {}, outcome = "completed", nextActions = []) {
@@ -3839,9 +3964,14 @@ function text(resultCode, t, data = {}, outcome = "completed", nextActions = [])
     nextActions
   });
 }
-function textJson(resultCode, header, obj, outcome = "completed") {
-  const summary = `${header}
-${JSON.stringify(obj, null, 2)}`;
+function textJson(resultCode, title, lead, obj, outcome = "completed") {
+  const summary = summaryMarkdown({
+    title,
+    lead,
+    raw: `\`\`\`json
+${JSON.stringify(obj, null, 2)}
+\`\`\``
+  });
   return structuredToolResult({
     schemaVersion: 1,
     outcome,
@@ -3884,7 +4014,8 @@ function analysisSummary(analysis) {
 function notDeployableResult(analysis) {
   return textJson(
     "site_analysis_not_deployable",
-    `This project is NOT deployable as-is. No files were uploaded and no API call was made.
+    "This project is NOT deployable as-is",
+    `No files were uploaded and no API call was made.
 Next action: ${analysis.suggestedNextAction}
 Analysis:`,
     analysisSummary(analysis),
@@ -3975,14 +4106,22 @@ ${block}`, checklist: toDnsChecklist(diag.checks) };
     };
   }
 }
-function freeSiteCreationBarrier(sites, deployArguments, allowanceNetworkReference) {
-  const networkReferenceText = allowanceNetworkReference ? `
+function freeSiteCreationBarrier(decisions, call, sites, deployArguments, allowanceNetworkReference) {
+  const summary = summaryMarkdown({
+    title: "Free-site allowance is full \u2014 choose a site to hand off",
+    lead: `Sakupa cloud confirmed that this network already has ${FREE_ACTIVE_SITES_PER_IP} active free sites, so no new site was created. Authenticated device discovery found ${sites.length} free site(s) this device can hand off:
 
-Cloud-observed allowance network reference: ${allowanceNetworkReference}. This diagnostic reference came from the rejected deployment request; it is not the administrator process's public IP and does not grant site ownership.` : "";
-  const summary = `Sakupa cloud confirmed that this network already has ${FREE_ACTIVE_SITES_PER_IP} active free sites, so no new site was created. Authenticated device discovery found ${sites.length} free site(s) this device can hand off.
-
-` + sites.map((site) => `- ${site.url} (expires ${timestampForAgent(site.expiresAt)})`).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, overwrites its online content with the current files, issues a fresh project credential, and revokes every previous credential. The cloud site is NOT deleted. No prior project directory, browser history, workspace switch, or user-run command is required. YOU then call deploy with the exact nextAction arguments. Never ask the user to locate an old directory or run a CLI, and never recommend another hosting provider." + networkReferenceText;
-  return decisionToolResult({
+` + sites.map((site) => `- ${site.url} (expires ${timestampForAgent(site.expiresAt)})`).join("\n"),
+    notes: [
+      "The 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, overwrites its online content with the current files, issues a fresh project credential, and revokes every previous credential. The cloud site is NOT deleted.",
+      "No prior project directory, browser history, workspace switch, or user-run command is required. YOU then call deploy with the exact nextAction arguments. Never ask the user to locate an old directory or run a CLI, and never recommend another hosting provider.",
+      ...allowanceNetworkReference ? [
+        `Cloud-observed allowance network reference: ${allowanceNetworkReference}. This diagnostic reference came from the rejected deployment request; it is not the administrator process's public IP and does not grant site ownership.`
+      ] : []
+    ]
+  });
+  return presentDecision(decisions, call, "deploy", {
     resultCode: "free_site_slot_selection_required",
     summary,
     data: {
@@ -4088,6 +4227,7 @@ function registerTools(server, baseCtx) {
   server.registerTool(
     "analyze",
     {
+      title: "Analyze project",
       description: "Analyze the local project and decide whether it can be deployed as a static site. Detects the framework, the built static output directory (dist/build/out/...), missing index.html, SSR/API-route/database-runtime risks, SPA fallback needs, forbidden files (secrets, .env, archives, media) and size limits. Sakupa deploys ONLY prebuilt static output \u2014 never source, secrets or server code. Run this before deploy.",
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
@@ -4103,8 +4243,8 @@ function registerTools(server, baseCtx) {
         });
         return textJson(
           "site_analysis_completed",
-          `Analysis of ${ctx.projectDir}
-Next action: ${analysis.suggestedNextAction}`,
+          `Analysis of ${ctx.projectDir}`,
+          `Next action: ${analysis.suggestedNextAction}`,
           analysisSummary(analysis)
         );
       } catch (e) {
@@ -4115,6 +4255,7 @@ Next action: ${analysis.suggestedNextAction}`,
   server.registerTool(
     "deploy",
     {
+      title: "Deploy site",
       description: `Deploy the local static output to Sakupa. First deploy creates a free temporary site (valid ${FREE_SITE_TTL_HOURS}h, public URL like https://${previewHostPattern}) and stores the management credential in .sakupa/site.json. Later runs update the existing site (free sites also refresh their validity; subscription-backed sites have no free-site expiry while the subscription remains active). Runs analyze first and refuses to upload source projects, secrets, .env files, archives, media or server code. The MCP process is locked to the current directory initialized by the no-argument init MCP tool; no tool argument can change that root. outputDir is a separate REQUIRED relative path supplied from the current project inspection. Never uploads anything when analysis says the project is not deployable.`,
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
@@ -4146,7 +4287,7 @@ Next action: ${analysis.suggestedNextAction}`,
         lang: z2.string().optional().describe("Site language override (en | ja | zh-CN); defaults to the html lang.")
       })
     },
-    async (args, call) => {
+    withDecisionReentry("deploy", async (args, call) => {
       let releaseHandoffLock;
       try {
         const ctx = await withProjectDir(baseCtx, call);
@@ -4163,7 +4304,7 @@ Next action: ${analysis.suggestedNextAction}`,
             outputDir: effectiveOutputDir,
             ...confirmation
           };
-          return decisionToolResult({
+          return presentDecision(baseCtx.decisions, call, "deploy", {
             resultCode: "publish_directory_change_confirmation_required",
             summary: `This initialized project last published from "${recordedOutputDir}", but this request selected "${effectiveOutputDir}". Nothing was uploaded and the site was not changed. Show both paths to the user; only after explicit confirmation call deploy again with outputDirChangeConfirmed: true.`,
             data: {
@@ -4246,7 +4387,7 @@ Next action: ${analysis.suggestedNextAction}`,
             if (args.sakupaRelocationConfirmed !== true) {
               const confirmation = { sakupaRelocationConfirmed: true };
               const confirmArguments = { ...args, ...confirmation };
-              return decisionToolResult({
+              return presentDecision(baseCtx.decisions, call, "deploy", {
                 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: {
@@ -4399,7 +4540,7 @@ Next action: ${analysis.suggestedNextAction}`,
         if (!existing && args.reuseSiteUrl === void 0 && args.publicConfirmed !== true) {
           const confirmation = { publicConfirmed: true };
           const confirmArguments = { ...args, ...confirmation };
-          return decisionToolResult({
+          return presentDecision(baseCtx.decisions, call, "deploy", {
             resultCode: "public_deployment_confirmation_required",
             summary: `First deployment creates a public URL that anyone with the link can open. The free preview stays live for ${FREE_SITE_TTL_HOURS} hours. Nothing has been uploaded or made public yet. The exact confirmation field is publicConfirmed: true.`,
             data: {
@@ -4431,7 +4572,7 @@ Next action: ${analysis.suggestedNextAction}`,
             if (args.reuseConfirmed !== true) {
               const confirmation = { reuseConfirmed: true };
               const confirmArguments = { ...args, publicConfirmed: true, ...confirmation };
-              return decisionToolResult({
+              return presentDecision(baseCtx.decisions, call, "deploy", {
                 resultCode: "free_site_reuse_confirmation_required",
                 summary: `Nothing was changed. Reusing ${args.reuseSiteUrl} will replace all online content at that URL with the current project, issue a fresh credential here, and revoke every previous credential automatically. No old directory is needed. Show these consequences and call deploy with reuseConfirmed:true only after the user explicitly selects this URL.`,
                 data: {
@@ -4563,7 +4704,13 @@ Next action: ${analysis.suggestedNextAction}`,
             if (isSakupaError(error) && error.code === "rate_limited") {
               const allowanceNetworkReference = allowanceNetworkReferenceFrom(error);
               if (deviceSites.length > 0) {
-                return freeSiteCreationBarrier(deviceSites, { ...args }, allowanceNetworkReference);
+                return freeSiteCreationBarrier(
+                  baseCtx.decisions,
+                  call,
+                  deviceSites,
+                  { ...args },
+                  allowanceNetworkReference
+                );
               }
               const networkReferenceText = allowanceNetworkReference ? ` Cloud-observed allowance network reference: ${allowanceNetworkReference}. This reference came from the rejected deployment request, not from the administrator process's public IP.` : "";
               return text(
@@ -4605,15 +4752,30 @@ Next action: ${analysis.suggestedNextAction}`,
           });
           return text(
             "site_published",
-            `Site published: ${finalized2.url}
-` + deploymentEnvironmentContext(ctx.apiBaseUrl) + `Project directory: ${ctx.projectDir}
-Files uploaded: ${uploaded2} (${finalized2.totalBytes} bytes)
-` + (finalized2.expiresAt ? `Expiry deadline: ${timestampForAgent(finalized2.expiresAt)}
-` : "") + `
-This is a FREE temporary preview: it stays live for ${FREE_SITE_TTL_HOURS} hours. Deploying again or calling refresh extends the validity; while a subscription remains active, this URL stays live without the free-site expiry. This is conditional on the subscription remaining active: do NOT describe the site as permanent or long-term, and do NOT say the subscription is bound to the site. The management credential was saved to the exact relative path .sakupa/site.json \u2014 preserve this complete path verbatim and never shorten it to site.json. Keep that file: it is the only way to manage this site.
-` + credentialGitReminder(ctx.projectDir) + (finalized2.warnings.length > 0 ? `
-Warnings:
-${JSON.stringify(finalized2.warnings, null, 2)}` : ""),
+            summaryMarkdown({
+              title: `Site published: ${finalized2.url}`,
+              lead: deploymentEnvironmentContext(ctx.apiBaseUrl) + `Project directory: ${ctx.projectDir}`,
+              facts: [
+                ["Public URL", finalized2.url],
+                ["Project directory", ctx.projectDir],
+                ["Files uploaded", `${uploaded2} (${finalized2.totalBytes} bytes)`],
+                [
+                  "Expiry deadline",
+                  finalized2.expiresAt ? timestampForAgent(finalized2.expiresAt) : void 0
+                ],
+                ["Credential path", ".sakupa/site.json"]
+              ],
+              notes: [
+                `This is a FREE temporary preview: it stays live for ${FREE_SITE_TTL_HOURS} hours. Deploying again or calling refresh extends the validity; while a subscription remains active, this URL stays live without the free-site expiry. This is conditional on the subscription remaining active: do NOT describe the site as permanent or long-term, and do NOT say the subscription is bound to the site.`,
+                "The management credential was saved to the exact relative path .sakupa/site.json \u2014 preserve this complete path verbatim and never shorten it to site.json. Keep that file: it is the only way to manage this site.",
+                ...[credentialGitReminder(ctx.projectDir)].filter((line) => line.trim().length > 0)
+              ],
+              next: ["`status`", "`subscribe` to keep the site online beyond the free period"],
+              raw: finalized2.warnings.length > 0 ? `Warnings:
+\`\`\`json
+${JSON.stringify(finalized2.warnings, null, 2)}
+\`\`\`` : void 0
+            }),
             {
               siteId: created.siteId,
               shortId: created.shortId,
@@ -4701,18 +4863,43 @@ ${JSON.stringify(finalized2.warnings, null, 2)}` : ""),
         }
         return text(
           handoffPerformed ? "free_site_slot_reassigned" : "site_updated",
-          `Site updated: ${finalized.url}
-` + deploymentEnvironmentContext(ctx.apiBaseUrl) + `Project directory: ${ctx.projectDir}
-Files uploaded: ${uploaded} (${finalized.totalBytes} bytes)
-` + (finalized.expiresAt ? `Validity refreshed \u2014 expiry deadline: ${timestampForAgent(finalized.expiresAt)}
-` : "") + (credentialRelocatedFrom.length > 0 ? `Credential binding relocated from ${credentialRelocatedFrom.join(", ")} to ${ctx.projectDir}/.sakupa; the existing site was preserved.
-` : "") + (handoffPerformed ? `Site handoff completed from the authenticated device list. The existing free-site URL stayed the same, the cloud site was NOT deleted, and its content was replaced. Sakupa issued a fresh project credential and revoked ${handoffRevokedCredentials} previous credential(s), so no old project can continue managing this URL.` + (handoffCleanup?.sourceCredentialRemoved ? " A matching obsolete local site.json was removed automatically.\n" : "\n") : "") + (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. While a subscription remains active, the site stays live without this free-site expiry.
-` : "\nThis site is subscription-backed and has no free-site expiry while the subscription remains active.\n") + (finalized.warnings.length > 0 ? `
-Warnings:
-${JSON.stringify(finalized.warnings, null, 2)}` : "") + (credentialSecurity?.rotationRecommended ? `
-
-Optional security recommendation: this management credential was created at ${timestampForAgent(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.` : ""),
+          summaryMarkdown({
+            title: `Site updated: ${finalized.url}`,
+            lead: deploymentEnvironmentContext(ctx.apiBaseUrl) + `Project directory: ${ctx.projectDir}`,
+            facts: [
+              ["Public URL", finalized.url],
+              ["Project directory", ctx.projectDir],
+              ["Files uploaded", `${uploaded} (${finalized.totalBytes} bytes)`],
+              ["Mode", finalized.mode],
+              [
+                "Validity refreshed \u2014 expiry deadline",
+                finalized.expiresAt ? timestampForAgent(finalized.expiresAt) : void 0
+              ]
+            ],
+            notes: [
+              ...credentialRelocatedFrom.length > 0 ? [
+                `Credential binding relocated from ${credentialRelocatedFrom.join(", ")} to ${ctx.projectDir}/.sakupa; the existing site was preserved.`
+              ] : [],
+              ...handoffPerformed ? [
+                `Site handoff completed from the authenticated device list. The existing free-site URL stayed the same, the cloud site was NOT deleted, and its content was replaced. Sakupa issued a fresh project credential and revoked ${handoffRevokedCredentials} previous credential(s), so no old project can continue managing this URL.` + (handoffCleanup?.sourceCredentialRemoved ? " A matching obsolete local site.json was removed automatically." : "")
+              ] : [],
+              ...credentialRotationResumed ? [
+                "A previously confirmed credential rotation was resumed safely before this deploy; every older credential is revoked."
+              ] : [],
+              finalized.mode === "free" ? `Reminder: free sites stay live for ${FREE_SITE_TTL_HOURS} hours after the last deploy or refresh call. While a subscription remains active, the site stays live without this free-site expiry.` : "This site is subscription-backed and has no free-site expiry while the subscription remains active.",
+              ...credentialSecurity?.rotationRecommended ? [
+                `Optional security recommendation: this management credential was created at ${timestampForAgent(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.`
+              ] : []
+            ],
+            next: [
+              "`status`",
+              ...credentialSecurity?.rotationRecommended ? ["`rotate` (optional, preview first) if the user wants a fresh credential"] : []
+            ],
+            raw: finalized.warnings.length > 0 ? `Warnings:
+\`\`\`json
+${JSON.stringify(finalized.warnings, null, 2)}
+\`\`\`` : void 0
+          }),
           {
             siteId: existing.siteId,
             url: finalized.url,
@@ -4766,11 +4953,12 @@ Optional security recommendation: this management credential was created at ${ti
       } finally {
         releaseHandoffLock?.();
       }
-    }
+    })
   );
   server.registerTool(
     "refresh",
     {
+      title: "Refresh free site",
       description: "Refresh the validity of the free temporary site WITHOUT uploading content. Uses the local credential in .sakupa/site.json. Subscription-backed sites have no free-site expiry while the subscription remains active and need no refresh.",
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
@@ -4792,8 +4980,18 @@ Optional security recommendation: this management credential was created at ${ti
         }
         return text(
           "site_refreshed",
-          `Site validity refreshed (project: ${ctx.projectDir}). New expiry: ${timestampForAgent(res.expiresAt)}
-NO content was uploaded or changed by this call \u2014 to publish new or edited files, run deploy. Free sites stay live for ${FREE_SITE_TTL_HOURS} hours after each deploy or refresh.`,
+          summaryMarkdown({
+            title: "Site validity refreshed",
+            facts: [
+              ["Project directory", ctx.projectDir],
+              ["New expiry", timestampForAgent(res.expiresAt)]
+            ],
+            notes: [
+              "NO content was uploaded or changed by this call \u2014 to publish new or edited files, run deploy.",
+              `Free sites stay live for ${FREE_SITE_TTL_HOURS} hours after each deploy or refresh.`
+            ],
+            next: ["`status`", "`deploy` to publish changed files"]
+          }),
           { siteId: site.siteId, expiresAt: res.expiresAt, projectDir: ctx.projectDir }
         );
       } catch (e) {
@@ -4804,6 +5002,7 @@ NO content was uploaded or changed by this call \u2014 to publish new or edited
   server.registerTool(
     "status",
     {
+      title: "Site status",
       description: "Show the current status of this project's Sakupa site: URL, mode (free/paid), expiry, custom domains, size, last deployment and warnings. For a paid site this tool also automatically returns the complete authoritative billing snapshot; users never need to know or name a separate billing tool to get accurate subscription information.",
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
@@ -4819,7 +5018,12 @@ NO content was uploaded or changed by this call \u2014 to publish new or edited
         const binding = res.pendingDomainBinding ? await describePendingBinding(ctx.client, site.credential, res.pendingDomainBinding) : void 0;
         return textJson(
           "status_returned",
-          billing ? `Site status with AUTHORITATIVE BILLING SNAPSHOT. When answering any subscription question, use the nested billing object and report the current plan, scheduled renewal or cancellation, effective time, current entitlement, billing period, usage state and one-time carry when present:${binding?.note ?? ""}` : `Site status:${binding?.note ?? ""}`,
+          billing ? `Site status for ${res.url ?? res.siteId} with AUTHORITATIVE BILLING SNAPSHOT` : `Site status for ${res.url ?? res.siteId}`,
+          [
+            `Mode: ${res.mode} \xB7 Serving: ${res.servingMode} \xB7 Status: ${res.status}` + (res.expiresAt ? ` \xB7 Free expiry: ${timestampForAgent(res.expiresAt)}` : ""),
+            billing ? "When answering any subscription question, use the nested billing object and report the current plan, scheduled renewal or cancellation, effective time, current entitlement, billing period, usage state and one-time carry when present." : "",
+            binding?.note ?? ""
+          ].filter(Boolean).join("\n"),
           {
             ...res,
             projectDir: ctx.projectDir,
@@ -4835,6 +5039,7 @@ NO content was uploaded or changed by this call \u2014 to publish new or edited
   server.registerTool(
     "subscribe",
     {
+      title: "Subscribe (Stripe Checkout)",
       description: `Create a Stripe Checkout link that subscribes THIS site to a Sakupa Hosting monthly plan (${planCatalog()}). While the subscription remains active, its ${previewHostPattern} URL stays live without the free 24-hour expiry. Binding a custom domain afterwards (bind) is an optional included extra and requires DNS control of that domain. Owner-only: requires this project's site credential (.sakupa/site.json) \u2014 deploy first. If the site outgrows its plan, Sakupa shows an over-limit notice and never changes billing automatically. The owner can explicitly choose another plan through Stripe Customer Portal. Card details are entered only on the Stripe-hosted page \u2014 never through the AI tool. Opening and completing Stripe Checkout is the final subscription confirmation.`,
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
@@ -4858,11 +5063,23 @@ NO content was uploaded or changed by this call \u2014 to publish new or edited
         );
         return text(
           "subscription_checkout_ready",
-          `Stripe Checkout link \u2014 Sakupa Hosting for this site: ${res.plan} plan, JPY ${res.monthlyPriceJpy}/month (Japanese yen)
-${res.checkoutUrl}
-
-Open this link in a browser to subscribe. Card data is entered only on the Stripe-hosted page \u2014 never give card numbers, passwords or security codes to the AI tool.
-Once Stripe confirms payment and Sakupa synchronizes the subscription, the current URL stays live while that subscription remains active. Binding a custom domain (bind) is optional and still requires DNS verification.`,
+          summaryMarkdown({
+            title: "Stripe Checkout link \u2014 Sakupa Hosting for this site",
+            lead: `Present this exact URL to the user: ${res.checkoutUrl}`,
+            facts: [
+              ["Plan", `${res.plan} plan, JPY ${res.monthlyPriceJpy}/month (Japanese yen)`],
+              ["Checkout URL", res.checkoutUrl],
+              ["Final confirmation", "Stripe-hosted checkout page"]
+            ],
+            steps: [
+              "Open this link in a browser to subscribe. Card data is entered only on the Stripe-hosted page \u2014 never give card numbers, passwords or security codes to the AI tool."
+            ],
+            notes: [
+              "Once Stripe confirms payment and Sakupa synchronizes the subscription, the current URL stays live while that subscription remains active.",
+              "Binding a custom domain (bind) is optional and still requires DNS verification."
+            ],
+            next: ["`billing` after the user completes checkout"]
+          }),
           {
             siteId: res.siteId,
             plan: res.plan,
@@ -4881,6 +5098,7 @@ Once Stripe confirms payment and Sakupa synchronizes the subscription, the curre
   server.registerTool(
     "bind",
     {
+      title: "Bind custom domain",
       description: `Bind a custom domain to this subscribed site \u2014 an OPTIONAL extra serving surface; the subscription-backed ${previewHostPattern} URL keeps working alongside it while the subscription is active. The binding unit is the APEX domain: binding example.com reserves routes for example.com and www.example.com, but ONLY www is required and judged for activation; the naked apex is optional because many DNS providers cannot point it. One apex TXT verification covers both. A site has one FINAL apex domain; starting a different apex begins a zero-downtime switch and the previous domain remains until the new www is live. The www CNAME must remain while bound. Requires an ACTIVE subscription (subscribe). Ownership is proven ONLY by DNS control of the apex \u2014 payment never grants ownership, and bindings are ALWAYS challengeable: whoever proves CURRENT DNS control takes the domain, even from an existing binding (the displaced site keeps its subscription, content and subscription-backed Sakupa URL). Unverified requests expire after 72 hours. Call again with action "status" to check progress.`,
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
@@ -4915,14 +5133,25 @@ Once Stripe confirms payment and Sakupa synchronizes the subscription, the curre
           const customerRecheckInstruction = `The customer cannot know whether the certificate is ready. Never use conditional readiness wording or ask the customer to decide the provider state. Tell the customer: "You do not need to judge readiness. After about one minute, reply: check domain status. I will check it once." The AI, not the customer, calls bind status exactly once. During this zero-downtime transition, the previously active domain may still serve. Once this binding becomes active, Sakupa retains only the last bound domain unit: ${apex2} and www.${apex2}.`;
           return text(
             res2.bindingStatus === "active" ? "domain_binding_active" : res2.bindingStatus === "provisioning" ? "domain_binding_provisioning" : "domain_verification_pending",
-            `Domain binding status for ${apex2}: ${res2.status}
-${res2.message}
-The serving CNAME www.${apex2} \u2192 ${res2.servingTarget} must remain for as long as this domain is bound.` + (manualProviderRecheckRequired ? `
-
-${customerRecheckInstruction}` : "") + "\n\n" + renderChecklistBlock(
-              diag,
-              "Fix any [MISSING]/[FIX] lines above, then re-run bind status; if still failing after the attempts below, show the user this checklist."
-            ),
+            summaryMarkdown({
+              title: `Domain binding status for ${apex2}: ${res2.status}`,
+              lead: res2.message,
+              facts: [
+                ["Ownership verification", res2.status],
+                ["Binding status", res2.bindingStatus],
+                ["Provisioning phase", res2.provisioningPhase],
+                ["Required serving record", `www.${apex2} CNAME \u2192 ${res2.servingTarget}`],
+                ["Live for the customer", res2.bindingStatus === "active" ? "yes" : "not yet"]
+              ],
+              notes: [
+                `The serving CNAME www.${apex2} \u2192 ${res2.servingTarget} must remain for as long as this domain is bound.`,
+                ...manualProviderRecheckRequired ? [customerRecheckInstruction] : []
+              ],
+              raw: renderChecklistBlock(
+                diag,
+                "Fix any [MISSING]/[FIX] lines above, then re-run bind status; if still failing after the attempts below, show the user this checklist."
+              )
+            }),
             {
               verificationId: res2.verificationId,
               status: res2.status,
@@ -4977,17 +5206,28 @@ ${customerRecheckInstruction}` : "") + "\n\n" + renderChecklistBlock(
 ` : "";
         return text(
           "domain_verification_started",
-          switchNotice + `Domain binding started for ${apex} (routes reserved: ${res.includedHostnames.join(", ")}). Only www.${apex} is required to go live; the naked domain is optional.
-
-This is a STEP-BY-STEP setup \u2014 give the user ONE record at a time so they do not get overwhelmed and give up.
-
-STEP 1 of 2 \u2014 prove ownership. Add ONE record:
-
-  TXT   host: ${txtShort}   value: ${res.verificationRecord.value}
-
-Host is the SHORT form: most panels append the domain automatically (the saved record must NOT show ${apex} twice in one name). Ownership comes ONLY from DNS control; paying never grants it. The first verified request wins and this challenge expires after 72 hours.
-
-When the user says the TXT is set, run bind "status". It verifies ownership and then hands back STEP 2 \u2014 a SINGLE www CNAME (there are NO certificate TXT records; HTTPS validates automatically over that CNAME). That CNAME must remain for as long as the domain stays bound to Sakupa. Each "status" checks the previous step and, unless something is misconfigured, advances to the next \u2014 so run it whenever the user reports a step done, NOT on a timer. Any later session can resume with action "status" alone; the verificationId is optional.`,
+          summaryMarkdown({
+            title: `Domain binding started for ${apex}`,
+            lead: switchNotice + `Routes reserved: ${res.includedHostnames.join(", ")}. Only www.${apex} is required to go live; the naked domain is optional. This is a STEP-BY-STEP setup \u2014 give the user ONE record at a time so they do not get overwhelmed and give up.`,
+            facts: [
+              ["STEP 1 of 2 \u2014 record type", "TXT"],
+              ["TXT host (short form)", txtShort],
+              ["TXT value", res.verificationRecord.value],
+              ["Full record name", res.verificationRecord.name],
+              ["Challenge expires", "after 72 hours"]
+            ],
+            steps: [
+              `STEP 1 of 2 \u2014 prove ownership. Add ONE record: TXT   host: ${txtShort}   value: ${res.verificationRecord.value}`,
+              'Tell the AI when the TXT record is set; it then runs bind "status", which verifies ownership and hands back STEP 2 \u2014 a SINGLE www CNAME.'
+            ],
+            notes: [
+              `Host is the SHORT form: most panels append the domain automatically (the saved record must NOT show ${apex} twice in one name).`,
+              "Ownership comes ONLY from DNS control; paying never grants it. The first verified request wins.",
+              "There are NO certificate TXT records; HTTPS validates automatically over the www CNAME. That CNAME must remain for as long as the domain stays bound to Sakupa.",
+              'Each "status" checks the previous step and, unless something is misconfigured, advances to the next \u2014 so run it whenever the user reports a step done, NOT on a timer. Any later session can resume with action "status" alone; the verificationId is optional.'
+            ],
+            next: ['`bind` with action "status" after the user reports the TXT record is set']
+          }),
           {
             verificationId: res.verificationId,
             apexDomain: apex,
@@ -5020,6 +5260,7 @@ When the user says the TXT is set, run bind "status". It verifies ownership and
   server.registerTool(
     "billing",
     {
+      title: "Billing snapshot",
       description: "Return the sole authoritative source for this site's hosting subscription: current plan, next renewal plan or cancellation, effective time, payment state, current paid entitlement, reconciled paid usage or current free-site fair-use telemetry, estimated usage tier, bound custom domains and risks. Owner-only (uses the credential in .sakupa/site.json).",
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
@@ -5053,9 +5294,14 @@ When the user says the TXT is set, run bind "status". It verifies ownership and
           res.boundHostnames.length > 0 ? `Bound custom domains: ${res.boundHostnames.join(", ")}` : void 0,
           res.risks.pastDue ? "ATTENTION: renewal payment failing \u2014 update the payment method (portal). Serving continues while Stripe retries; if Stripe gives up, the site reverts to free." : void 0
         ].filter((l) => l !== void 0);
-        return textJson("billing_returned", `${lines.join("\n")}
+        return textJson(
+          "billing_returned",
+          `AUTHORITATIVE BILLING SNAPSHOT for site ${res.siteId} (mode: ${res.mode})`,
+          `${lines.slice(1).map((line) => `- ${line}`).join("\n")}
 
-Full status:`, res);
+Full status:`,
+          res
+        );
       } catch (e) {
         return toolError(e);
       }
@@ -5064,6 +5310,7 @@ Full status:`, res);
   server.registerTool(
     "portal",
     {
+      title: "Billing portal (Stripe)",
       description: "Open the Stripe-hosted billing portal for this site: update the payment method, view invoices, or cancel the subscription. All billing operations happen on the Stripe-hosted page \u2014 never inside the AI tool. With .sakupa/site.json, this opens the site-specific portal. Without the local credential, this returns Stripe's public no-code Customer Portal login page. The customer enters the checkout email and confirms a one-time passcode sent by Stripe. This never restores Sakupa site authority.",
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
@@ -5081,7 +5328,12 @@ Full status:`, res);
             schemaVersion: 1,
             outcome: "waiting_user",
             resultCode: "site_billing_portal_ready",
-            summary: `Short-lived Stripe customer portal link created for this site: ${res2.portalUrl}. Any change still happens only on the Stripe-hosted page.`,
+            summary: summaryMarkdown({
+              title: "Stripe customer portal link ready",
+              lead: `Short-lived Stripe customer portal link created for this site: ${res2.portalUrl}`,
+              notes: ["Any change still happens only on the Stripe-hosted page."],
+              next: ["`billing` after the user finishes on Stripe"]
+            }),
             data: { scope: args.scope, portalUrl: res2.portalUrl },
             userAction: {
               type: "open_url",
@@ -5097,7 +5349,14 @@ Full status:`, res);
           schemaVersion: 1,
           outcome: "waiting_user",
           resultCode: "public_billing_recovery_portal_ready",
-          summary: `Stripe public email-OTP login page: ${res.portalUrl}. It uses a one-time passcode, does not recover the Sakupa key, and grants no site authority; when one email has several Customers, Stripe may open only the most recently created usable record.`,
+          summary: summaryMarkdown({
+            title: "Stripe public billing login page",
+            lead: `Stripe public email-OTP login page: ${res.portalUrl}`,
+            notes: [
+              "It uses a one-time passcode, does not recover the Sakupa key, and grants no site authority.",
+              "When one email has several Customers, Stripe may open only the most recently created usable record."
+            ]
+          }),
           data: {
             scope: args.scope,
             portalUrl: res.portalUrl,
@@ -5120,6 +5379,7 @@ Full status:`, res);
   server.registerTool(
     "recover",
     {
+      title: "Recover site",
       description: "Recover management control of a subscribed site WITH A BOUND CUSTOM DOMAIN after losing the local project, by proving DNS control of the apex domain. Sites without a bound domain are identified solely by their local credential and cannot be recovered. By default, completing recovery REVOKES all previous local credentials. Recovery is resumable: start stores local pending state; complete installs and writes the new .sakupa/site.json credential BEFORE requesting content; download uses that credential to reissue an archive and safely extract it into the explicitly selected outputDir without repeating DNS.",
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
@@ -5133,7 +5393,7 @@ Full status:`, res);
         preserveExistingCredentials: z2.boolean().optional().describe("Explicitly keep old local credentials working (default: revoke them all).")
       })
     },
-    async (args, call) => {
+    withDecisionReentry("recover", async (args, call) => {
       try {
         const ctx = await withProjectDir(baseCtx, call);
         if ((args.action === "complete" || args.action === "download") && args.outputDir === void 0) {
@@ -5341,7 +5601,7 @@ After the DNS record resolves, re-run recover with verificationId: "${res2.verif
               ...revokeArguments,
               preserveExistingCredentials: true
             };
-            return decisionToolResult({
+            return presentDecision(baseCtx.decisions, call, "recover", {
               resultCode: "domain_recovery_ready",
               summary: "DNS control is verified and recovery is ready to complete. Nothing was completed yet. The user must choose whether previous site credentials remain valid.",
               data: {
@@ -5476,11 +5736,12 @@ Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
       } catch (e) {
         return toolError(e);
       }
-    }
+    })
   );
   server.registerTool(
     "support",
     {
+      title: "Support ticket",
       description: "Create a Sakupa support ticket for billing, payment, refund review, domain verification, deployment, serving or other issues the MCP cannot solve automatically. Do not include secrets, credentials or card data in the description.",
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
@@ -5504,7 +5765,14 @@ Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
         });
         return text(
           "support_ticket_created",
-          `Support ticket created: ${res.ticketId} (status: ${res.status}).`,
+          summaryMarkdown({
+            title: "Support ticket created",
+            facts: [
+              ["Ticket", res.ticketId],
+              ["Status", res.status]
+            ],
+            notes: ["Wait for the Sakupa support follow-up; no further tool call is needed."]
+          }),
           { ticketId: res.ticketId, status: res.status }
         );
       } catch (e) {
@@ -5515,6 +5783,7 @@ Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
   server.registerTool(
     "report",
     {
+      title: "Bug report",
       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 },
@@ -5536,7 +5805,7 @@ Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
         confirmSubmit: z2.boolean().optional().describe("User reviewed the report payload and approved submission.")
       })
     },
-    async (args, call) => {
+    withDecisionReentry("report", async (args, call) => {
       try {
         requireReportAuthorization(baseCtx, args.helpAuthorization, args.toolName);
         const ctx = await optionalProjectContext(baseCtx, call);
@@ -5566,7 +5835,7 @@ Files: ${extracted.fileCount}; bytes: ${extracted.totalBytes}
           const contactNote = args.contactEmail !== void 0 ? "note that their contact email is attached for follow-up. " : "ASK THEM ONCE whether they want to attach a contact email for follow-up (optional \u2014 omit if declined; include it as contactEmail when they do). ";
           const confirmation = { confirmSubmit: true };
           const confirmArguments = { ...args, ...confirmation };
-          return decisionToolResult({
+          return presentDecision(baseCtx.decisions, call, "report", {
             resultCode: "bug_report_preview_ready",
             outcome: "preview",
             summary: `Bug report prepared but NOT submitted. This is the exact payload that would be sent (structured diagnostics only \u2014 no file contents, source code or secrets). Show it to the user, and ${contactNote}Exact payload:
@@ -5608,7 +5877,7 @@ Summary: ${res.sanitizedSummary}`,
       } catch (e) {
         return toolError(e);
       }
-    }
+    })
   );
 }
 
@@ -5618,6 +5887,7 @@ function registerBillingTools(server, baseCtx) {
   server.registerTool(
     "plans",
     {
+      title: "Hosting plan catalog",
       description: "Return the authoritative Sakupa monthly plan catalog, exact limits, prices, catalog version and plan-change billing rules. This is read-only and does not require a site.",
       inputSchema: z3.object({}),
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
@@ -5630,7 +5900,21 @@ function registerBillingTools(server, baseCtx) {
           schemaVersion: 1,
           outcome: "completed",
           resultCode: "billing_catalog_returned",
-          summary: `Returned ${catalog.plans.length} monthly plans; the Stripe-hosted page is the final confirmation surface for payment and plan changes.`,
+          summary: summaryMarkdown({
+            title: `Sakupa monthly plans (catalog ${catalog.catalogVersion})`,
+            lead: `Returned ${catalog.plans.length} monthly plans; the Stripe-hosted page is the final confirmation surface for payment and plan changes. Prices are in JPY (Japanese yen).`,
+            raw: [
+              "| Plan | Rank | JPY / month | Storage (bytes) | Transfer (bytes) | Requests |",
+              "|---|---|---|---|---|---|",
+              ...catalog.plans.map(
+                (plan) => `| ${plan.id} | ${plan.rank} | ${plan.monthlyPriceJpy} | ${plan.limits.storageBytes} | ${plan.limits.transferBytes} | ${plan.limits.requests} |`
+              )
+            ].join("\n"),
+            notes: [
+              `Upgrades bill immediately at full price (${catalog.upgradeChargeTiming}); downgrades take effect at ${catalog.downgradeEffectiveTiming}; unused transfer carries once (${catalog.upgradeTransferCarry}).`
+            ],
+            next: ["`subscribe` for a first subscription", "`change` for an existing subscription"]
+          }),
           data: { catalog },
           nextActions: [{ tool: "subscribe", allowed: true }]
         });
@@ -5642,6 +5926,7 @@ function registerBillingTools(server, baseCtx) {
   server.registerTool(
     "change",
     {
+      title: "Change subscription (Stripe)",
       description: "Create one Stripe-hosted subscription-management link. The user chooses the plan or period-end cancellation on Stripe; Sakupa never infers intent from the conversation. Creating the link does not change billing.",
       inputSchema: z3.object({
         operationId: z3.string().min(1)
@@ -5662,7 +5947,25 @@ function registerBillingTools(server, baseCtx) {
           outcome: "waiting_user",
           resultCode: "stripe_subscription_management_required",
           operationId: args.operationId,
-          summary: `Stripe subscription-management link (present this exact URL to the user): ${result.portalUrl}. The subscription has NOT changed yet. Stripe is the authoritative place to choose Water, Personal, Share, Business, or period-end cancellation. After Stripe confirmation, upgrades start a new billing cycle immediately at full price; downgrades and cancellation take effect at the current period end. The authoritative plan order from lowest to highest is Water, Personal, Share, Business; never describe a lower-ranked plan as an upgrade. Query billing after the user finishes.`,
+          summary: summaryMarkdown({
+            title: "Stripe subscription-management link ready",
+            lead: `Stripe subscription-management link (present this exact URL to the user): ${result.portalUrl}`,
+            facts: [
+              ["Subscription changed", "NO \u2014 nothing changes until the user confirms on Stripe"],
+              [
+                "Plan order (lowest \u2192 highest)",
+                Array.isArray(result.planOrder) ? result.planOrder.join(" \u2192 ") : void 0
+              ]
+            ],
+            steps: [
+              "Open the link and choose Water, Personal, Share, Business, or period-end cancellation on the Stripe-hosted page."
+            ],
+            notes: [
+              "After Stripe confirmation, upgrades start a new billing cycle immediately at full price; downgrades and cancellation take effect at the current period end.",
+              "The authoritative plan order from lowest to highest is Water, Personal, Share, Business; never describe a lower-ranked plan as an upgrade."
+            ],
+            next: ["`billing` after the user finishes on Stripe"]
+          }),
           data: { portalUrl: result.portalUrl, result },
           userAction: {
             type: "open_url",
@@ -5933,6 +6236,7 @@ function registerHelpTools(server, baseCtx) {
   server.registerTool(
     "init",
     {
+      title: "Initialize project",
       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. If MCP Roots are unavailable, call help; the AI may then use the no-argument CLI init itself.",
       inputSchema: z4.object({}),
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
@@ -5951,7 +6255,16 @@ function registerHelpTools(server, baseCtx) {
           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.`,
+          summary: summaryMarkdown({
+            title: "Sakupa project initialized",
+            lead: `Initialized and verified at the active workspace Root: ${ctx.projectDir}. No cloud site was created and no charge occurred.`,
+            facts: [
+              ["Project root", ctx.projectDir],
+              [".sakupa directory", sakupaDirectory],
+              ["Binding source", ctx.bindingSource]
+            ],
+            next: ["`analyze`, then `deploy` with the exact relative outputDir"]
+          }),
           data: {
             projectRoot: ctx.projectDir,
             sakupaDirectory,
@@ -5973,6 +6286,7 @@ function registerHelpTools(server, baseCtx) {
   server.registerTool(
     "help",
     {
+      title: "Help and diagnosis",
       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: z4.object({
         topic: z4.enum(HELP_TOPICS).optional().default("diagnose"),
@@ -6000,7 +6314,25 @@ function registerHelpTools(server, baseCtx) {
             schemaVersion: 1,
             outcome: "completed",
             resultCode: "help_overview",
-            summary: `Sakupa tool overview and parameter names returned. Site handoff moves an existing free URL to the current project and replaces its credential as a safety consequence; credential rotation changes the credential in place solely for security. Both revoke prior values. When a result contains decision, present every option, select none by default, and copy only the user's selected option nextAction exactly. Use help topic:"terminology" for every site/credential distinction. On any failure call help with topic:"diagnose" before retrying, support or report.`,
+            summary: summaryMarkdown({
+              title: "Sakupa tool overview",
+              lead: "Sakupa tool overview and parameter names returned.",
+              raw: [
+                "| Tool | Purpose | Parameters |",
+                "|---|---|---|",
+                ...TOOL_TOPICS.map(
+                  (tool) => `| \`${tool}\` | ${TOOL_MANUALS[tool].purpose} | ${TOOL_MANUALS[tool].parameterNames.join(", ") || "\u2014"} |`
+                )
+              ].join("\n"),
+              notes: [
+                "Site handoff moves an existing free URL to the current project and replaces its credential as a safety consequence; credential rotation changes the credential in place solely for security. Both revoke prior values.",
+                "When a result contains decision, present every option, select none by default, and copy only the user's selected option nextAction exactly.",
+                'Use help topic:"terminology" for every site/credential distinction.'
+              ],
+              next: [
+                '`help` with topic:"diagnose" on any failure \u2014 before retrying, support or report'
+              ]
+            }),
             data: {
               tools: catalog,
               toolOrder: TOOL_TOPICS,
@@ -6035,13 +6367,20 @@ function registerHelpTools(server, baseCtx) {
             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}` + (terminologyText.length > 0 ? `
-Terminology: ${terminologyText}` : ""),
+            summary: summaryMarkdown({
+              title: `${args.topic}: ${manual.purpose}`,
+              facts: [
+                ["Side effects", manual.sideEffects],
+                ["Preconditions", manual.preconditions],
+                ["Parameters", manual.parameters],
+                ["Parameter names", manual.parameterNames.join(", ") || "(none)"]
+              ],
+              notes: [
+                ...manual.warnings,
+                ...terminologyText.length > 0 ? [`Terminology: ${terminologyText}`] : []
+              ],
+              next: [manual.nextStep]
+            }),
             data: { tool: args.topic, ...manual, relatedTerminology },
             nextActions: []
           });
@@ -6089,7 +6428,23 @@ Terminology: ${terminologyText}` : ""),
           }
         ] : 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.");
+        const summary = summaryMarkdown({
+          title: `Help diagnosis: ${diagnosis.diagnosisCode}`,
+          lead: diagnosis.guidance,
+          facts: [
+            ["MCP version", MCP_VERSION],
+            ["Project marker", marker.kind],
+            ["Site binding", site.kind],
+            ["Recovery state", recoveryState],
+            ["Credential rotation", credentialRotationState],
+            ["Report recommended", reportRecommended ? "yes (last resort)" : "no"]
+          ],
+          notes: [
+            ...rotationGuidance ? [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."
+          ],
+          next: nextActions.map((action) => `\`${action.tool}\` (${action.reasonCode})`)
+        });
         return structuredToolResult({
           schemaVersion: 1,
           outcome: diagnosis.diagnosisCode === "project_bound" ? "completed" : "blocked",
@@ -6124,6 +6479,7 @@ function registerCredentialTools(server, baseCtx) {
   server.registerTool(
     "rotate",
     {
+      title: "Rotate site credential",
       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: z5.object({
         confirmed: z5.boolean().optional().describe(
@@ -6133,7 +6489,7 @@ function registerCredentialTools(server, baseCtx) {
       outputSchema: STRUCTURED_TOOL_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true }
     },
-    async (args, call) => {
+    withDecisionReentry("rotate", async (args, call) => {
       let releaseLock;
       try {
         const ctx = await withProjectDir(baseCtx, call);
@@ -6155,7 +6511,19 @@ function registerCredentialTools(server, baseCtx) {
             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.`,
+            summary: summaryMarkdown({
+              title: `Credential rotation resumed and completed for ${site.url ?? site.siteId}`,
+              facts: [
+                ["Site", site.url ?? site.siteId],
+                ["New credential stored at", ".sakupa/site.json (this project only)"],
+                ["Previous credentials", "all revoked"]
+              ],
+              notes: [
+                "Every previous credential is revoked; old project folders and backup copies can no longer manage this site.",
+                "No credential value is shown."
+              ],
+              next: ["`status`"]
+            }),
             data: {
               siteId: site.siteId,
               credentialCreatedAt: resumed.status.credentialCreatedAt,
@@ -6170,9 +6538,20 @@ function registerCredentialTools(server, baseCtx) {
         const status = await ctx.client.getCredentialStatus(site.siteId, site.credential);
         const confirmation = { confirmed: true };
         if (args.confirmed !== true) {
-          return decisionToolResult({
+          return presentDecision(baseCtx.decisions, call, "rotate", {
             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: ${timestampForAgent(status.credentialCreatedAt)}. Exact confirm arguments: ${JSON.stringify(confirmation)}. Ask the user for explicit approval; never expose credential values.`,
+            summary: summaryMarkdown({
+              title: `Rotate the management credential for ${site.url ?? site.siteId}? Nothing was changed.`,
+              facts: [
+                ["Current credential created at", timestampForAgent(status.credentialCreatedAt)],
+                ["Rotation", "optional; deploy remains available"],
+                ["Exact confirm arguments", JSON.stringify(confirmation)]
+              ],
+              notes: [
+                "Rotating generates a new credential locally, saves it as the current credential in this project .sakupa/site.json, and revokes EVERY previous credential for this site\u2014including copies in old folders and backups.",
+                "Ask the user for explicit approval; never expose credential values."
+              ]
+            }),
             data: {
               siteId: site.siteId,
               credentialCreatedAt: status.credentialCreatedAt,
@@ -6223,7 +6602,21 @@ function registerCredentialTools(server, baseCtx) {
           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.`,
+          summary: summaryMarkdown({
+            title: `Management credential rotated for ${site.url ?? site.siteId}`,
+            facts: [
+              ["New credential stored at", ".sakupa/site.json (this project only)"],
+              [
+                "Previous credentials revoked",
+                completed.rotation?.revokedPreviousCredentials ?? "all"
+              ]
+            ],
+            notes: [
+              "Every previous credential is revoked; old project folders and backup copies can no longer manage this site.",
+              "No credential value is shown."
+            ],
+            next: ["`status`"]
+          }),
           data: {
             siteId: site.siteId,
             credentialCreatedAt: completed.status.credentialCreatedAt,
@@ -6240,7 +6633,7 @@ function registerCredentialTools(server, baseCtx) {
       } finally {
         releaseLock?.();
       }
-    }
+    })
   );
 }
 
@@ -6520,13 +6913,39 @@ Safety boundaries:
   a bound custom domain, a lost credential is unrecoverable by design. portal then opens
   Stripe's public no-code portal login, where the customer verifies the checkout email with a
   Stripe one-time passcode; it never restores site authority.`;
+var DECISION_ROUND_TIMEOUT_MS = 12e4;
+var DECISION_STATE_TTL_SECONDS = 900;
+function clientSupportsFormElicitation(server, call) {
+  let declared;
+  if (call?.mcpReq.envelope !== void 0) {
+    const envelope = call.mcpReq.envelope;
+    declared = envelope[CLIENT_CAPABILITIES_META_KEY];
+  } else {
+    declared = server.server.getClientCapabilities();
+  }
+  const elicitation = declared?.elicitation;
+  if (!elicitation || typeof elicitation !== "object") return false;
+  if (elicitation.form !== void 0) return true;
+  return elicitation.url === void 0;
+}
 function createSakupaMcpServer(opts) {
   const client = opts.client ?? new HttpApiClient(
     new FetchTransport(opts.apiBaseUrl, { testAccessToken: opts.testAccessToken })
   );
+  const decisionCodec = createRequestStateCodec({
+    key: randomBytes2(32),
+    ttlSeconds: DECISION_STATE_TTL_SECONDS
+  });
   const server = new McpServer(
     { name: "sakupa", version: MCP_VERSION },
-    { instructions: instructionsFor(previewHostPatternFor(opts.apiBaseUrl)) }
+    {
+      instructions: instructionsFor(previewHostPatternFor(opts.apiBaseUrl)),
+      // A native decision prompt must resolve well inside common IDE tool
+      // deadlines; past this the legacy shim fails the round and the tool
+      // falls back to the text decision on the next call.
+      inputRequired: { roundTimeoutMs: DECISION_ROUND_TIMEOUT_MS },
+      requestState: { verify: (state, call) => decisionCodec.verify(state, call) }
+    }
   );
   const processCwd = resolve6(opts.projectDir ?? process.cwd());
   const rootsProvider = opts.rootsProvider ?? ((call) => readClientRoots(server, call));
@@ -6541,7 +6960,11 @@ function createSakupaMcpServer(opts) {
       rootsProvider,
       MCP_ROOTS_TIMEOUT_MS,
       opts.projectRoot
-    )
+    ),
+    decisions: {
+      supportsFormElicitation: (call) => clientSupportsFormElicitation(server, call),
+      codec: decisionCodec
+    }
   };
   registerTools(server, ctx);
   registerBillingTools(server, ctx);