@sakupa/mcp 1.5.0 → 1.6.0

package/dist/index.js

@@ -148,7 +148,7 @@ function isFreeSiteAllowanceNetworkReference(value) {
 }
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "1.5.0";
+var SAKUPA_MCP_VERSION = "1.6.0";
 
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
@@ -891,6 +891,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 });
   }
@@ -1092,129 +1099,90 @@ var HttpApiClient = class {
 };
 
 // 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 join3 } from "node:path";
+
+// src/credential-store.ts
+import { randomUUID } from "node:crypto";
 import {
   chmodSync,
   existsSync,
   mkdirSync,
   readFileSync,
   renameSync,
-  rmdirSync,
   rmSync,
   writeFileSync
 } from "node:fs";
-import { randomUUID } from "node:crypto";
-import { dirname, join } from "node:path";
-var SITE_DIR = ".sakupa";
-var SITE_FILE = "site.json";
-var RECOVERY_FILE = "recovery.json";
-function siteFilePath(projectDir) {
-  return join(projectDir, SITE_DIR, SITE_FILE);
+import { homedir } from "node:os";
+import { join } from "node:path";
+var REF_PATTERN = /^[0-9a-f-]{36}$/i;
+function credentialStoreDirectory() {
+  const base = process.env["SAKUPA_STATE_DIR"] ?? homedir();
+  return join(base, ".sakupa", "credentials");
 }
-function recoveryFilePath(projectDir) {
-  return join(projectDir, SITE_DIR, RECOVERY_FILE);
+function credentialStorePath(ref) {
+  if (!REF_PATTERN.test(ref)) throw new Error("Invalid credential reference.");
+  return join(credentialStoreDirectory(), `${ref}.json`);
 }
-function loadSiteFile(projectDir) {
-  const path = siteFilePath(projectDir);
-  if (!existsSync(path)) return { kind: "absent" };
-  let raw;
-  try {
-    raw = readFileSync(path, "utf8");
-  } catch (err2) {
+function newCredentialRef() {
+  return randomUUID();
+}
+function readStoredCredential(ref) {
+  if (!REF_PATTERN.test(ref)) {
     return {
       kind: "corrupted",
-      problem: `the file exists but could not be read (${err2 instanceof Error ? err2.message : String(err2)})`
+      problem: "the credentialRef does not look like a Sakupa reference"
     };
   }
+  const path = credentialStorePath(ref);
+  if (!existsSync(path)) return { kind: "absent" };
   let parsed;
   try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return { kind: "corrupted", problem: "the file exists but is not valid JSON" };
-  }
-  if (typeof parsed !== "object" || parsed === null) {
-    return { kind: "corrupted", problem: "the file does not contain a JSON object" };
-  }
-  if (typeof parsed.siteId !== "string" || parsed.siteId.length === 0) {
-    return { kind: "corrupted", problem: "the siteId field is missing or empty" };
+    parsed = JSON.parse(readFileSync(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.credential !== "string" || parsed.credential.length === 0) {
-    return { kind: "corrupted", problem: "the credential field is missing or empty" };
+  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 does not match the shape Sakupa issues (sk_ followed by exactly 43 URL-safe base64 characters) \u2014 it looks locally altered or damaged"
+      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",
-    file: {
-      siteId: parsed.siteId,
-      credential: parsed.credential,
-      createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : "",
+    entry: {
+      ref,
+      siteId: typeof parsed.siteId === "string" ? parsed.siteId : "",
       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 } : {}
-    }
-  };
-}
-function loadRecoveryFile(projectDir) {
-  const path = recoveryFilePath(projectDir);
-  if (!existsSync(path)) return null;
-  try {
-    const parsed = JSON.parse(readFileSync(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");
-    }
-    return {
-      verificationId: parsed.verificationId,
       credential: parsed.credential,
       createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : ""
-    };
-  } catch (error) {
-    throw new Error(
-      `Recovery state ${path} is damaged (${error instanceof Error ? error.message : String(error)}). Do not start another DNS recovery until this file is repaired or deliberately removed.`
-    );
-  }
-}
-function writeRecoveryFile(projectDir, file) {
-  const dir = join(projectDir, SITE_DIR);
-  mkdirSync(dir, { recursive: true });
-  const path = join(dir, RECOVERY_FILE);
-  writeFileSync(path, `${JSON.stringify(file, null, 2)}
-`, "utf8");
-  try {
-    chmodSync(path, 384);
-  } catch {
-  }
-}
-function deleteRecoveryFile(projectDir) {
-  const path = recoveryFilePath(projectDir);
-  if (existsSync(path)) rmSync(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.`;
-}
-function writeSiteFile(projectDir, file, opts = {}) {
-  if (opts.allowReplace !== true) {
-    const existing = loadSiteFile(projectDir);
-    if (existing.kind === "corrupted") {
-      throw new Error(
-        `Refusing to overwrite ${siteFilePath(projectDir)}: ${existing.problem}. ` + siteFileRecoveryGuidance(projectDir)
-      );
-    }
-    if (existing.kind === "ok" && existing.file.siteId !== file.siteId) {
-      throw new Error(
-        `Refusing to overwrite ${siteFilePath(projectDir)}: it already binds this project to site ${existing.file.siteId}. ` + siteFileRecoveryGuidance(projectDir)
-      );
     }
+  };
+}
+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 = join(projectDir, SITE_DIR);
-  mkdirSync(dir, { recursive: true });
-  const path = join(dir, SITE_FILE);
-  const temporary = join(dir, `.site-${randomUUID()}.tmp`);
-  writeFileSync(temporary, `${JSON.stringify(file, null, 2)}
+  const dir = credentialStoreDirectory();
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  const path = credentialStorePath(entry.ref);
+  const temporary = join(dir, `.${entry.ref}.${process.pid}.tmp`);
+  writeFileSync(temporary, `${JSON.stringify(entry, null, 2)}
 `, {
     encoding: "utf8",
     mode: 384
@@ -1230,707 +1198,928 @@ function writeSiteFile(projectDir, file, opts = {}) {
     throw error;
   }
 }
-function deleteSiteFile(projectDir) {
-  const path = siteFilePath(projectDir);
-  if (existsSync(path)) {
-    rmSync(path, { force: true });
+function deleteStoredCredential(ref) {
+  if (!REF_PATTERN.test(ref)) return;
+  rmSync(credentialStorePath(ref), { force: true });
+}
+
+// src/project-root.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import {
+  chmodSync as chmodSync2,
+  existsSync as existsSync2,
+  lstatSync,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync2,
+  readdirSync,
+  realpathSync,
+  renameSync as renameSync2,
+  rmdirSync,
+  statSync,
+  unlinkSync,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { isAbsolute, join as join2, 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;
+  constructor(code, message) {
+    super(message);
+    this.name = "ProjectRootError";
+    this.code = code;
   }
+};
+function projectMarkerPath(projectDir) {
+  return join2(projectDir, SAKUPA_DIR, PROJECT_FILE);
+}
+function loadProjectMarker(projectDir) {
+  const path = projectMarkerPath(projectDir);
+  if (!existsSync2(path)) return { kind: "absent" };
+  let parsed;
   try {
-    rmdirSync(join(projectDir, SITE_DIR));
-  } catch {
+    parsed = JSON.parse(readFileSync2(path, "utf8"));
+  } catch (error) {
+    return {
+      kind: "corrupted",
+      problem: `the file cannot be read as JSON (${error instanceof Error ? error.message : String(error)})`
+    };
   }
-}
-function deleteSiteFileIfMatches(projectDir, expected) {
-  const state = loadSiteFile(projectDir);
-  if (state.kind === "absent") return "absent";
-  if (state.kind === "corrupted") return "corrupted";
-  if (state.file.siteId !== expected.siteId || state.file.credential !== expected.credential) {
-    return "mismatch";
+  if (typeof parsed !== "object" || parsed === null) {
+    return { kind: "corrupted", problem: "the file does not contain a JSON object" };
   }
-  deleteSiteFile(projectDir);
-  return "removed";
-}
-function findAncestor(startDir, predicate, maxLevels = Number.POSITIVE_INFINITY) {
-  let cursor = startDir;
-  for (let i = 0; i < maxLevels; i += 1) {
-    const parent = dirname(cursor);
-    if (parent === cursor) return null;
-    if (predicate(parent)) return parent;
-    cursor = parent;
+  const record = parsed;
+  if (record.schemaVersion !== PROJECT_SCHEMA_VERSION) {
+    return {
+      kind: "corrupted",
+      problem: `unsupported schemaVersion ${String(record.schemaVersion)}`
+    };
   }
-  return null;
-}
-function isInsideGitRepo(projectDir) {
-  return existsSync(join(projectDir, ".git")) || findAncestor(projectDir, (dir) => existsSync(join(dir, ".git"))) !== null;
-}
-function credentialGitReminder(projectDir) {
-  if (!isInsideGitRepo(projectDir)) return "";
-  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).';
-}
-
-// src/analyze/analyzer.ts
-import { promises as fs } from "node:fs";
-import { join as join2, posix, resolve, sep } from "node:path";
-var SERVER_RUNTIME_DEPS = ["express", "koa", "fastify", "hapi", "@hapi/hapi"];
-var DB_RUNTIME_DEPS = [
-  "prisma",
-  "@prisma/client",
-  "mongoose",
-  "pg",
-  "mysql2",
-  "better-sqlite3",
-  "typeorm",
-  "sequelize",
-  "redis",
-  "ioredis"
-];
-var USE_SERVER_SCAN_MAX_FILES = 200;
-var USE_SERVER_SCAN_MAX_BYTES = 256 * 1024;
-var CONTENT_READ_MAX_BYTES = 1024 * 1024;
-var TEXT_CONTENT_EXTENSIONS = /* @__PURE__ */ new Set(["html", "htm", "js", "mjs", "css", "json", "txt", "xml"]);
-var SOURCE_SCAN_EXTENSIONS = /* @__PURE__ */ new Set(["js", "jsx", "ts", "tsx", "mjs", "cjs"]);
-var FORBIDDEN_SEGMENTS_LOWER = new Set(FORBIDDEN_PATH_SEGMENTS.map((s) => s.toLowerCase()));
-async function isDirectory(path) {
-  try {
-    return (await fs.stat(path)).isDirectory();
-  } catch {
-    return false;
+  if (typeof record.projectId !== "string" || !isUuid(record.projectId)) {
+    return { kind: "corrupted", problem: "projectId is missing or is not a UUID" };
   }
-}
-async function isFile(path) {
-  try {
-    return (await fs.stat(path)).isFile();
-  } catch {
-    return false;
+  if (typeof record.createdAt !== "string" || !Number.isFinite(Date.parse(record.createdAt))) {
+    return { kind: "corrupted", problem: "createdAt is missing or invalid" };
   }
-}
-async function readTextIfExists(path, maxBytes = CONTENT_READ_MAX_BYTES) {
-  try {
-    const stat2 = await fs.stat(path);
-    if (!stat2.isFile() || stat2.size > maxBytes) return null;
-    return await fs.readFile(path, "utf8");
-  } catch {
-    return null;
+  if (record.outputDir !== void 0 && (typeof record.outputDir !== "string" || !isSafeRelativeOutput(record.outputDir))) {
+    return { kind: "corrupted", problem: "outputDir is not a safe project-relative path" };
   }
+  return {
+    kind: "ok",
+    marker: {
+      schemaVersion: PROJECT_SCHEMA_VERSION,
+      projectId: record.projectId,
+      createdAt: record.createdAt,
+      ...record.outputDir !== void 0 ? { outputDir: normalizeRelative(record.outputDir) } : {}
+    }
+  };
 }
-async function firstExistingFile(dir, names) {
-  for (const name of names) {
-    const p = join2(dir, name);
-    if (await isFile(p)) return p;
+function initializeProject(projectDir) {
+  const canonical = canonicalProjectDirectory(projectDir);
+  assertSafeProjectRoot(canonical);
+  const current = loadProjectMarker(canonical);
+  if (current.kind === "corrupted") {
+    throw new ProjectRootError(
+      "corrupted_marker",
+      `Refusing to overwrite damaged Sakupa project marker ${projectMarkerPath(canonical)}: ${current.problem}.`
+    );
   }
-  return null;
-}
-function extensionOf(path) {
-  const base = path.split("/").pop() ?? "";
-  const idx = base.lastIndexOf(".");
-  if (idx <= 0) return "";
-  return base.slice(idx + 1).toLowerCase();
-}
-async function walkFiles(dir, opts) {
-  const out = [];
-  async function recurse(current, relPrefix) {
-    if (out.length > opts.maxFiles) return;
-    let entries;
-    try {
-      entries = await fs.readdir(current, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
-    for (const entry of entries) {
-      if (out.length > opts.maxFiles) return;
-      const rel = relPrefix.length > 0 ? `${relPrefix}/${entry.name}` : entry.name;
-      if (entry.isSymbolicLink()) continue;
-      if (entry.isDirectory()) {
-        if (FORBIDDEN_SEGMENTS_LOWER.has(entry.name.toLowerCase())) continue;
-        if (opts.skipRelDirs?.has(rel)) continue;
-        await recurse(join2(current, entry.name), rel);
-      } else if (entry.isFile()) {
-        try {
-          const stat2 = await fs.stat(join2(current, entry.name));
-          out.push({ path: rel, size: stat2.size });
-        } catch {
-        }
-      }
-    }
+  if (current.kind === "ok") {
+    return {
+      projectDir: canonical,
+      requestedPath: canonical,
+      markerKind: "project",
+      marker: current.marker
+    };
   }
-  await recurse(dir, "");
-  return out;
+  const marker = {
+    schemaVersion: PROJECT_SCHEMA_VERSION,
+    projectId: randomUUID2(),
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  writeMarkerAtomically(canonical, marker);
+  return {
+    projectDir: canonical,
+    requestedPath: canonical,
+    markerKind: "project",
+    marker
+  };
 }
-async function readPackageJson(projectDir) {
-  const raw = await readTextIfExists(join2(projectDir, "package.json"));
-  if (raw === null) return null;
+function resolveLockedProjectRoot(projectDir) {
+  const canonical = canonicalProjectDirectory(projectDir);
+  assertSafeProjectRoot(canonical);
+  const markerState = loadProjectMarker(canonical);
+  if (markerState.kind === "corrupted") {
+    throw new ProjectRootError(
+      "corrupted_marker",
+      `Sakupa project marker ${projectMarkerPath(canonical)} is damaged: ${markerState.problem}.`
+    );
+  }
+  if (markerState.kind === "absent") {
+    throw new ProjectRootError(
+      "not_initialized",
+      `The MCP working directory ${canonical} is not initialized. Call the init MCP tool with no path argument. If help confirms that this client has no MCP Roots, the AI may run \`npx -y @sakupa/mcp@latest init\` itself as the fallback.`
+    );
+  }
+  return {
+    projectDir: canonical,
+    requestedPath: canonical,
+    markerKind: "project",
+    marker: markerState.marker
+  };
+}
+function updateProjectOutputDir(projectDir, outputDir) {
+  const canonical = canonicalProjectDirectory(projectDir);
+  const state = loadProjectMarker(canonical);
+  if (state.kind !== "ok") {
+    throw new ProjectRootError(
+      state.kind === "corrupted" ? "corrupted_marker" : "not_initialized",
+      state.kind === "corrupted" ? `Cannot update damaged Sakupa project marker: ${state.problem}.` : `No Sakupa project marker exists in ${canonical}.`
+    );
+  }
+  if (!isSafeRelativeOutput(outputDir)) {
+    throw new ProjectRootError(
+      "unsafe_path",
+      `Output directory "${outputDir}" must stay inside the initialized Sakupa project.`
+    );
+  }
+  const marker = {
+    ...state.marker,
+    outputDir: normalizeRelative(outputDir)
+  };
+  writeMarkerAtomically(canonical, marker);
+  return marker;
+}
+function ensureSakupaGitignore(projectDir) {
+  const dir = join2(projectDir, SAKUPA_DIR);
+  if (!existsSync2(dir)) return;
+  const path = join2(dir, GITIGNORE_FILE);
+  if (existsSync2(path)) return;
   try {
-    const parsed = JSON.parse(raw);
-    return typeof parsed === "object" && parsed !== null ? parsed : null;
+    writeFileSync2(path, GITIGNORE_CONTENT, { encoding: "utf8", flag: "wx" });
   } catch {
-    return null;
   }
 }
-function allDeps(pkg) {
-  return { ...pkg?.dependencies ?? {}, ...pkg?.devDependencies ?? {} };
+function pruneSakupaDirectory(projectDir) {
+  const dir = join2(projectDir, SAKUPA_DIR);
+  if (!existsSync2(dir)) return;
+  try {
+    const entries = readdirSync(dir);
+    if (entries.every((entry) => entry === GITIGNORE_FILE)) {
+      for (const entry of entries) unlinkSync(join2(dir, entry));
+      rmdirSync(dir);
+    }
+  } catch {
+  }
 }
-async function anyFileMatches(dir, predicate) {
-  if (!await isDirectory(dir)) return false;
-  const files = await walkFiles(dir, { maxFiles: 2e3 });
-  return files.some((f) => predicate(f.path.split("/").pop() ?? ""));
+function deleteProjectMarker(projectDir) {
+  const path = projectMarkerPath(projectDir);
+  if (existsSync2(path)) unlinkSync(path);
+  pruneSakupaDirectory(projectDir);
 }
-async function detectFramework(projectDir, pkg) {
-  const deps = allDeps(pkg);
-  const ssrRisks = [];
-  const nextConfigPath = await firstExistingFile(projectDir, [
-    "next.config.js",
-    "next.config.mjs",
-    "next.config.ts",
-    "next.config.cjs"
-  ]);
-  if ("next" in deps || nextConfigPath !== null) {
-    const config = nextConfigPath ? await readTextIfExists(nextConfigPath) : null;
-    const staticExport = config !== null && /output\s*:\s*['"]export['"]/.test(config);
-    if (!staticExport) {
-      ssrRisks.push(
-        `Next.js project without output: 'export' in next.config.* \u2014 the default Next.js build requires a Node.js server. Sakupa only serves static files; add output: 'export' to next.config.* and build locally to produce a static "out" directory.`
-      );
-    }
-    for (const apiDir of ["pages/api", "src/pages/api"]) {
-      if (await isDirectory(join2(projectDir, apiDir))) {
-        ssrRisks.push(
-          `API routes (${apiDir}/) require a server runtime and will not run on Sakupa. Remove them or move their logic to build time before static export.`
-        );
-        break;
-      }
-    }
-    for (const appDir of ["app", "src/app"]) {
-      if (await anyFileMatches(
-        join2(projectDir, appDir),
-        (base) => /^route\.(ts|js|tsx|jsx|mjs)$/.test(base)
-      )) {
-        ssrRisks.push(
-          `App Router route handlers (${appDir}/**/route.ts|js) require a server runtime and will not run on Sakupa.`
-        );
-        break;
-      }
+function canonicalProjectDirectory(path) {
+  const canonical = canonicalExistingPath(resolve(path));
+  if (!statSync(canonical).isDirectory()) {
+    throw new ProjectRootError("invalid_path", `Project path ${canonical} is not a directory.`);
+  }
+  return canonical;
+}
+function canonicalExistingPath(path) {
+  try {
+    const stat2 = lstatSync(path, { throwIfNoEntry: false });
+    if (!stat2) {
+      throw new ProjectRootError("invalid_path", `Project path ${path} does not exist.`);
     }
-    if (await firstExistingFile(projectDir, [
-      "middleware.ts",
-      "middleware.js",
-      "src/middleware.ts",
-      "src/middleware.js"
-    ]) !== null) {
-      ssrRisks.push("middleware.(ts|js) runs on a server/edge runtime and will not run on Sakupa.");
+    return realpathSync(path);
+  } catch (error) {
+    if (error instanceof ProjectRootError) throw error;
+    throw new ProjectRootError(
+      "invalid_path",
+      `Project path ${path} cannot be resolved (${error instanceof Error ? error.message : String(error)}).`
+    );
+  }
+}
+function assertSafeProjectRoot(projectDir) {
+  if (parse(projectDir).root === projectDir || projectDir === realpathSync(homedir2())) {
+    throw new ProjectRootError(
+      "unsafe_path",
+      `Refusing to use ${projectDir} as a Sakupa project root; choose a specific project directory.`
+    );
+  }
+}
+function isUuid(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+function normalizeRelative(path) {
+  const normalized = path.split(sep).join("/").replace(/^\.\//, "").replace(/\/$/, "");
+  return normalized.length === 0 ? "." : normalized;
+}
+function isSafeRelativeOutput(path) {
+  if (path.length === 0 || isAbsolute(path)) return false;
+  const normalized = normalizeRelative(path);
+  if (normalized === ".") return true;
+  const rel = relative("/sakupa-root", resolve("/sakupa-root", normalized));
+  return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+function writeMarkerAtomically(projectDir, marker) {
+  const dir = join2(projectDir, SAKUPA_DIR);
+  mkdirSync2(dir, { recursive: true, mode: 448 });
+  ensureSakupaGitignore(projectDir);
+  const path = projectMarkerPath(projectDir);
+  const temporary = `${path}.${process.pid}.${randomUUID2()}.tmp`;
+  try {
+    writeFileSync2(temporary, `${JSON.stringify(marker, null, 2)}
+`, {
+      encoding: "utf8",
+      mode: 384
+    });
+    renameSync2(temporary, path);
+    try {
+      chmodSync2(path, 384);
+    } catch {
     }
+  } finally {
+    if (existsSync2(temporary)) unlinkSync(temporary);
+  }
+}
+
+// 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);
+}
+function recoveryFilePath(projectDir) {
+  return join3(projectDir, SITE_DIR, RECOVERY_FILE);
+}
+function readSiteFileOnDisk(projectDir) {
+  const path = siteFilePath(projectDir);
+  if (!existsSync3(path)) return { kind: "absent" };
+  let raw;
+  try {
+    raw = readFileSync3(path, "utf8");
+  } catch (err2) {
     return {
-      framework: "next",
-      outputCandidates: ["out"],
-      buildCommandHint: "npm run build",
-      ssrRisks
+      kind: "corrupted",
+      problem: `the file exists but could not be read (${err2 instanceof Error ? err2.message : String(err2)})`
     };
   }
-  const nuxtConfigPath = await firstExistingFile(projectDir, [
-    "nuxt.config.ts",
-    "nuxt.config.js",
-    "nuxt.config.mjs"
-  ]);
-  if ("nuxt" in deps || "nuxt3" in deps || nuxtConfigPath !== null) {
-    for (const serverDir of ["server/api", "server/routes"]) {
-      if (await isDirectory(join2(projectDir, serverDir))) {
-        ssrRisks.push(
-          `Nuxt server handlers (${serverDir}/) require a server runtime and will not run on Sakupa. Use static generation (npx nuxi generate) and deploy .output/public.`
-        );
-      }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { kind: "corrupted", problem: "the file exists but is not valid JSON" };
+  }
+  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" };
+  }
+  if (!CREDENTIAL_PATTERN.test(parsed.credential)) {
     return {
-      framework: "nuxt",
-      outputCandidates: [".output/public", "dist"],
-      buildCommandHint: "npm run generate (or npx nuxi generate)",
-      ssrRisks
+      kind: "corrupted",
+      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"
     };
   }
-  const astroConfigPath = await firstExistingFile(projectDir, [
-    "astro.config.mjs",
-    "astro.config.js",
-    "astro.config.ts"
-  ]);
-  if ("astro" in deps || astroConfigPath !== null) {
-    const config = astroConfigPath ? await readTextIfExists(astroConfigPath) : null;
-    if (config !== null && /output\s*:\s*['"]server['"]/.test(config)) {
-      ssrRisks.push(
-        "Astro config sets output: 'server' (SSR). Sakupa only serves static files; use the default static output (or output: 'static') and build locally."
-      );
+  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 (!existsSync3(path)) return null;
+  try {
+    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");
     }
     return {
-      framework: "astro",
-      outputCandidates: ["dist"],
-      buildCommandHint: "npm run build",
-      ssrRisks
+      verificationId: parsed.verificationId,
+      credential: parsed.credential,
+      createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : ""
     };
+  } catch (error) {
+    throw new Error(
+      `Recovery state ${path} is damaged (${error instanceof Error ? error.message : String(error)}). Do not start another DNS recovery until this file is repaired or deliberately removed.`
+    );
   }
-  if ("@sveltejs/kit" in deps) {
-    if ("@sveltejs/adapter-node" in deps) {
-      ssrRisks.push(
-        "SvelteKit is configured with @sveltejs/adapter-node, which produces a Node.js server. Sakupa only serves static files; switch to @sveltejs/adapter-static and rebuild."
-      );
-    } else if (!("@sveltejs/adapter-static" in deps)) {
-      ssrRisks.push(
-        "SvelteKit requires @sveltejs/adapter-static to produce a fully static build. Install and configure it, then build locally."
+}
+function writeRecoveryFile(projectDir, file) {
+  const dir = join3(projectDir, SITE_DIR);
+  mkdirSync3(dir, { recursive: true, mode: 448 });
+  ensureSakupaGitignore(projectDir);
+  const path = join3(dir, RECOVERY_FILE);
+  writeFileSync3(path, `${JSON.stringify(file, null, 2)}
+`, "utf8");
+  try {
+    chmodSync3(path, 384);
+  } catch {
+  }
+}
+function deleteRecoveryFile(projectDir) {
+  const path = recoveryFilePath(projectDir);
+  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.`;
+}
+function writeSiteFile(projectDir, file, opts = {}) {
+  if (opts.allowReplace !== true) {
+    const existing = loadSiteFile(projectDir);
+    if (existing.kind === "corrupted") {
+      throw new Error(
+        `Refusing to overwrite ${siteFilePath(projectDir)}: ${existing.problem}. ` + siteFileRecoveryGuidance(projectDir)
       );
     }
-    if (await anyFileMatches(join2(projectDir, "src/routes"), (base) => base.startsWith("+server."))) {
-      ssrRisks.push(
-        "SvelteKit +server.* endpoint files require a server runtime and will not run on Sakupa."
+    if (existing.kind === "ok" && existing.file.siteId !== file.siteId) {
+      throw new Error(
+        `Refusing to overwrite ${siteFilePath(projectDir)}: it already binds this project to site ${existing.file.siteId}. ` + siteFileRecoveryGuidance(projectDir)
       );
     }
-    return {
-      framework: "sveltekit",
-      outputCandidates: ["build"],
-      buildCommandHint: "npm run build",
-      ssrRisks
-    };
   }
-  if ("react-scripts" in deps) {
-    return {
-      framework: "create-react-app",
-      outputCandidates: ["build"],
-      buildCommandHint: "npm run build",
-      ssrRisks
-    };
+  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;
   }
-  const viteConfigPath = await firstExistingFile(projectDir, [
-    "vite.config.ts",
-    "vite.config.js",
-    "vite.config.mjs"
-  ]);
-  if ("vite" in deps || viteConfigPath !== null) {
-    let framework = "vite";
-    if ("vue" in deps) framework = "vue (vite)";
-    else if ("react" in deps) framework = "react (vite)";
-    else if ("svelte" in deps) framework = "svelte (vite)";
-    return {
-      framework,
-      outputCandidates: ["dist"],
-      buildCommandHint: "npm run build",
-      ssrRisks
-    };
+}
+function writeSiteFileOnDisk(projectDir, file, ref) {
+  const dir = join3(projectDir, SITE_DIR);
+  mkdirSync3(dir, { recursive: true, mode: 448 });
+  ensureSakupaGitignore(projectDir);
+  const path = join3(dir, SITE_FILE);
+  const { credential: _omitted, ...rest } = file;
+  const onDisk = { ...rest, credentialRef: ref };
+  const temporary = join3(dir, `.site-${randomUUID3()}.tmp`);
+  writeFileSync3(temporary, `${JSON.stringify(onDisk, null, 2)}
+`, {
+    encoding: "utf8",
+    mode: 384
+  });
+  try {
+    chmodSync3(temporary, 384);
+  } catch {
+  }
+  try {
+    renameSync3(temporary, path);
+  } catch (error) {
+    rmSync2(temporary, { force: true });
+    throw error;
+  }
+}
+function deleteSiteFile(projectDir) {
+  const path = siteFilePath(projectDir);
+  const disk = readSiteFileOnDisk(projectDir);
+  if (existsSync3(path)) {
+    rmSync2(path, { force: true });
+  }
+  if (disk.kind === "ok" && typeof disk.raw.credentialRef === "string") {
+    deleteStoredCredential(disk.raw.credentialRef);
+  }
+  pruneSakupaDirectory(projectDir);
+}
+function deleteSiteFileIfMatches(projectDir, expected) {
+  const state = loadSiteFile(projectDir);
+  if (state.kind === "absent") return "absent";
+  if (state.kind === "corrupted") return "corrupted";
+  if (state.file.siteId !== expected.siteId || state.file.credential !== expected.credential) {
+    return "mismatch";
+  }
+  deleteSiteFile(projectDir);
+  return "removed";
+}
+function findAncestor(startDir, predicate, maxLevels = Number.POSITIVE_INFINITY) {
+  let cursor = startDir;
+  for (let i = 0; i < maxLevels; i += 1) {
+    const parent = dirname(cursor);
+    if (parent === cursor) return null;
+    if (predicate(parent)) return parent;
+    cursor = parent;
   }
   return null;
 }
-function serverAndDbDepRisks(pkg, hasStaticOutput) {
-  const deps = allDeps(pkg);
-  const risks = [];
-  for (const name of SERVER_RUNTIME_DEPS) {
-    if (name in deps) {
-      risks.push(
-        hasStaticOutput ? `Warning: dependency "${name}" is a server framework. Sakupa never runs it online \u2014 only the static output is served. Using it locally at build time is fine.` : `Dependency "${name}" is a server framework. Sakupa does not host server runtimes; only prebuilt static output can be deployed.`
-      );
-    }
+function isInsideGitRepo(projectDir) {
+  return existsSync3(join3(projectDir, ".git")) || findAncestor(projectDir, (dir) => existsSync3(join3(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. Sakupa keeps a ".sakupa/.gitignore" that ignores the whole directory; leave it in place.';
+}
+
+// src/analyze/analyzer.ts
+import { promises as fs } from "node:fs";
+import { join as join4, posix, resolve as resolve2, sep as sep2 } from "node:path";
+var SERVER_RUNTIME_DEPS = ["express", "koa", "fastify", "hapi", "@hapi/hapi"];
+var DB_RUNTIME_DEPS = [
+  "prisma",
+  "@prisma/client",
+  "mongoose",
+  "pg",
+  "mysql2",
+  "better-sqlite3",
+  "typeorm",
+  "sequelize",
+  "redis",
+  "ioredis"
+];
+var USE_SERVER_SCAN_MAX_FILES = 200;
+var USE_SERVER_SCAN_MAX_BYTES = 256 * 1024;
+var CONTENT_READ_MAX_BYTES = 1024 * 1024;
+var TEXT_CONTENT_EXTENSIONS = /* @__PURE__ */ new Set(["html", "htm", "js", "mjs", "css", "json", "txt", "xml"]);
+var SOURCE_SCAN_EXTENSIONS = /* @__PURE__ */ new Set(["js", "jsx", "ts", "tsx", "mjs", "cjs"]);
+var FORBIDDEN_SEGMENTS_LOWER = new Set(FORBIDDEN_PATH_SEGMENTS.map((s) => s.toLowerCase()));
+async function isDirectory(path) {
+  try {
+    return (await fs.stat(path)).isDirectory();
+  } catch {
+    return false;
   }
-  for (const name of DB_RUNTIME_DEPS) {
-    if (name in deps) {
-      risks.push(
-        hasStaticOutput ? `Warning: dependency "${name}" is a database/runtime client. Sakupa never runs it online \u2014 using a database locally at build time to generate static pages is fine.` : `Dependency "${name}" is a database/runtime client. Sakupa does not host databases or server runtimes; generate static pages locally and deploy only the output.`
-      );
-    }
+}
+async function isFile(path) {
+  try {
+    return (await fs.stat(path)).isFile();
+  } catch {
+    return false;
   }
-  return risks;
 }
-async function scanForUseServer(projectDir, skipRelDirs) {
-  const files = await walkFiles(projectDir, { maxFiles: USE_SERVER_SCAN_MAX_FILES, skipRelDirs });
-  let scanned = 0;
-  for (const file of files) {
-    if (scanned >= USE_SERVER_SCAN_MAX_FILES) break;
-    if (!SOURCE_SCAN_EXTENSIONS.has(extensionOf(file.path))) continue;
-    scanned += 1;
-    const text2 = await readTextIfExists(join2(projectDir, file.path), USE_SERVER_SCAN_MAX_BYTES);
-    if (text2 !== null && /['"]use server['"]/.test(text2)) return true;
+async function readTextIfExists(path, maxBytes = CONTENT_READ_MAX_BYTES) {
+  try {
+    const stat2 = await fs.stat(path);
+    if (!stat2.isFile() || stat2.size > maxBytes) return null;
+    return await fs.readFile(path, "utf8");
+  } catch {
+    return null;
   }
-  return false;
 }
-function normalizeOutputDir(outputDir) {
-  const normalized = posix.normalize(outputDir.replaceAll(sep, "/")).replace(/\/+$/, "");
-  return normalized === "" ? "." : normalized;
+async function firstExistingFile(dir, names) {
+  for (const name of names) {
+    const p = join4(dir, name);
+    if (await isFile(p)) return p;
+  }
+  return null;
 }
-async function analyzeProject(projectDir, opts = {}) {
-  const root = await fs.realpath(resolve(projectDir));
-  const pkg = await readPackageJson(root);
-  const detection = await detectFramework(root, pkg);
-  const ssrRisks = [...detection?.ssrRisks ?? []];
-  const hasBuildScript = typeof pkg?.scripts?.["build"] === "string";
-  const buildRequired = detection !== null || hasBuildScript;
-  let outputDirRel;
-  let outputDirExists = false;
-  if (opts.outputDir !== void 0) {
-    outputDirRel = normalizeOutputDir(opts.outputDir);
-    const abs = resolve(root, outputDirRel);
-    if (abs !== root && !abs.startsWith(root + sep)) {
-      outputDirRel = ".";
-      outputDirExists = false;
-    } else {
-      outputDirExists = await isDirectory(abs) || outputDirRel === "." && await isDirectory(root);
-      if (outputDirExists) {
+function extensionOf(path) {
+  const base = path.split("/").pop() ?? "";
+  const idx = base.lastIndexOf(".");
+  if (idx <= 0) return "";
+  return base.slice(idx + 1).toLowerCase();
+}
+async function walkFiles(dir, opts) {
+  const out = [];
+  async function recurse(current, relPrefix) {
+    if (out.length > opts.maxFiles) return;
+    let entries;
+    try {
+      entries = await fs.readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    for (const entry of entries) {
+      if (out.length > opts.maxFiles) return;
+      const rel = relPrefix.length > 0 ? `${relPrefix}/${entry.name}` : entry.name;
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        if (FORBIDDEN_SEGMENTS_LOWER.has(entry.name.toLowerCase())) continue;
+        if (opts.skipRelDirs?.has(rel)) continue;
+        await recurse(join4(current, entry.name), rel);
+      } else if (entry.isFile()) {
         try {
-          const physical = await fs.realpath(abs);
-          if (physical !== root && !physical.startsWith(root + sep)) {
-            outputDirExists = false;
-          }
+          const stat2 = await fs.stat(join4(current, entry.name));
+          out.push({ path: rel, size: stat2.size });
         } catch {
-          outputDirExists = false;
         }
       }
     }
-  } else if (detection) {
-    for (const candidate of detection.outputCandidates) {
-      if (await isDirectory(join2(root, candidate))) {
-        outputDirRel = candidate;
-        outputDirExists = true;
-        break;
-      }
-    }
-    if (outputDirRel === void 0) {
-      outputDirRel = detection.outputCandidates[0] ?? "dist";
-      outputDirExists = false;
-    }
-  } else if (!buildRequired) {
-    outputDirRel = ".";
-    outputDirExists = true;
-  } else if (hasBuildScript) {
-    for (const candidate of ["dist", "build", "out", "public"]) {
-      if (await isFile(join2(root, candidate, "index.html"))) {
-        outputDirRel = candidate;
-        outputDirExists = true;
-        break;
-      }
-    }
-  }
-  const projectType = detection ? "framework" : outputDirRel !== void 0 && !buildRequired ? "plain-static" : "unknown";
-  const buildCommandHint = detection ? detection.buildCommandHint : hasBuildScript ? "npm run build" : void 0;
-  if (pkg !== null && buildRequired) {
-    const skip = /* @__PURE__ */ new Set();
-    if (outputDirRel !== void 0 && outputDirRel !== ".") skip.add(outputDirRel);
-    if (await scanForUseServer(root, skip)) {
-      ssrRisks.push(
-        "Source files contain 'use server' directives (server actions). Server actions require a server runtime and will not run on Sakupa."
-      );
-    }
-  }
-  if (outputDirRel === void 0 || !outputDirExists) {
-    ssrRisks.push(...serverAndDbDepRisks(pkg, false));
-    const sourceWithoutBuild = pkg !== null && buildRequired && (await isDirectory(join2(root, "src")) || await isDirectory(join2(root, "pages")));
-    let suggestedNextAction2;
-    if (opts.outputDir !== void 0) {
-      suggestedNextAction2 = `The requested output directory "${opts.outputDir}" does not exist. Build the project locally first (${buildCommandHint ?? "npm run build"}) or pass the correct directory, then re-run analyze.`;
-    } else if (ssrRisks.length > 0 && detection) {
-      suggestedNextAction2 = `This ${detection.framework} project appears to require a server runtime (see ssrRisks) and no static output directory was found. Convert it to static output (e.g. Next.js output: 'export', Nuxt generate, Astro static, SvelteKit adapter-static), run the build locally (${buildCommandHint ?? "npm run build"}), then re-run analyze.`;
-    } else if (sourceWithoutBuild || detection && !outputDirExists) {
-      suggestedNextAction2 = `This looks like a source project, not built static output. Run the build locally (${buildCommandHint ?? "npm run build"}) then re-run analyze.`;
-    } else {
-      suggestedNextAction2 = "No deployable static output was found. Create an index.html (or build the project locally so a static output directory exists), then re-run analyze.";
-    }
-    return {
-      projectType,
-      ...detection ? { framework: detection.framework } : {},
-      ...outputDirRel !== void 0 ? { recommendedOutputDir: outputDirRel } : {},
-      outputDirExists: false,
-      ...buildCommandHint !== void 0 ? { buildCommandHint } : {},
-      entryHtmlFound: false,
-      langSupported: false,
-      totalBytes: 0,
-      fileCount: 0,
-      issues: [],
-      ssrRisks,
-      spa: { looksLikeSpa: false, autoFallback: false },
-      deployable: false,
-      suggestedNextAction: suggestedNextAction2
-    };
-  }
-  const outputAbs = outputDirRel === "." ? root : resolve(root, outputDirRel);
-  const walked = await walkFiles(outputAbs, { maxFiles: MAX_FILE_COUNT + 1 });
-  const candidates = [];
-  for (const file of walked) {
-    const ext = extensionOf(file.path);
-    let content;
-    if (TEXT_CONTENT_EXTENSIONS.has(ext) && file.size <= CONTENT_READ_MAX_BYTES) {
-      try {
-        content = new Uint8Array(await fs.readFile(join2(outputAbs, file.path)));
-      } catch {
-        content = void 0;
-      }
-    }
-    candidates.push({ path: file.path, size: file.size, ...content ? { content } : {} });
-  }
-  const validation = validateDeployableFiles(candidates, {
-    mode: "free",
-    ...opts.formsScriptUrl !== void 0 ? { formsScriptUrl: opts.formsScriptUrl } : {}
-  });
-  ssrRisks.push(...serverAndDbDepRisks(pkg, true));
-  const deployable = validation.ok && walked.length > 0;
-  const spa = {
-    looksLikeSpa: validation.looksLikeSpa,
-    autoFallback: validation.looksLikeSpa
-  };
-  let suggestedNextAction;
-  if (!deployable) {
-    const firstError = validation.issues.find((i) => i.severity === "error");
-    if (firstError?.code === "missing_index_html") {
-      suggestedNextAction = `No index.html at the root of "${outputDirRel}". Deploy the built static output (the directory whose root contains index.html), not the source project. Build locally first if needed (${buildCommandHint ?? "npm run build"}), then re-run analyze.`;
-    } else {
-      suggestedNextAction = "Fix the listed issues (remove forbidden/secret files, reduce size, add missing entry HTML), then re-run analyze.";
-    }
-  } else if (spa.looksLikeSpa) {
-    suggestedNextAction = `Run deploy to publish the static output in "${outputDirRel}". It looks like a single-page app, so SPA fallback (unknown paths rewrite to index.html) will be enabled automatically; pass spaFallback: false to opt out.`;
-  } else {
-    suggestedNextAction = `Run deploy to publish the static output in "${outputDirRel}".`;
   }
-  return {
-    projectType,
-    ...detection ? { framework: detection.framework } : {},
-    recommendedOutputDir: outputDirRel,
-    outputDirExists: true,
-    ...buildCommandHint !== void 0 ? { buildCommandHint } : {},
-    entryHtmlFound: validation.entryHtmlPath !== void 0,
-    ...validation.htmlLang !== void 0 ? { htmlLang: validation.htmlLang } : {},
-    langSupported: validation.supportedLang !== void 0,
-    totalBytes: validation.totalBytes,
-    fileCount: validation.fileCount,
-    issues: validation.issues,
-    ssrRisks,
-    spa,
-    deployable,
-    suggestedNextAction,
-    ...deployable ? { files: walked.map((f) => ({ path: f.path, size: f.size })) } : {}
-  };
+  await recurse(dir, "");
+  return out;
 }
-
-// src/tools/context.ts
-import {
-  inputRequired
-} from "@modelcontextprotocol/server";
-
-// src/project-binding.ts
-import { fileURLToPath } from "node:url";
-import { isAbsolute as isAbsolute2, resolve as resolve3 } from "node:path";
-
-// src/project-root.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
-import {
-  chmodSync as chmodSync2,
-  existsSync as existsSync2,
-  lstatSync,
-  mkdirSync as mkdirSync2,
-  readFileSync as readFileSync2,
-  realpathSync,
-  renameSync as renameSync2,
-  rmdirSync as rmdirSync2,
-  statSync,
-  unlinkSync,
-  writeFileSync as writeFileSync2
-} from "node:fs";
-import { homedir } from "node:os";
-import { isAbsolute, join as join3, parse, relative, resolve as resolve2, sep as sep2 } from "node:path";
-var SAKUPA_DIR = ".sakupa";
-var PROJECT_FILE = "project.json";
-var PROJECT_SCHEMA_VERSION = 1;
-var ProjectRootError = class extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "ProjectRootError";
-    this.code = code;
+async function readPackageJson(projectDir) {
+  const raw = await readTextIfExists(join4(projectDir, "package.json"));
+  if (raw === null) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === "object" && parsed !== null ? parsed : null;
+  } catch {
+    return null;
   }
-};
-function projectMarkerPath(projectDir) {
-  return join3(projectDir, SAKUPA_DIR, PROJECT_FILE);
 }
-function loadProjectMarker(projectDir) {
-  const path = projectMarkerPath(projectDir);
-  if (!existsSync2(path)) return { kind: "absent" };
-  let parsed;
-  try {
-    parsed = JSON.parse(readFileSync2(path, "utf8"));
-  } catch (error) {
+function allDeps(pkg) {
+  return { ...pkg?.dependencies ?? {}, ...pkg?.devDependencies ?? {} };
+}
+async function anyFileMatches(dir, predicate) {
+  if (!await isDirectory(dir)) return false;
+  const files = await walkFiles(dir, { maxFiles: 2e3 });
+  return files.some((f) => predicate(f.path.split("/").pop() ?? ""));
+}
+async function detectFramework(projectDir, pkg) {
+  const deps = allDeps(pkg);
+  const ssrRisks = [];
+  const nextConfigPath = await firstExistingFile(projectDir, [
+    "next.config.js",
+    "next.config.mjs",
+    "next.config.ts",
+    "next.config.cjs"
+  ]);
+  if ("next" in deps || nextConfigPath !== null) {
+    const config = nextConfigPath ? await readTextIfExists(nextConfigPath) : null;
+    const staticExport = config !== null && /output\s*:\s*['"]export['"]/.test(config);
+    if (!staticExport) {
+      ssrRisks.push(
+        `Next.js project without output: 'export' in next.config.* \u2014 the default Next.js build requires a Node.js server. Sakupa only serves static files; add output: 'export' to next.config.* and build locally to produce a static "out" directory.`
+      );
+    }
+    for (const apiDir of ["pages/api", "src/pages/api"]) {
+      if (await isDirectory(join4(projectDir, apiDir))) {
+        ssrRisks.push(
+          `API routes (${apiDir}/) require a server runtime and will not run on Sakupa. Remove them or move their logic to build time before static export.`
+        );
+        break;
+      }
+    }
+    for (const appDir of ["app", "src/app"]) {
+      if (await anyFileMatches(
+        join4(projectDir, appDir),
+        (base) => /^route\.(ts|js|tsx|jsx|mjs)$/.test(base)
+      )) {
+        ssrRisks.push(
+          `App Router route handlers (${appDir}/**/route.ts|js) require a server runtime and will not run on Sakupa.`
+        );
+        break;
+      }
+    }
+    if (await firstExistingFile(projectDir, [
+      "middleware.ts",
+      "middleware.js",
+      "src/middleware.ts",
+      "src/middleware.js"
+    ]) !== null) {
+      ssrRisks.push("middleware.(ts|js) runs on a server/edge runtime and will not run on Sakupa.");
+    }
     return {
-      kind: "corrupted",
-      problem: `the file cannot be read as JSON (${error instanceof Error ? error.message : String(error)})`
+      framework: "next",
+      outputCandidates: ["out"],
+      buildCommandHint: "npm run build",
+      ssrRisks
     };
   }
-  if (typeof parsed !== "object" || parsed === null) {
-    return { kind: "corrupted", problem: "the file does not contain a JSON object" };
-  }
-  const record = parsed;
-  if (record.schemaVersion !== PROJECT_SCHEMA_VERSION) {
+  const nuxtConfigPath = await firstExistingFile(projectDir, [
+    "nuxt.config.ts",
+    "nuxt.config.js",
+    "nuxt.config.mjs"
+  ]);
+  if ("nuxt" in deps || "nuxt3" in deps || nuxtConfigPath !== null) {
+    for (const serverDir of ["server/api", "server/routes"]) {
+      if (await isDirectory(join4(projectDir, serverDir))) {
+        ssrRisks.push(
+          `Nuxt server handlers (${serverDir}/) require a server runtime and will not run on Sakupa. Use static generation (npx nuxi generate) and deploy .output/public.`
+        );
+      }
+    }
     return {
-      kind: "corrupted",
-      problem: `unsupported schemaVersion ${String(record.schemaVersion)}`
+      framework: "nuxt",
+      outputCandidates: [".output/public", "dist"],
+      buildCommandHint: "npm run generate (or npx nuxi generate)",
+      ssrRisks
     };
   }
-  if (typeof record.projectId !== "string" || !isUuid(record.projectId)) {
-    return { kind: "corrupted", problem: "projectId is missing or is not a UUID" };
-  }
-  if (typeof record.createdAt !== "string" || !Number.isFinite(Date.parse(record.createdAt))) {
-    return { kind: "corrupted", problem: "createdAt is missing or invalid" };
-  }
-  if (record.outputDir !== void 0 && (typeof record.outputDir !== "string" || !isSafeRelativeOutput(record.outputDir))) {
-    return { kind: "corrupted", problem: "outputDir is not a safe project-relative path" };
+  const astroConfigPath = await firstExistingFile(projectDir, [
+    "astro.config.mjs",
+    "astro.config.js",
+    "astro.config.ts"
+  ]);
+  if ("astro" in deps || astroConfigPath !== null) {
+    const config = astroConfigPath ? await readTextIfExists(astroConfigPath) : null;
+    if (config !== null && /output\s*:\s*['"]server['"]/.test(config)) {
+      ssrRisks.push(
+        "Astro config sets output: 'server' (SSR). Sakupa only serves static files; use the default static output (or output: 'static') and build locally."
+      );
+    }
+    return {
+      framework: "astro",
+      outputCandidates: ["dist"],
+      buildCommandHint: "npm run build",
+      ssrRisks
+    };
   }
-  return {
-    kind: "ok",
-    marker: {
-      schemaVersion: PROJECT_SCHEMA_VERSION,
-      projectId: record.projectId,
-      createdAt: record.createdAt,
-      ...record.outputDir !== void 0 ? { outputDir: normalizeRelative(record.outputDir) } : {}
+  if ("@sveltejs/kit" in deps) {
+    if ("@sveltejs/adapter-node" in deps) {
+      ssrRisks.push(
+        "SvelteKit is configured with @sveltejs/adapter-node, which produces a Node.js server. Sakupa only serves static files; switch to @sveltejs/adapter-static and rebuild."
+      );
+    } else if (!("@sveltejs/adapter-static" in deps)) {
+      ssrRisks.push(
+        "SvelteKit requires @sveltejs/adapter-static to produce a fully static build. Install and configure it, then build locally."
+      );
     }
-  };
-}
-function initializeProject(projectDir) {
-  const canonical = canonicalProjectDirectory(projectDir);
-  assertSafeProjectRoot(canonical);
-  const current = loadProjectMarker(canonical);
-  if (current.kind === "corrupted") {
-    throw new ProjectRootError(
-      "corrupted_marker",
-      `Refusing to overwrite damaged Sakupa project marker ${projectMarkerPath(canonical)}: ${current.problem}.`
-    );
+    if (await anyFileMatches(join4(projectDir, "src/routes"), (base) => base.startsWith("+server."))) {
+      ssrRisks.push(
+        "SvelteKit +server.* endpoint files require a server runtime and will not run on Sakupa."
+      );
+    }
+    return {
+      framework: "sveltekit",
+      outputCandidates: ["build"],
+      buildCommandHint: "npm run build",
+      ssrRisks
+    };
   }
-  if (current.kind === "ok") {
+  if ("react-scripts" in deps) {
     return {
-      projectDir: canonical,
-      requestedPath: canonical,
-      markerKind: "project",
-      marker: current.marker
+      framework: "create-react-app",
+      outputCandidates: ["build"],
+      buildCommandHint: "npm run build",
+      ssrRisks
     };
   }
-  const marker = {
-    schemaVersion: PROJECT_SCHEMA_VERSION,
-    projectId: randomUUID2(),
-    createdAt: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  writeMarkerAtomically(canonical, marker);
-  return {
-    projectDir: canonical,
-    requestedPath: canonical,
-    markerKind: "project",
-    marker
-  };
+  const viteConfigPath = await firstExistingFile(projectDir, [
+    "vite.config.ts",
+    "vite.config.js",
+    "vite.config.mjs"
+  ]);
+  if ("vite" in deps || viteConfigPath !== null) {
+    let framework = "vite";
+    if ("vue" in deps) framework = "vue (vite)";
+    else if ("react" in deps) framework = "react (vite)";
+    else if ("svelte" in deps) framework = "svelte (vite)";
+    return {
+      framework,
+      outputCandidates: ["dist"],
+      buildCommandHint: "npm run build",
+      ssrRisks
+    };
+  }
+  return null;
 }
-function resolveLockedProjectRoot(projectDir) {
-  const canonical = canonicalProjectDirectory(projectDir);
-  assertSafeProjectRoot(canonical);
-  const markerState = loadProjectMarker(canonical);
-  if (markerState.kind === "corrupted") {
-    throw new ProjectRootError(
-      "corrupted_marker",
-      `Sakupa project marker ${projectMarkerPath(canonical)} is damaged: ${markerState.problem}.`
-    );
+function serverAndDbDepRisks(pkg, hasStaticOutput) {
+  const deps = allDeps(pkg);
+  const risks = [];
+  for (const name of SERVER_RUNTIME_DEPS) {
+    if (name in deps) {
+      risks.push(
+        hasStaticOutput ? `Warning: dependency "${name}" is a server framework. Sakupa never runs it online \u2014 only the static output is served. Using it locally at build time is fine.` : `Dependency "${name}" is a server framework. Sakupa does not host server runtimes; only prebuilt static output can be deployed.`
+      );
+    }
   }
-  if (markerState.kind === "absent") {
-    throw new ProjectRootError(
-      "not_initialized",
-      `The MCP working directory ${canonical} is not initialized. Call the init MCP tool with no path argument. If help confirms that this client has no MCP Roots, the AI may run \`npx -y @sakupa/mcp@latest init\` itself as the fallback.`
-    );
+  for (const name of DB_RUNTIME_DEPS) {
+    if (name in deps) {
+      risks.push(
+        hasStaticOutput ? `Warning: dependency "${name}" is a database/runtime client. Sakupa never runs it online \u2014 using a database locally at build time to generate static pages is fine.` : `Dependency "${name}" is a database/runtime client. Sakupa does not host databases or server runtimes; generate static pages locally and deploy only the output.`
+      );
+    }
   }
-  return {
-    projectDir: canonical,
-    requestedPath: canonical,
-    markerKind: "project",
-    marker: markerState.marker
-  };
+  return risks;
 }
-function updateProjectOutputDir(projectDir, outputDir) {
-  const canonical = canonicalProjectDirectory(projectDir);
-  const state = loadProjectMarker(canonical);
-  if (state.kind !== "ok") {
-    throw new ProjectRootError(
-      state.kind === "corrupted" ? "corrupted_marker" : "not_initialized",
-      state.kind === "corrupted" ? `Cannot update damaged Sakupa project marker: ${state.problem}.` : `No Sakupa project marker exists in ${canonical}.`
-    );
-  }
-  if (!isSafeRelativeOutput(outputDir)) {
-    throw new ProjectRootError(
-      "unsafe_path",
-      `Output directory "${outputDir}" must stay inside the initialized Sakupa project.`
-    );
+async function scanForUseServer(projectDir, skipRelDirs) {
+  const files = await walkFiles(projectDir, { maxFiles: USE_SERVER_SCAN_MAX_FILES, skipRelDirs });
+  let scanned = 0;
+  for (const file of files) {
+    if (scanned >= USE_SERVER_SCAN_MAX_FILES) break;
+    if (!SOURCE_SCAN_EXTENSIONS.has(extensionOf(file.path))) continue;
+    scanned += 1;
+    const text2 = await readTextIfExists(join4(projectDir, file.path), USE_SERVER_SCAN_MAX_BYTES);
+    if (text2 !== null && /['"]use server['"]/.test(text2)) return true;
   }
-  const marker = {
-    ...state.marker,
-    outputDir: normalizeRelative(outputDir)
-  };
-  writeMarkerAtomically(canonical, marker);
-  return marker;
+  return false;
 }
-function deleteProjectMarker(projectDir) {
-  const path = projectMarkerPath(projectDir);
-  if (existsSync2(path)) unlinkSync(path);
-  try {
-    rmdirSync2(join3(projectDir, SAKUPA_DIR));
-  } catch {
+function normalizeOutputDir(outputDir) {
+  const normalized = posix.normalize(outputDir.replaceAll(sep2, "/")).replace(/\/+$/, "");
+  return normalized === "" ? "." : normalized;
+}
+async function analyzeProject(projectDir, opts = {}) {
+  const root = await fs.realpath(resolve2(projectDir));
+  const pkg = await readPackageJson(root);
+  const detection = await detectFramework(root, pkg);
+  const ssrRisks = [...detection?.ssrRisks ?? []];
+  const hasBuildScript = typeof pkg?.scripts?.["build"] === "string";
+  const buildRequired = detection !== null || hasBuildScript;
+  let outputDirRel;
+  let outputDirExists = false;
+  if (opts.outputDir !== void 0) {
+    outputDirRel = normalizeOutputDir(opts.outputDir);
+    const abs = resolve2(root, outputDirRel);
+    if (abs !== root && !abs.startsWith(root + sep2)) {
+      outputDirRel = ".";
+      outputDirExists = false;
+    } else {
+      outputDirExists = await isDirectory(abs) || outputDirRel === "." && await isDirectory(root);
+      if (outputDirExists) {
+        try {
+          const physical = await fs.realpath(abs);
+          if (physical !== root && !physical.startsWith(root + sep2)) {
+            outputDirExists = false;
+          }
+        } catch {
+          outputDirExists = false;
+        }
+      }
+    }
+  } else if (detection) {
+    for (const candidate of detection.outputCandidates) {
+      if (await isDirectory(join4(root, candidate))) {
+        outputDirRel = candidate;
+        outputDirExists = true;
+        break;
+      }
+    }
+    if (outputDirRel === void 0) {
+      outputDirRel = detection.outputCandidates[0] ?? "dist";
+      outputDirExists = false;
+    }
+  } else if (!buildRequired) {
+    outputDirRel = ".";
+    outputDirExists = true;
+  } else if (hasBuildScript) {
+    for (const candidate of ["dist", "build", "out", "public"]) {
+      if (await isFile(join4(root, candidate, "index.html"))) {
+        outputDirRel = candidate;
+        outputDirExists = true;
+        break;
+      }
+    }
   }
-}
-function canonicalProjectDirectory(path) {
-  const canonical = canonicalExistingPath(resolve2(path));
-  if (!statSync(canonical).isDirectory()) {
-    throw new ProjectRootError("invalid_path", `Project path ${canonical} is not a directory.`);
+  const projectType = detection ? "framework" : outputDirRel !== void 0 && !buildRequired ? "plain-static" : "unknown";
+  const buildCommandHint = detection ? detection.buildCommandHint : hasBuildScript ? "npm run build" : void 0;
+  if (pkg !== null && buildRequired) {
+    const skip = /* @__PURE__ */ new Set();
+    if (outputDirRel !== void 0 && outputDirRel !== ".") skip.add(outputDirRel);
+    if (await scanForUseServer(root, skip)) {
+      ssrRisks.push(
+        "Source files contain 'use server' directives (server actions). Server actions require a server runtime and will not run on Sakupa."
+      );
+    }
   }
-  return canonical;
-}
-function canonicalExistingPath(path) {
-  try {
-    const stat2 = lstatSync(path, { throwIfNoEntry: false });
-    if (!stat2) {
-      throw new ProjectRootError("invalid_path", `Project path ${path} does not exist.`);
+  if (outputDirRel === void 0 || !outputDirExists) {
+    ssrRisks.push(...serverAndDbDepRisks(pkg, false));
+    const sourceWithoutBuild = pkg !== null && buildRequired && (await isDirectory(join4(root, "src")) || await isDirectory(join4(root, "pages")));
+    let suggestedNextAction2;
+    if (opts.outputDir !== void 0) {
+      suggestedNextAction2 = `The requested output directory "${opts.outputDir}" does not exist. Build the project locally first (${buildCommandHint ?? "npm run build"}) or pass the correct directory, then re-run analyze.`;
+    } else if (ssrRisks.length > 0 && detection) {
+      suggestedNextAction2 = `This ${detection.framework} project appears to require a server runtime (see ssrRisks) and no static output directory was found. Convert it to static output (e.g. Next.js output: 'export', Nuxt generate, Astro static, SvelteKit adapter-static), run the build locally (${buildCommandHint ?? "npm run build"}), then re-run analyze.`;
+    } else if (sourceWithoutBuild || detection && !outputDirExists) {
+      suggestedNextAction2 = `This looks like a source project, not built static output. Run the build locally (${buildCommandHint ?? "npm run build"}) then re-run analyze.`;
+    } else {
+      suggestedNextAction2 = "No deployable static output was found. Create an index.html (or build the project locally so a static output directory exists), then re-run analyze.";
     }
-    return realpathSync(path);
-  } catch (error) {
-    if (error instanceof ProjectRootError) throw error;
-    throw new ProjectRootError(
-      "invalid_path",
-      `Project path ${path} cannot be resolved (${error instanceof Error ? error.message : String(error)}).`
-    );
+    return {
+      projectType,
+      ...detection ? { framework: detection.framework } : {},
+      ...outputDirRel !== void 0 ? { recommendedOutputDir: outputDirRel } : {},
+      outputDirExists: false,
+      ...buildCommandHint !== void 0 ? { buildCommandHint } : {},
+      entryHtmlFound: false,
+      langSupported: false,
+      totalBytes: 0,
+      fileCount: 0,
+      issues: [],
+      ssrRisks,
+      spa: { looksLikeSpa: false, autoFallback: false },
+      deployable: false,
+      suggestedNextAction: suggestedNextAction2
+    };
   }
-}
-function assertSafeProjectRoot(projectDir) {
-  if (parse(projectDir).root === projectDir || projectDir === realpathSync(homedir())) {
-    throw new ProjectRootError(
-      "unsafe_path",
-      `Refusing to use ${projectDir} as a Sakupa project root; choose a specific project directory.`
-    );
+  const outputAbs = outputDirRel === "." ? root : resolve2(root, outputDirRel);
+  const walked = await walkFiles(outputAbs, { maxFiles: MAX_FILE_COUNT + 1 });
+  const candidates = [];
+  for (const file of walked) {
+    const ext = extensionOf(file.path);
+    let content;
+    if (TEXT_CONTENT_EXTENSIONS.has(ext) && file.size <= CONTENT_READ_MAX_BYTES) {
+      try {
+        content = new Uint8Array(await fs.readFile(join4(outputAbs, file.path)));
+      } catch {
+        content = void 0;
+      }
+    }
+    candidates.push({ path: file.path, size: file.size, ...content ? { content } : {} });
   }
-}
-function isUuid(value) {
-  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
-}
-function normalizeRelative(path) {
-  const normalized = path.split(sep2).join("/").replace(/^\.\//, "").replace(/\/$/, "");
-  return normalized.length === 0 ? "." : normalized;
-}
-function isSafeRelativeOutput(path) {
-  if (path.length === 0 || isAbsolute(path)) return false;
-  const normalized = normalizeRelative(path);
-  if (normalized === ".") return true;
-  const rel = relative("/sakupa-root", resolve2("/sakupa-root", normalized));
-  return rel !== ".." && !rel.startsWith(`..${sep2}`) && !isAbsolute(rel);
-}
-function writeMarkerAtomically(projectDir, marker) {
-  const dir = join3(projectDir, SAKUPA_DIR);
-  mkdirSync2(dir, { recursive: true, mode: 448 });
-  const path = projectMarkerPath(projectDir);
-  const temporary = `${path}.${process.pid}.${randomUUID2()}.tmp`;
-  try {
-    writeFileSync2(temporary, `${JSON.stringify(marker, null, 2)}
-`, {
-      encoding: "utf8",
-      mode: 384
-    });
-    renameSync2(temporary, path);
-    try {
-      chmodSync2(path, 384);
-    } catch {
+  const validation = validateDeployableFiles(candidates, {
+    mode: "free",
+    ...opts.formsScriptUrl !== void 0 ? { formsScriptUrl: opts.formsScriptUrl } : {}
+  });
+  ssrRisks.push(...serverAndDbDepRisks(pkg, true));
+  const deployable = validation.ok && walked.length > 0;
+  const spa = {
+    looksLikeSpa: validation.looksLikeSpa,
+    autoFallback: validation.looksLikeSpa
+  };
+  let suggestedNextAction;
+  if (!deployable) {
+    const firstError = validation.issues.find((i) => i.severity === "error");
+    if (firstError?.code === "missing_index_html") {
+      suggestedNextAction = `No index.html at the root of "${outputDirRel}". Deploy the built static output (the directory whose root contains index.html), not the source project. Build locally first if needed (${buildCommandHint ?? "npm run build"}), then re-run analyze.`;
+    } else {
+      suggestedNextAction = "Fix the listed issues (remove forbidden/secret files, reduce size, add missing entry HTML), then re-run analyze.";
     }
-  } finally {
-    if (existsSync2(temporary)) unlinkSync(temporary);
+  } else if (spa.looksLikeSpa) {
+    suggestedNextAction = `Run deploy to publish the static output in "${outputDirRel}". It looks like a single-page app, so SPA fallback (unknown paths rewrite to index.html) will be enabled automatically; pass spaFallback: false to opt out.`;
+  } else {
+    suggestedNextAction = `Run deploy to publish the static output in "${outputDirRel}".`;
   }
+  return {
+    projectType,
+    ...detection ? { framework: detection.framework } : {},
+    recommendedOutputDir: outputDirRel,
+    outputDirExists: true,
+    ...buildCommandHint !== void 0 ? { buildCommandHint } : {},
+    entryHtmlFound: validation.entryHtmlPath !== void 0,
+    ...validation.htmlLang !== void 0 ? { htmlLang: validation.htmlLang } : {},
+    langSupported: validation.supportedLang !== void 0,
+    totalBytes: validation.totalBytes,
+    fileCount: validation.fileCount,
+    issues: validation.issues,
+    ssrRisks,
+    spa,
+    deployable,
+    suggestedNextAction,
+    ...deployable ? { files: walked.map((f) => ({ path: f.path, size: f.size })) } : {}
+  };
 }
 
+// src/tools/context.ts
+import {
+  inputRequired
+} from "@modelcontextprotocol/server";
+
 // src/project-binding.ts
+import { fileURLToPath } from "node:url";
+import { isAbsolute as isAbsolute2, resolve as resolve3 } from "node:path";
 var MCP_ROOTS_TIMEOUT_MS = 5e3;
 var McpRootsPending = class extends Error {
   constructor() {
@@ -2466,7 +2655,7 @@ function timestampForAgentInZone(exactTimestamp, clientTimeZone) {
 }
 
 // src/tools/context.ts
-import { randomUUID as randomUUID3 } from "node:crypto";
+import { randomUUID as randomUUID4 } from "node:crypto";
 var LocalGuidanceError = class extends SakupaError {
   constructor(code, message) {
     super(code, message);
@@ -2551,7 +2740,7 @@ function reportAuthorizationStore(ctx) {
   return store;
 }
 function issueReportAuthorization(ctx, failedTool) {
-  const token = randomUUID3();
+  const token = randomUUID4();
   reportAuthorizationStore(ctx).set(token, {
     failedTool,
     expiresAt: Date.now() + 10 * 60 * 1e3
@@ -2584,7 +2773,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() } });
@@ -2658,15 +2847,15 @@ function toolError(e) {
 }
 
 // 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/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 isAbsolute3, join as join4, relative as relative2, resolve as resolve4, sep as sep3 } from "node:path";
+import { dirname as dirname2, isAbsolute as isAbsolute3, join as join5, relative as relative2, resolve as resolve4, sep as sep3 } from "node:path";
 
 // ../../node_modules/fflate/esm/index.mjs
 import { createRequire } from "module";
@@ -3166,7 +3355,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;
@@ -3208,7 +3397,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
@@ -3226,7 +3415,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;
   }
@@ -3277,13 +3466,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(resolve4(input.projectDir), ".sakupa-restore-"));
+  const tempDir = await mkdtemp(join5(resolve4(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;
@@ -3309,19 +3498,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")
@@ -3332,8 +3521,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) {
@@ -3377,28 +3566,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 randomUUID4 } from "node:crypto";
-import { homedir as homedir3 } from "node:os";
-import { dirname as dirname4, join as join6 } from "node:path";
+import { randomUUID as randomUUID5 } 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;
@@ -3420,15 +3609,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 = randomUUID4();
+      const token = randomUUID5();
       const fd2 = openSync(path, "wx", 384);
-      writeFileSync4(
+      writeFileSync5(
         fd2,
         JSON.stringify({ token, pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() })
       );
@@ -3453,11 +3642,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");
     }
@@ -3471,14 +3660,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];
@@ -3499,8 +3688,8 @@ async function ensureDeviceBinding(client, apiBaseUrl) {
     let pending = registry.pendingRegistrations[apiBaseUrl];
     if (!pending) {
       pending = {
-        operationId: randomUUID4(),
-        deviceId: randomUUID4(),
+        operationId: randomUUID5(),
+        deviceId: randomUUID5(),
         credential: generateCredential(),
         createdAt: (/* @__PURE__ */ new Date()).toISOString()
       };
@@ -3532,15 +3721,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 isAbsolute4, join as join7 } from "node:path";
+import { dirname as dirname5, isAbsolute as isAbsolute4, join as join8 } from "node:path";
 var HANDOFF_LOCK_TTL_MS = 15 * 60 * 1e3;
 function normalizeSiteUrl(raw) {
   const url = new URL(raw);
@@ -3596,12 +3785,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 {
@@ -3615,7 +3804,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);
@@ -3796,26 +3985,26 @@ ${diag.layers}
 
 // 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 randomUUID5 } from "node:crypto";
-import { join as join8 } from "node:path";
+import { randomUUID as randomUUID6 } 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",
@@ -3862,28 +4051,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-${randomUUID5()}.tmp`);
-  writeFileSync6(temporary, `${JSON.stringify(file, null, 2)}
+  const temporary = join9(directory, `.rotation-${randomUUID6()}.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) {
@@ -4318,7 +4507,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;
@@ -4337,7 +4526,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",
@@ -4482,14 +4671,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 [];
@@ -4642,7 +4831,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(
@@ -4670,8 +4859,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
@@ -5336,7 +5525,7 @@ ${JSON.stringify(finalized.warnings, null, 2)}
           {
             siteId: site.siteId,
             plan: args.plan,
-            idempotencyKey: randomUUID6()
+            idempotencyKey: randomUUID7()
           },
           site.credential
         );
@@ -5659,11 +5848,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(
@@ -5712,6 +5903,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(
@@ -6271,7 +6595,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",
@@ -6464,11 +6788,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",
@@ -6566,7 +6892,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",
@@ -7392,7 +7718,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(),
@@ -7454,7 +7780,7 @@ function registerDeleteTools(server, baseCtx) {
             resultCode: result.alreadyDeleted ? "site_already_deleted" : "site_deleted",
             summary: summaryMarkdown({
               title: result.alreadyDeleted ? "Site was already deleted" : "Site deleted",
-              lead: `${site.url ?? site.siteId} no longer serves anything (visitors get HTTP 410). The local credential file .sakupa/site.json was removed; this project is no longer bound to any site.`,
+              lead: `${site.url ?? site.siteId} no longer serves anything (visitors get a not-found page, HTTP 404). The local credential file .sakupa/site.json was removed; this project is no longer bound to any site.`,
               facts: [
                 ["Site ID", result.siteId],
                 ["Public URL released", site.url],
@@ -7479,7 +7805,7 @@ function registerDeleteTools(server, baseCtx) {
             nextActions: []
           });
         }
-        const operationId = randomUUID7();
+        const operationId = randomUUID8();
         const preview = await ctx.client.previewDeleteSite(site.siteId, site.credential, {
           operationId
         });
@@ -7563,7 +7889,7 @@ function registerDeleteTools(server, baseCtx) {
               label: `Delete ${site.url ?? site.siteId}`,
               description: "Remove the site, its content, apps and submissions, and release the URL.",
               consequences: [
-                "Visitors get HTTP 410 immediately.",
+                "Visitors get a not-found page (HTTP 404) immediately.",
                 "The local credential file is removed; this project is unbound."
               ],
               tool: "delete",
@@ -7590,8 +7916,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
@@ -7613,6 +7940,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.
@@ -7706,7 +8035,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
@@ -7719,8 +8048,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;
@@ -7825,10 +8156,13 @@ export {
   TEST_API_BASE_URL,
   analyzeProject,
   createSakupaMcpServer,
+  credentialStoreDirectory,
+  credentialStorePath,
   deleteSiteFile,
   environmentFor,
   loadMcpRuntimeConfig,
   loadSiteFile,
+  readStoredCredential,
   registerTools,
   requireSiteFile,
   siteFilePath,