@sakupa/mcp 1.5.1 → 1.6.0

package/dist/bin.js

@@ -12,6 +12,7 @@ import {
   lstatSync,
   mkdirSync,
   readFileSync,
+  readdirSync,
   realpathSync,
   renameSync,
   rmdirSync,
@@ -23,6 +24,8 @@ import { homedir } from "node:os";
 import { isAbsolute, join, parse, relative, resolve, sep } from "node:path";
 var SAKUPA_DIR = ".sakupa";
 var PROJECT_FILE = "project.json";
+var GITIGNORE_FILE = ".gitignore";
+var GITIGNORE_CONTENT = "# Sakupa local state (project marker, site binding, recovery/rotation journals).\n# Managed by @sakupa/mcp \u2014 everything in this directory stays out of version control.\n*\n";
 var PROJECT_SCHEMA_VERSION = 1;
 var ProjectRootError = class extends Error {
   code;
@@ -152,14 +155,33 @@ function updateProjectOutputDir(projectDir, outputDir) {
   writeMarkerAtomically(canonical, marker);
   return marker;
 }
-function deleteProjectMarker(projectDir) {
-  const path = projectMarkerPath(projectDir);
-  if (existsSync(path)) unlinkSync(path);
+function ensureSakupaGitignore(projectDir) {
+  const dir = join(projectDir, SAKUPA_DIR);
+  if (!existsSync(dir)) return;
+  const path = join(dir, GITIGNORE_FILE);
+  if (existsSync(path)) return;
+  try {
+    writeFileSync(path, GITIGNORE_CONTENT, { encoding: "utf8", flag: "wx" });
+  } catch {
+  }
+}
+function pruneSakupaDirectory(projectDir) {
+  const dir = join(projectDir, SAKUPA_DIR);
+  if (!existsSync(dir)) return;
   try {
-    rmdirSync(join(projectDir, SAKUPA_DIR));
+    const entries = readdirSync(dir);
+    if (entries.every((entry) => entry === GITIGNORE_FILE)) {
+      for (const entry of entries) unlinkSync(join(dir, entry));
+      rmdirSync(dir);
+    }
   } catch {
   }
 }
+function deleteProjectMarker(projectDir) {
+  const path = projectMarkerPath(projectDir);
+  if (existsSync(path)) unlinkSync(path);
+  pruneSakupaDirectory(projectDir);
+}
 function canonicalProjectDirectory(path) {
   const canonical = canonicalExistingPath(resolve(path));
   if (!statSync(canonical).isDirectory()) {
@@ -207,6 +229,7 @@ function isSafeRelativeOutput(path) {
 function writeMarkerAtomically(projectDir, marker) {
   const dir = join(projectDir, SAKUPA_DIR);
   mkdirSync(dir, { recursive: true, mode: 448 });
+  ensureSakupaGitignore(projectDir);
   const path = projectMarkerPath(projectDir);
   const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
   try {
@@ -403,7 +426,7 @@ function isFreeSiteAllowanceNetworkReference(value) {
 }
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "1.5.1";
+var SAKUPA_MCP_VERSION = "1.6.0";
 
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
@@ -971,6 +994,13 @@ var HttpApiClient = class {
       { device: { deviceId, credential } }
     );
   }
+  async reissueDeviceFreeSiteCredential(siteId, deviceId, credential) {
+    return this.call(
+      "POST",
+      `/v1/devices/sites/${encodeURIComponent(siteId)}/credential`,
+      { device: { deviceId, credential } }
+    );
+  }
   async createSite(req, _clientIp, device) {
     return this.call("POST", "/v1/sites", { body: req, device });
   }
@@ -1172,9 +1202,9 @@ var HttpApiClient = class {
 };
 
 // src/tools/definitions.ts
-import { randomUUID as randomUUID6 } from "node:crypto";
+import { randomUUID as randomUUID7 } from "node:crypto";
 import { promises as fs2 } from "node:fs";
-import { join as join9, relative as relative3, resolve as resolve5, sep as sep4 } from "node:path";
+import { join as join10, relative as relative3, resolve as resolve5, sep as sep4 } from "node:path";
 import { z as z2 } from "zod";
 
 // src/analyze/analyzer.ts
@@ -1610,33 +1640,126 @@ async function analyzeProject(projectDir, opts = {}) {
 }
 
 // src/project-file.ts
+import {
+  chmodSync as chmodSync3,
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync3,
+  renameSync as renameSync3,
+  rmSync as rmSync2,
+  writeFileSync as writeFileSync3
+} from "node:fs";
+import { randomUUID as randomUUID3 } from "node:crypto";
+import { dirname, join as join4 } from "node:path";
+
+// src/credential-store.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
 import {
   chmodSync as chmodSync2,
   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";
+import { homedir as homedir2 } from "node:os";
+import { join as join3 } from "node:path";
+var REF_PATTERN = /^[0-9a-f-]{36}$/i;
+function credentialStoreDirectory() {
+  const base = process.env["SAKUPA_STATE_DIR"] ?? homedir2();
+  return join3(base, ".sakupa", "credentials");
+}
+function credentialStorePath(ref) {
+  if (!REF_PATTERN.test(ref)) throw new Error("Invalid credential reference.");
+  return join3(credentialStoreDirectory(), `${ref}.json`);
+}
+function newCredentialRef() {
+  return randomUUID2();
+}
+function readStoredCredential(ref) {
+  if (!REF_PATTERN.test(ref)) {
+    return {
+      kind: "corrupted",
+      problem: "the credentialRef does not look like a Sakupa reference"
+    };
+  }
+  const path = credentialStorePath(ref);
+  if (!existsSync2(path)) return { kind: "absent" };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync2(path, "utf8"));
+  } catch (error) {
+    return {
+      kind: "corrupted",
+      problem: `${path} exists but could not be parsed (${error instanceof Error ? error.message : String(error)})`
+    };
+  }
+  if (typeof parsed !== "object" || parsed === null || typeof parsed.credential !== "string") {
+    return { kind: "corrupted", problem: `${path} does not contain a credential` };
+  }
+  if (!CREDENTIAL_PATTERN.test(parsed.credential)) {
+    return {
+      kind: "corrupted",
+      problem: `the credential in ${path} does not match the shape Sakupa issues (sk_ followed by exactly 43 URL-safe base64 characters) \u2014 it looks locally altered or damaged`
+    };
+  }
+  return {
+    kind: "ok",
+    entry: {
+      ref,
+      siteId: typeof parsed.siteId === "string" ? parsed.siteId : "",
+      apiBaseUrl: typeof parsed.apiBaseUrl === "string" ? parsed.apiBaseUrl : "",
+      credential: parsed.credential,
+      createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : ""
+    }
+  };
+}
+function storeCredential(entry) {
+  if (!CREDENTIAL_PATTERN.test(entry.credential)) {
+    throw new Error("Refusing to store a credential that does not match the Sakupa shape.");
+  }
+  const dir = credentialStoreDirectory();
+  mkdirSync2(dir, { recursive: true, mode: 448 });
+  const path = credentialStorePath(entry.ref);
+  const temporary = join3(dir, `.${entry.ref}.${process.pid}.tmp`);
+  writeFileSync2(temporary, `${JSON.stringify(entry, null, 2)}
+`, {
+    encoding: "utf8",
+    mode: 384
+  });
+  try {
+    chmodSync2(temporary, 384);
+  } catch {
+  }
+  try {
+    renameSync2(temporary, path);
+  } catch (error) {
+    rmSync(temporary, { force: true });
+    throw error;
+  }
+}
+function deleteStoredCredential(ref) {
+  if (!REF_PATTERN.test(ref)) return;
+  rmSync(credentialStorePath(ref), { force: true });
+}
+
+// src/project-file.ts
 var SITE_DIR = ".sakupa";
 var SITE_FILE = "site.json";
 var RECOVERY_FILE = "recovery.json";
 function siteFilePath(projectDir) {
-  return join3(projectDir, SITE_DIR, SITE_FILE);
+  return join4(projectDir, SITE_DIR, SITE_FILE);
 }
 function recoveryFilePath(projectDir) {
-  return join3(projectDir, SITE_DIR, RECOVERY_FILE);
+  return join4(projectDir, SITE_DIR, RECOVERY_FILE);
 }
-function loadSiteFile(projectDir) {
+function readSiteFileOnDisk(projectDir) {
   const path = siteFilePath(projectDir);
-  if (!existsSync2(path)) return { kind: "absent" };
+  if (!existsSync3(path)) return { kind: "absent" };
   let raw;
   try {
-    raw = readFileSync2(path, "utf8");
+    raw = readFileSync3(path, "utf8");
   } catch (err2) {
     return {
       kind: "corrupted",
@@ -1652,9 +1775,37 @@ function loadSiteFile(projectDir) {
   if (typeof parsed !== "object" || parsed === null) {
     return { kind: "corrupted", problem: "the file does not contain a JSON object" };
   }
+  return { kind: "ok", raw: parsed };
+}
+function siteFileFrom(raw, credential) {
+  return {
+    siteId: raw.siteId,
+    credential,
+    createdAt: typeof raw.createdAt === "string" ? raw.createdAt : "",
+    apiBaseUrl: typeof raw.apiBaseUrl === "string" ? raw.apiBaseUrl : "",
+    ...typeof raw.shortId === "string" ? { shortId: raw.shortId } : {},
+    ...typeof raw.url === "string" ? { url: raw.url } : {},
+    ...typeof raw.boundDomain === "string" ? { boundDomain: raw.boundDomain } : {}
+  };
+}
+function loadSiteFile(projectDir) {
+  const disk = readSiteFileOnDisk(projectDir);
+  if (disk.kind !== "ok") return disk;
+  const parsed = disk.raw;
   if (typeof parsed.siteId !== "string" || parsed.siteId.length === 0) {
     return { kind: "corrupted", problem: "the siteId field is missing or empty" };
   }
+  if (typeof parsed.credentialRef === "string" && parsed.credentialRef.length > 0) {
+    const stored = readStoredCredential(parsed.credentialRef);
+    if (stored.kind === "absent") {
+      return {
+        kind: "corrupted",
+        problem: `its credential is kept in the user-level store, but ${credentialStorePathSafe(parsed.credentialRef)} is missing on this machine. Restore that file from a backup of the home directory (or copy it from the machine that published the site); if it is gone for good, recover the site through its custom domain (recover) or, for a free site created on this device, recover with action "device"`
+      };
+    }
+    if (stored.kind === "corrupted") return { kind: "corrupted", problem: stored.problem };
+    return { kind: "ok", file: siteFileFrom(parsed, stored.entry.credential) };
+  }
   if (typeof parsed.credential !== "string" || parsed.credential.length === 0) {
     return { kind: "corrupted", problem: "the credential field is missing or empty" };
   }
@@ -1664,24 +1815,41 @@ function loadSiteFile(projectDir) {
       problem: "the credential does not match the shape Sakupa issues (sk_ followed by exactly 43 URL-safe base64 characters) \u2014 it looks locally altered or damaged"
     };
   }
-  return {
-    kind: "ok",
-    file: {
-      siteId: parsed.siteId,
-      credential: parsed.credential,
-      createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : "",
-      apiBaseUrl: typeof parsed.apiBaseUrl === "string" ? parsed.apiBaseUrl : "",
-      ...typeof parsed.shortId === "string" ? { shortId: parsed.shortId } : {},
-      ...typeof parsed.url === "string" ? { url: parsed.url } : {},
-      ...typeof parsed.boundDomain === "string" ? { boundDomain: parsed.boundDomain } : {}
+  const file = siteFileFrom(parsed, parsed.credential);
+  migrateInlineCredential(projectDir, file);
+  return { kind: "ok", file };
+}
+function credentialStorePathSafe(ref) {
+  try {
+    return credentialStorePath(ref);
+  } catch {
+    return `the credential store entry "${ref}"`;
+  }
+}
+function migrateInlineCredential(projectDir, file) {
+  try {
+    const ref = newCredentialRef();
+    storeCredential({
+      ref,
+      siteId: file.siteId,
+      apiBaseUrl: file.apiBaseUrl,
+      credential: file.credential,
+      createdAt: file.createdAt
+    });
+    try {
+      writeSiteFileOnDisk(projectDir, file, ref);
+    } catch (error) {
+      deleteStoredCredential(ref);
+      throw error;
     }
-  };
+  } catch {
+  }
 }
 function loadRecoveryFile(projectDir) {
   const path = recoveryFilePath(projectDir);
-  if (!existsSync2(path)) return null;
+  if (!existsSync3(path)) return null;
   try {
-    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    const parsed = JSON.parse(readFileSync3(path, "utf8"));
     if (typeof parsed.verificationId !== "string" || parsed.verificationId.length === 0 || typeof parsed.credential !== "string" || !CREDENTIAL_PATTERN.test(parsed.credential)) {
       throw new Error("required recovery fields are missing or invalid");
     }
@@ -1697,19 +1865,20 @@ function loadRecoveryFile(projectDir) {
   }
 }
 function writeRecoveryFile(projectDir, file) {
-  const dir = join3(projectDir, SITE_DIR);
-  mkdirSync2(dir, { recursive: true });
-  const path = join3(dir, RECOVERY_FILE);
-  writeFileSync2(path, `${JSON.stringify(file, null, 2)}
+  const dir = join4(projectDir, SITE_DIR);
+  mkdirSync3(dir, { recursive: true, mode: 448 });
+  ensureSakupaGitignore(projectDir);
+  const path = join4(dir, RECOVERY_FILE);
+  writeFileSync3(path, `${JSON.stringify(file, null, 2)}
 `, "utf8");
   try {
-    chmodSync2(path, 384);
+    chmodSync3(path, 384);
   } catch {
   }
 }
 function deleteRecoveryFile(projectDir) {
   const path = recoveryFilePath(projectDir);
-  if (existsSync2(path)) rmSync(path, { force: true });
+  if (existsSync3(path)) rmSync2(path, { force: true });
 }
 function siteFileRecoveryGuidance(projectDir) {
   return `The site itself is intact on the server; only the local binding file (${siteFilePath(projectDir)}) is the problem. Restore the file (from a backup or by undoing the local edit). Do NOT delete it to work around the error: the credential is unrecoverable by design, so abandoning it permanently orphans the existing site. Run help for a safe repair path; the tool will never overwrite a damaged binding or ask the user to manipulate credentials manually.`;
@@ -1728,35 +1897,57 @@ function writeSiteFile(projectDir, file, opts = {}) {
       );
     }
   }
-  const dir = join3(projectDir, SITE_DIR);
-  mkdirSync2(dir, { recursive: true });
-  const path = join3(dir, SITE_FILE);
-  const temporary = join3(dir, `.site-${randomUUID2()}.tmp`);
-  writeFileSync2(temporary, `${JSON.stringify(file, null, 2)}
+  const disk = readSiteFileOnDisk(projectDir);
+  const existingRef = disk.kind === "ok" && disk.raw.siteId === file.siteId && typeof disk.raw.credentialRef === "string" && disk.raw.credentialRef.length > 0 ? disk.raw.credentialRef : void 0;
+  const ref = existingRef ?? newCredentialRef();
+  storeCredential({
+    ref,
+    siteId: file.siteId,
+    apiBaseUrl: file.apiBaseUrl,
+    credential: file.credential,
+    createdAt: file.createdAt
+  });
+  try {
+    writeSiteFileOnDisk(projectDir, file, ref);
+  } catch (error) {
+    if (existingRef === void 0) deleteStoredCredential(ref);
+    throw error;
+  }
+}
+function writeSiteFileOnDisk(projectDir, file, ref) {
+  const dir = join4(projectDir, SITE_DIR);
+  mkdirSync3(dir, { recursive: true, mode: 448 });
+  ensureSakupaGitignore(projectDir);
+  const path = join4(dir, SITE_FILE);
+  const { credential: _omitted, ...rest } = file;
+  const onDisk = { ...rest, credentialRef: ref };
+  const temporary = join4(dir, `.site-${randomUUID3()}.tmp`);
+  writeFileSync3(temporary, `${JSON.stringify(onDisk, null, 2)}
 `, {
     encoding: "utf8",
     mode: 384
   });
   try {
-    chmodSync2(temporary, 384);
+    chmodSync3(temporary, 384);
   } catch {
   }
   try {
-    renameSync2(temporary, path);
+    renameSync3(temporary, path);
   } catch (error) {
-    rmSync(temporary, { force: true });
+    rmSync2(temporary, { force: true });
     throw error;
   }
 }
 function deleteSiteFile(projectDir) {
   const path = siteFilePath(projectDir);
-  if (existsSync2(path)) {
-    rmSync(path, { force: true });
+  const disk = readSiteFileOnDisk(projectDir);
+  if (existsSync3(path)) {
+    rmSync2(path, { force: true });
   }
-  try {
-    rmdirSync2(join3(projectDir, SITE_DIR));
-  } catch {
+  if (disk.kind === "ok" && typeof disk.raw.credentialRef === "string") {
+    deleteStoredCredential(disk.raw.credentialRef);
   }
+  pruneSakupaDirectory(projectDir);
 }
 function deleteSiteFileIfMatches(projectDir, expected) {
   const state = loadSiteFile(projectDir);
@@ -1779,17 +1970,17 @@ function findAncestor(startDir, predicate, maxLevels = Number.POSITIVE_INFINITY)
   return null;
 }
 function isInsideGitRepo(projectDir) {
-  return existsSync2(join3(projectDir, ".git")) || findAncestor(projectDir, (dir) => existsSync2(join3(dir, ".git"))) !== null;
+  return existsSync3(join4(projectDir, ".git")) || findAncestor(projectDir, (dir) => existsSync3(join4(dir, ".git"))) !== null;
 }
 function credentialGitReminder(projectDir) {
   if (!isInsideGitRepo(projectDir)) return "";
-  return '\nNOTE: this project is inside a git repository. The management credential in .sakupa/site.json is the key to this site \u2014 do NOT commit it to a PUBLIC repository (add ".sakupa/" to .gitignore yourself if you want to keep it out of version control).';
+  return '\nNOTE: this project is inside a git repository. The management credential in .sakupa/site.json is the key to this site \u2014 do NOT commit it to a PUBLIC repository. Sakupa keeps a ".sakupa/.gitignore" that ignores the whole directory; leave it in place.';
 }
 
 // src/recovery-archive.ts
-import { existsSync as existsSync3, realpathSync as realpathSync2 } from "node:fs";
+import { existsSync as existsSync4, realpathSync as realpathSync2 } from "node:fs";
 import { mkdtemp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { dirname as dirname2, isAbsolute as isAbsolute2, join as join4, relative as relative2, resolve as resolve3, sep as sep3 } from "node:path";
+import { dirname as dirname2, isAbsolute as isAbsolute2, join as join5, relative as relative2, resolve as resolve3, sep as sep3 } from "node:path";
 
 // ../../node_modules/fflate/esm/index.mjs
 import { createRequire } from "module";
@@ -2289,7 +2480,7 @@ function safeOutputPath(projectDir, outputDir) {
     throw new SakupaError("invalid_request", "Recovery content cannot be written inside .sakupa");
   }
   let existingAncestor = target;
-  while (!existsSync3(existingAncestor)) {
+  while (!existsSync4(existingAncestor)) {
     const parent = dirname2(existingAncestor);
     if (parent === existingAncestor) break;
     existingAncestor = parent;
@@ -2331,7 +2522,7 @@ async function listExistingFiles(root, current = root) {
     if (entry.isSymbolicLink()) {
       throw new SakupaError("state_conflict", `Recovery output contains a symlink: ${entry.name}`);
     }
-    const absolute = join4(current, entry.name);
+    const absolute = join5(current, entry.name);
     if (entry.isDirectory()) files.push(...await listExistingFiles(root, absolute));
     else if (entry.isFile()) files.push(relative2(root, absolute).split(sep3).join("/"));
     else
@@ -2349,7 +2540,7 @@ async function existingOutputMatches(outputDir, files) {
     return false;
   }
   for (const name of expected) {
-    const actual = await readFile(join4(outputDir, ...name.split("/")));
+    const actual = await readFile(join5(outputDir, ...name.split("/")));
     const wanted = files[name];
     if (!wanted || actual.byteLength !== wanted.byteLength || !actual.equals(wanted)) return false;
   }
@@ -2400,13 +2591,13 @@ async function extractRecoveryArchive(input) {
       `Recovery output already exists with different content: ${outputDir}. Move it aside or choose another outputDir.`
     );
   }
-  const tempDir = await mkdtemp(join4(resolve3(input.projectDir), ".sakupa-restore-"));
+  const tempDir = await mkdtemp(join5(resolve3(input.projectDir), ".sakupa-restore-"));
   try {
     let writtenBytes = 0;
     const entries = Object.entries(files).sort(([a], [b]) => a.localeCompare(b));
     for (const [rawName, data] of entries) {
       const name = safeEntryName(rawName);
-      const destination = join4(tempDir, ...name.split("/"));
+      const destination = join5(tempDir, ...name.split("/"));
       await mkdir(dirname2(destination), { recursive: true });
       await writeFile(destination, data, { flag: "wx" });
       writtenBytes += data.byteLength;
@@ -2432,19 +2623,19 @@ async function extractRecoveryArchive(input) {
 }
 
 // src/creation-registry.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
-import { homedir as homedir2 } from "node:os";
-import { dirname as dirname3, join as join5 } from "node:path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { dirname as dirname3, join as join6 } from "node:path";
 var RECENT_WINDOW_MS = FREE_SITE_TTL_HOURS * 60 * 60 * 1e3;
 function creationRegistryPath() {
-  const base = process.env["SAKUPA_STATE_DIR"] ?? homedir2();
-  return join5(base, ".sakupa", "created-sites.json");
+  const base = process.env["SAKUPA_STATE_DIR"] ?? homedir3();
+  return join6(base, ".sakupa", "created-sites.json");
 }
 function readAll() {
   const path = creationRegistryPath();
-  if (!existsSync4(path)) return [];
+  if (!existsSync5(path)) return [];
   try {
-    const parsed = JSON.parse(readFileSync3(path, "utf-8"));
+    const parsed = JSON.parse(readFileSync4(path, "utf-8"));
     if (!Array.isArray(parsed)) return [];
     return parsed.filter(
       (e) => typeof e === "object" && e !== null && typeof e.siteId === "string" && typeof e.projectDir === "string" && typeof e.url === "string" && typeof e.createdAt === "string" && (e.apiBaseUrl === void 0 || typeof e.apiBaseUrl === "string")
@@ -2455,8 +2646,8 @@ function readAll() {
 }
 function writeAll(records) {
   const path = creationRegistryPath();
-  mkdirSync3(dirname3(path), { recursive: true });
-  writeFileSync3(path, `${JSON.stringify(records, null, 2)}
+  mkdirSync4(dirname3(path), { recursive: true });
+  writeFileSync4(path, `${JSON.stringify(records, null, 2)}
 `, "utf-8");
 }
 function listRecentCreations(nowMs, apiBaseUrl) {
@@ -2500,28 +2691,28 @@ function noteSiteMode(siteId, mode) {
 // src/device-file.ts
 import {
   closeSync,
-  existsSync as existsSync5,
-  mkdirSync as mkdirSync4,
+  existsSync as existsSync6,
+  mkdirSync as mkdirSync5,
   openSync,
-  readFileSync as readFileSync4,
-  renameSync as renameSync3,
+  readFileSync as readFileSync5,
+  renameSync as renameSync4,
   statSync as statSync2,
   unlinkSync as unlinkSync2,
-  writeFileSync as writeFileSync4
+  writeFileSync as writeFileSync5
 } from "node:fs";
-import { randomUUID as randomUUID3 } from "node:crypto";
-import { homedir as homedir3 } from "node:os";
-import { dirname as dirname4, join as join6 } from "node:path";
+import { randomUUID as randomUUID4 } from "node:crypto";
+import { homedir as homedir4 } from "node:os";
+import { dirname as dirname4, join as join7 } from "node:path";
 var DEVICE_LOCK_STALE_MS = 3e4;
 var DEVICE_LOCK_WAIT_MS = 2e4;
 function deviceRegistryPath() {
-  const base = process.env["SAKUPA_STATE_DIR"] ?? homedir3();
-  return join6(base, ".sakupa", "devices.json");
+  const base = process.env["SAKUPA_STATE_DIR"] ?? homedir4();
+  return join7(base, ".sakupa", "devices.json");
 }
-var deviceLockPath = () => join6(dirname4(deviceRegistryPath()), "devices.lock");
+var deviceLockPath = () => join7(dirname4(deviceRegistryPath()), "devices.lock");
 function lockTokenAt(path) {
   try {
-    const parsed = JSON.parse(readFileSync4(path, "utf8"));
+    const parsed = JSON.parse(readFileSync5(path, "utf8"));
     return typeof parsed.token === "string" ? parsed.token : null;
   } catch {
     return null;
@@ -2543,15 +2734,15 @@ function releaseDeviceLock(lock) {
 }
 async function acquireDeviceLock(apiBaseUrl) {
   const path = deviceLockPath();
-  mkdirSync4(dirname4(path), { recursive: true, mode: 448 });
+  mkdirSync5(dirname4(path), { recursive: true, mode: 448 });
   const deadline = Date.now() + DEVICE_LOCK_WAIT_MS;
   while (true) {
     const existing = loadDeviceBinding(apiBaseUrl);
     if (existing) return existing;
     try {
-      const token = randomUUID3();
+      const token = randomUUID4();
       const fd2 = openSync(path, "wx", 384);
-      writeFileSync4(
+      writeFileSync5(
         fd2,
         JSON.stringify({ token, pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() })
       );
@@ -2576,11 +2767,11 @@ async function acquireDeviceLock(apiBaseUrl) {
 }
 function readRegistry() {
   const path = deviceRegistryPath();
-  if (!existsSync5(path)) {
+  if (!existsSync6(path)) {
     return { schemaVersion: 1, environments: {}, pendingRegistrations: {} };
   }
   try {
-    const parsed = JSON.parse(readFileSync4(path, "utf8"));
+    const parsed = JSON.parse(readFileSync5(path, "utf8"));
     if (parsed.schemaVersion !== 1 || !parsed.environments || typeof parsed.environments !== "object") {
       throw new Error("unsupported device registry schema");
     }
@@ -2594,14 +2785,14 @@ function readRegistry() {
 }
 function writeRegistry(registry) {
   const path = deviceRegistryPath();
-  mkdirSync4(dirname4(path), { recursive: true, mode: 448 });
+  mkdirSync5(dirname4(path), { recursive: true, mode: 448 });
   const temporary = `${path}.${process.pid}.tmp`;
-  writeFileSync4(temporary, `${JSON.stringify(registry, null, 2)}
+  writeFileSync5(temporary, `${JSON.stringify(registry, null, 2)}
 `, {
     encoding: "utf8",
     mode: 384
   });
-  renameSync3(temporary, path);
+  renameSync4(temporary, path);
 }
 function loadDeviceBinding(apiBaseUrl) {
   const binding = readRegistry().environments[apiBaseUrl];
@@ -2622,8 +2813,8 @@ async function ensureDeviceBinding(client, apiBaseUrl) {
     let pending = registry.pendingRegistrations[apiBaseUrl];
     if (!pending) {
       pending = {
-        operationId: randomUUID3(),
-        deviceId: randomUUID3(),
+        operationId: randomUUID4(),
+        deviceId: randomUUID4(),
         credential: generateCredential(),
         createdAt: (/* @__PURE__ */ new Date()).toISOString()
       };
@@ -2655,15 +2846,15 @@ async function ensureDeviceBinding(client, apiBaseUrl) {
 // src/site-handoff.ts
 import {
   closeSync as closeSync2,
-  existsSync as existsSync6,
-  mkdirSync as mkdirSync5,
+  existsSync as existsSync7,
+  mkdirSync as mkdirSync6,
   openSync as openSync2,
   statSync as statSync3,
   unlinkSync as unlinkSync3,
-  writeFileSync as writeFileSync5
+  writeFileSync as writeFileSync6
 } from "node:fs";
 import { createHash } from "node:crypto";
-import { dirname as dirname5, isAbsolute as isAbsolute3, join as join7 } from "node:path";
+import { dirname as dirname5, isAbsolute as isAbsolute3, join as join8 } from "node:path";
 var HANDOFF_LOCK_TTL_MS = 15 * 60 * 1e3;
 function normalizeSiteUrl(raw) {
   const url = new URL(raw);
@@ -2719,12 +2910,12 @@ function resolveReusableSite(rawUrl, currentProjectDir, nowMs, apiBaseUrl) {
 }
 function lockPath(siteId) {
   const digest = createHash("sha256").update(siteId).digest("hex");
-  return join7(dirname5(creationRegistryPath()), "handoff-locks", `${digest}.lock`);
+  return join8(dirname5(creationRegistryPath()), "handoff-locks", `${digest}.lock`);
 }
 function acquireSiteHandoffLock(siteId) {
   const path = lockPath(siteId);
-  mkdirSync5(dirname5(path), { recursive: true, mode: 448 });
-  if (existsSync6(path)) {
+  mkdirSync6(dirname5(path), { recursive: true, mode: 448 });
+  if (existsSync7(path)) {
     try {
       if (Date.now() - statSync3(path).mtimeMs >= HANDOFF_LOCK_TTL_MS) unlinkSync3(path);
     } catch {
@@ -2738,7 +2929,7 @@ function acquireSiteHandoffLock(siteId) {
       "Another Sakupa process is already performing a site handoff for this free site. Wait for it to finish and retry deploy."
     );
   }
-  writeFileSync5(fd2, JSON.stringify({ siteId, createdAt: (/* @__PURE__ */ new Date()).toISOString() }));
+  writeFileSync6(fd2, JSON.stringify({ siteId, createdAt: (/* @__PURE__ */ new Date()).toISOString() }));
   return () => {
     try {
       closeSync2(fd2);
@@ -2952,26 +3143,26 @@ var CLIENT_TYPE = "sakupa-mcp";
 
 // src/credential-rotation.ts
 import {
-  chmodSync as chmodSync3,
-  existsSync as existsSync7,
-  mkdirSync as mkdirSync6,
-  readFileSync as readFileSync5,
-  renameSync as renameSync4,
-  rmSync as rmSync2,
-  writeFileSync as writeFileSync6
+  chmodSync as chmodSync4,
+  existsSync as existsSync8,
+  mkdirSync as mkdirSync7,
+  readFileSync as readFileSync6,
+  renameSync as renameSync5,
+  rmSync as rmSync3,
+  writeFileSync as writeFileSync7
 } from "node:fs";
-import { randomUUID as randomUUID4 } from "node:crypto";
-import { join as join8 } from "node:path";
+import { randomUUID as randomUUID5 } from "node:crypto";
+import { join as join9 } from "node:path";
 var ROTATION_FILE = "rotation.json";
 function credentialRotationPath(projectDir) {
-  return join8(projectDir, ".sakupa", ROTATION_FILE);
+  return join9(projectDir, ".sakupa", ROTATION_FILE);
 }
 function loadCredentialRotation(projectDir) {
   const path = credentialRotationPath(projectDir);
-  if (!existsSync7(path)) return { kind: "absent" };
+  if (!existsSync8(path)) return { kind: "absent" };
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync5(path, "utf8"));
+    parsed = JSON.parse(readFileSync6(path, "utf8"));
   } catch (error) {
     return {
       kind: "corrupted",
@@ -3018,28 +3209,28 @@ function writeCredentialRotation(projectDir, file) {
       "A different credential rotation is already pending. Run rotate to resume it; no state was overwritten."
     );
   }
-  const directory = join8(projectDir, ".sakupa");
-  mkdirSync6(directory, { recursive: true, mode: 448 });
+  const directory = join9(projectDir, ".sakupa");
+  mkdirSync7(directory, { recursive: true, mode: 448 });
   const target = credentialRotationPath(projectDir);
-  const temporary = join8(directory, `.rotation-${randomUUID4()}.tmp`);
-  writeFileSync6(temporary, `${JSON.stringify(file, null, 2)}
+  const temporary = join9(directory, `.rotation-${randomUUID5()}.tmp`);
+  writeFileSync7(temporary, `${JSON.stringify(file, null, 2)}
 `, {
     encoding: "utf8",
     mode: 384
   });
   try {
-    chmodSync3(temporary, 384);
+    chmodSync4(temporary, 384);
   } catch {
   }
   try {
-    renameSync4(temporary, target);
+    renameSync5(temporary, target);
   } catch (error) {
-    rmSync2(temporary, { force: true });
+    rmSync3(temporary, { force: true });
     throw error;
   }
 }
 function deleteCredentialRotation(projectDir) {
-  rmSync2(credentialRotationPath(projectDir), { force: true });
+  rmSync3(credentialRotationPath(projectDir), { force: true });
 }
 function promoteRotatedCredential(projectDir, site, rotation, credentialCreatedAt) {
   if (rotation.siteId !== site.siteId || rotation.apiBaseUrl !== site.apiBaseUrl) {
@@ -3659,7 +3850,7 @@ function timestampForAgentInZone(exactTimestamp, clientTimeZone) {
 }
 
 // src/tools/context.ts
-import { randomUUID as randomUUID5 } from "node:crypto";
+import { randomUUID as randomUUID6 } from "node:crypto";
 var LocalGuidanceError = class extends SakupaError {
   constructor(code, message) {
     super(code, message);
@@ -3744,7 +3935,7 @@ function reportAuthorizationStore(ctx) {
   return store;
 }
 function issueReportAuthorization(ctx, failedTool) {
-  const token = randomUUID5();
+  const token = randomUUID6();
   reportAuthorizationStore(ctx).set(token, {
     failedTool,
     expiresAt: Date.now() + 10 * 60 * 1e3
@@ -3777,7 +3968,7 @@ function requireSiteFile(ctx) {
   }
   return state.file;
 }
-var UNAUTHORIZED_SUMMARY = "The server rejected the site credential: the one in .sakupa/site.json no longer matches the server-side verifier. The site itself is intact on the server \u2014 only the local binding file is the problem. Repair the file (restore a backup or undo the local edit). Do NOT delete the .sakupa directory to work around this: the credential is unrecoverable by design, so abandoning it permanently orphans the existing site.";
+var UNAUTHORIZED_SUMMARY = "The server rejected the site credential: the one referenced by .sakupa/site.json (kept in the user-level credential store) no longer matches the server-side verifier. The site itself is intact on the server \u2014 only the local binding file is the problem. Repair the file (restore a backup or undo the local edit). Do NOT delete the .sakupa directory to work around this: the credential is unrecoverable by design, so abandoning it permanently orphans the existing site.";
 function toolError(e) {
   if (e instanceof McpRootsPending) {
     return inputRequired({ inputRequests: { roots: inputRequired.listRoots() } });
@@ -4208,7 +4399,7 @@ function ensureUploadSizeWithinLimits(manifest, isFirstFreeDeploy) {
 async function buildHashedManifest(files, outputAbs) {
   const manifest = [];
   for (const file of files) {
-    const bytes = new Uint8Array(await fs2.readFile(join9(outputAbs, file.path)));
+    const bytes = new Uint8Array(await fs2.readFile(join10(outputAbs, file.path)));
     manifest.push({ path: file.path, size: file.size, contentHash: await sha256Hex(bytes) });
   }
   return manifest;
@@ -4227,7 +4418,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(join9(outputAbs, match.path)));
+    const bytes = new Uint8Array(await fs2.readFile(join10(outputAbs, match.path)));
     if (bytes.byteLength !== match.size) {
       throw new SakupaError(
         "validation_failed",
@@ -4372,14 +4563,14 @@ function outputDirectoryChain(projectRoot, outputAbs) {
   const chain = [];
   let cursor = projectRoot;
   for (const part of rel.split(sep4).filter(Boolean)) {
-    cursor = join9(cursor, part);
+    cursor = join10(cursor, part);
     chain.push(cursor);
   }
   return chain;
 }
 async function sakupaDirectoryEntries(projectDir) {
   try {
-    return await fs2.readdir(join9(projectDir, ".sakupa"));
+    return await fs2.readdir(join10(projectDir, ".sakupa"));
   } catch (error) {
     const code = error.code;
     if (code === "ENOENT") return [];
@@ -4532,7 +4723,7 @@ function registerTools(server, baseCtx) {
           const entries = await sakupaDirectoryEntries(candidateDir);
           if (entries.length === 0) continue;
           const unknownEntries = entries.filter(
-            (entry) => !["project.json", "site.json", "recovery.json"].includes(entry)
+            (entry) => !["project.json", "site.json", "recovery.json", ".gitignore"].includes(entry)
           );
           if (unknownEntries.length > 0) {
             return text(
@@ -4560,8 +4751,8 @@ function registerTools(server, baseCtx) {
                 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: join9(candidateDir, ".sakupa"),
-                  targetSakupaDirectory: join9(ctx.projectDir, ".sakupa"),
+                  misplacedSakupaDirectory: join10(candidateDir, ".sakupa"),
+                  targetSakupaDirectory: join10(ctx.projectDir, ".sakupa"),
                   confirmationField: "sakupaRelocationConfirmed",
                   confirmation,
                   confirmArguments
@@ -5226,7 +5417,7 @@ ${JSON.stringify(finalized.warnings, null, 2)}
           {
             siteId: site.siteId,
             plan: args.plan,
-            idempotencyKey: randomUUID6()
+            idempotencyKey: randomUUID7()
           },
           site.credential
         );
@@ -5549,11 +5740,13 @@ Full status:`,
     "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.",
+      description: 'Recover management control of a site after losing the local .sakupa binding. Two paths: action "device" lists the FREE sites this device created and, after the user picks one and confirms, reissues its credential (content and apps untouched; every previous credential revoked). Actions start/status/complete/download recover a subscribed site WITH A BOUND CUSTOM DOMAIN by proving DNS control of the apex domain; a subscribed site without a bound domain 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 },
       inputSchema: z2.object({
-        action: z2.enum(["start", "status", "complete", "download"]),
+        action: z2.enum(["device", "start", "status", "complete", "download"]),
+        siteId: z2.string().optional().describe("device only: the site chosen from the decision (copied verbatim)."),
+        confirmed: z2.boolean().optional().describe("device only: true only from the exact decision arguments."),
         hostname: z2.string().optional().describe("Required for start."),
         verificationId: z2.string().optional().describe("For status or complete; inferred from local recovery state when omitted."),
         outputDir: z2.string().optional().describe(
@@ -5602,6 +5795,139 @@ Full status:`,
           deleteRecoveryFile(ctx.projectDir);
           return { archive, extracted };
         };
+        if (args.action === "device") {
+          if (localSite.kind === "ok" && await localCredentialIsActive()) {
+            return structuredToolResult({
+              schemaVersion: 1,
+              outcome: "blocked",
+              resultCode: "recovery_credential_already_present",
+              summary: summaryMarkdown({
+                title: "This project already holds a working credential",
+                lead: `${localSite.file.url ?? localSite.file.siteId} is bound here and its credential works; nothing was changed. Use status or deploy. To manage a different free site, open its own project directory.`,
+                next: ["`status`"]
+              }),
+              data: { siteId: localSite.file.siteId, credentialStoredLocally: true },
+              nextActions: [{ tool: "status", arguments: {}, allowed: true }]
+            });
+          }
+          const device = await ensureDeviceBinding(ctx.client, ctx.apiBaseUrl);
+          if (args.confirmed === true && args.siteId) {
+            const res2 = await ctx.client.reissueDeviceFreeSiteCredential(
+              args.siteId,
+              device.deviceId,
+              device.credential
+            );
+            const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+            writeSiteFile(
+              ctx.projectDir,
+              {
+                siteId: res2.siteId,
+                shortId: res2.shortId,
+                url: res2.url,
+                credential: res2.credential,
+                createdAt: nowIso,
+                apiBaseUrl: ctx.apiBaseUrl
+              },
+              { allowReplace: true }
+            );
+            recordCreation({
+              siteId: res2.siteId,
+              projectDir: ctx.projectDir,
+              url: res2.url,
+              createdAt: nowIso,
+              apiBaseUrl: ctx.apiBaseUrl
+            });
+            return structuredToolResult({
+              schemaVersion: 1,
+              outcome: "completed",
+              resultCode: "free_site_credential_recovered",
+              summary: summaryMarkdown({
+                title: `Credential reissued for ${res2.url}`,
+                lead: "A new management credential was issued and saved for this project; the site content, settings and installed apps are untouched.",
+                facts: [
+                  ["Site ID", res2.siteId],
+                  ["Public URL", res2.url],
+                  ["Free expiry", timestampForAgent(res2.expiresAt)],
+                  ["Previous credentials revoked", res2.revokedPreviousCredentials],
+                  [
+                    "Credential path",
+                    ".sakupa/site.json (reference) + the user-level credential store"
+                  ]
+                ],
+                notes: [
+                  "Any other project directory that still referred to this site no longer has management authority.",
+                  "No DNS verification was needed: ownership was proven by this device."
+                ],
+                next: ["`status`", "`deploy` to publish changes"]
+              }),
+              data: {
+                siteId: res2.siteId,
+                shortId: res2.shortId,
+                url: res2.url,
+                expiresAt: res2.expiresAt,
+                revokedPreviousCredentials: res2.revokedPreviousCredentials,
+                credentialPath: ".sakupa/site.json",
+                credentialStoredLocally: true,
+                dnsVerificationRepeated: false,
+                projectDir: ctx.projectDir
+              },
+              nextActions: [{ tool: "status", arguments: {}, allowed: true }]
+            });
+          }
+          const sites = await discoverDeviceFreeSites(ctx.client, ctx.apiBaseUrl, device);
+          if (sites.length === 0) {
+            return structuredToolResult({
+              schemaVersion: 1,
+              outcome: "completed",
+              resultCode: "device_free_sites_none",
+              summary: summaryMarkdown({
+                title: "No recoverable free site on this device",
+                lead: "This device created no free site that is still active, so there is nothing to reissue. A free site published from another device cannot be recovered here; a subscribed site with a custom domain can be recovered with recover start; otherwise publish again with deploy.",
+                next: ["`deploy`", '`recover` with action "start" (custom-domain site)']
+              }),
+              data: { deviceSites: [], environment: environmentFor(ctx.apiBaseUrl) },
+              nextActions: [
+                {
+                  tool: "deploy",
+                  arguments: {},
+                  allowed: false,
+                  reasonCode: "requires_outputDir_from_agent"
+                }
+              ]
+            });
+          }
+          return presentDecision(baseCtx.decisions, call, "recover", {
+            resultCode: "device_free_site_selection_required",
+            summary: summaryMarkdown({
+              title: "Choose the free site whose credential should be reissued",
+              lead: `${sites.length} active free site(s) were created on this device. Nothing was changed. Reissuing revokes every previous credential of the chosen site; its content and apps stay as they are.`,
+              facts: sites.map((site) => [
+                site.url,
+                `expires ${timestampForAgent(site.expiresAt)}`
+              ])
+            }),
+            data: { deviceSites: sites, environment: environmentFor(ctx.apiBaseUrl) },
+            prompt: "Which free site should get a new management credential for this project?",
+            options: [
+              ...sites.map(
+                (site) => callToolDecisionOption({
+                  id: `recover_free_site_${site.shortId}`,
+                  label: `Reissue the credential of ${site.url}`,
+                  description: `Bind this project to ${site.url} with a fresh credential.`,
+                  consequences: [
+                    "Every previous credential of this site is revoked; other project directories bound to it stop working.",
+                    "Content, settings and installed apps are untouched."
+                  ],
+                  tool: "recover",
+                  arguments: { action: "device", siteId: site.siteId, confirmed: true },
+                  reasonCode: "user_selected_device_free_site"
+                })
+              ),
+              noActionDecisionOption({ description: "Reissue nothing." })
+            ],
+            legacyUserAction: { type: "select_site", provider: "sakupa" }
+          });
+        }
         if (args.action === "download") {
           const { archive, extracted } = await download();
           return text(
@@ -6152,7 +6478,7 @@ function registerBillingTools(server, baseCtx) {
 }
 
 // src/tools/help.ts
-import { join as join10 } from "node:path";
+import { join as join11 } from "node:path";
 import { z as z4 } from "zod";
 var TOOL_TOPICS = [
   "init",
@@ -6345,11 +6671,13 @@ var TOOL_MANUALS = {
     nextStep: "Query billing after the user confirms an operation in Stripe."
   },
   recover: {
-    purpose: "Recover a paid custom-domain site credential and download its content.",
-    sideEffects: "Creates DNS verification state and writes local credential/archive files.",
-    preconditions: "DNS control of a domain bound to an active paid site.",
+    purpose: 'Recover a lost site binding: reissue the credential of a free site this device created (action "device"), or recover a paid custom-domain site by DNS and download its content.',
+    sideEffects: "device: after an explicit choice, revokes the old credentials of that site and writes the local binding. DNS path: creates verification state and writes local credential/archive files.",
+    preconditions: "device: the site was created on this device and is still an active free site. DNS path: DNS control of a domain bound to an active paid site.",
     parameterNames: [
       "action",
+      "siteId",
+      "confirmed",
       "hostname",
       "verificationId",
       "outputDir",
@@ -6447,7 +6775,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 = join10(ctx.projectDir, ".sakupa");
+        const sakupaDirectory = join11(ctx.projectDir, ".sakupa");
         return structuredToolResult({
           schemaVersion: 1,
           outcome: "completed",
@@ -7273,7 +7601,7 @@ function registerAppsTools(server, baseCtx) {
 }
 
 // src/tools/delete.ts
-import { randomUUID as randomUUID7 } from "node:crypto";
+import { randomUUID as randomUUID8 } from "node:crypto";
 import { z as z7 } from "zod";
 var confirmationSchema = z7.object({
   siteId: z7.string(),
@@ -7360,7 +7688,7 @@ function registerDeleteTools(server, baseCtx) {
             nextActions: []
           });
         }
-        const operationId = randomUUID7();
+        const operationId = randomUUID8();
         const preview = await ctx.client.previewDeleteSite(site.siteId, site.credential, {
           operationId
         });
@@ -7622,8 +7950,9 @@ Workflow:
    (Vite/Vue/React/Svelte/Astro/Next static export/Nuxt generate), run the build LOCALLY first,
    then re-run analyze.
 2. deploy \u2014 uploads ONLY the built static output. The first deploy creates a free temporary
-   site (public URL ${hostPattern}, valid 30 days, free banner shown) and stores the
-   management credential in .sakupa/site.json. Deploying again updates the site and refreshes
+   site (public URL ${hostPattern}, valid 30 days, free banner shown) and binds this project
+   in .sakupa/site.json; the credential itself is kept in the user-level Sakupa credential store
+   (home directory, owner-only), never inside the project. 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. Every update checks the credential's
    server-side issue time. When it is older than 7 days, deploy succeeds and only SUGGESTS the
@@ -7645,6 +7974,8 @@ Workflow:
    30-day site and removes paid data after Stripe sends the signed final-cancellation webhook.
    Recovery writes the new local credential before downloading content. If a session stops after
    .sakupa/site.json exists, NEVER repeat DNS recovery: resume with recover action "download".
+   A FREE site created on this device can get its credential reissued with recover action
+   "device" (no DNS): present every listed site, let the user choose, then confirm.
 5. If any Sakupa operation is difficult or fails, call help FIRST. support handles billing,
    payment, refund and other customer-service requests. report is the LAST resort only when
    help explicitly recommends a product bug report, and submission still requires user review.
@@ -7738,7 +8069,7 @@ Safety boundaries:
 - Never upload source projects, secrets, .env files, private keys, archives, videos or audio.
 - Payment card data is entered only on Stripe-hosted pages \u2014 never through the AI tool.
 - A subscription never grants domain ownership; only DNS verification does.
-- Never repeat, echo, or memorize the credential value from .sakupa/site.json \u2014 quoting it
+- Never repeat, echo, or memorize the credential value from the credential store or any file \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
@@ -7751,8 +8082,10 @@ Safety boundaries:
   other than Japanese, look up the approximate exchange rate and show an estimated local
   price next to the JPY amount, clearly marked as an estimate \u2014 Stripe always settles the
   real charge in JPY. Never show a bare Yen sign.
-- The management credential lives only in .sakupa/site.json; never share or upload it. Without
-  a bound custom domain, a lost credential is unrecoverable by design. portal then opens
+- The management credential lives only in the user-level Sakupa credential store (referenced by
+  .sakupa/site.json); never share or upload it. A lost credential can be reissued only for a free
+  site from the device that created it (recover action "device") or for a subscribed site through
+  its bound custom domain; otherwise it 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;