create-thally-docs 0.10.62 → 0.10.65

package/README.md

@@ -66,6 +66,12 @@ projected into Thally. A live Mintlify URL uses the structured configuration
 embedded by Mintlify when it is available, with bounded same-site crawling as a
 fallback.
 
+Migrated OpenAPI specs are written to `openapi/`, not `public/` (which the host
+serves as-is). `--into` never deletes files: an older copy of a spec already in
+`public/` stays publicly downloadable (a `public/openapi.json` even answers
+`/openapi.json` in place of the filtered spec), so the migration lists such files and
+`thally check` warns about them until you delete them manually.
+
 Repository-local JSX/TSX components and supported static dependencies are copied
 into the customer-owned MDX registry. Simple interactive HTML blocks are moved
 into client components, and locale/root routing is normalized. Unsupported

package/dist/{chunk-ND33X4NN.js → chunk-BNVHCZWS.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   STABLE_SCAFFOLD_RELEASE
-} from "./chunk-I6IIZGQY.js";
+} from "./chunk-MSCEHMMG.js";
 
 // src/starter-sync.ts
 import { createHash } from "crypto";

package/dist/{chunk-SLDENDOT.js → chunk-KCBUOBEF.js}

@@ -5,7 +5,7 @@ import {
 } from "./chunk-XYRM4GAT.js";
 import {
   downloadStarter
-} from "./chunk-UX57AKM4.js";
+} from "./chunk-UBIX5ISG.js";
 
 // src/scaffold.ts
 import { existsSync, mkdirSync, readdirSync } from "fs";

package/dist/{chunk-I6IIZGQY.js → chunk-MSCEHMMG.js}

@@ -3,19 +3,19 @@
 // src/stable-scaffold-release.json
 var stable_scaffold_release_default = {
   schemaVersion: 1,
-  id: "2026-09-29.5b063972.7f16574b",
+  id: "2026-09-30.f7cdf474.f4a15647",
   source: {
     repository: "thallylabs/starter",
-    commitSha: "5b0639728efe2b6a16ac93d3166e499c959e976b",
-    treeSha: "251a4f91ad6deda5a4c3e257b067c3b7f74a5c00",
-    archiveUrl: "https://codeload.github.com/thallylabs/starter/tar.gz/5b0639728efe2b6a16ac93d3166e499c959e976b",
+    commitSha: "f7cdf47487d58aaa0587d16bda1a4292ac7c8580",
+    treeSha: "0306927e5906195c4f8ec5174b0a661d4a29bd21",
+    archiveUrl: "https://codeload.github.com/thallylabs/starter/tar.gz/f7cdf47487d58aaa0587d16bda1a4292ac7c8580",
     manifestPath: "starter-release.json",
-    manifestSha256: "ad9eafe8a243eb23670ca39a314cda7843b3e6da809f9a3cd1c49bd80f44848d"
+    manifestSha256: "ff505eb5f628cc3a7d09fd605ae5c5afc2301f65c74394abf88ddf7aeef3584f"
   },
   runtime: {
     repository: "thallylabs/thally",
-    commitSha: "7f16574beefb0fdd91bc5bdaa322d3e7dc527c61",
-    treeSha: "e046affbd74d72e7a6c041361ec3418d4fd95120",
+    commitSha: "f4a1564759c049bd82226c769485ead66817c78d",
+    treeSha: "1680f037c03f6b41c2a564f00983a7e2a084c87d",
     contentSource: "assets",
     identityContractVersion: 1
   },
@@ -24,6 +24,26 @@ var stable_scaffold_release_default = {
 
 // src/previous-scaffold-releases.json
 var previous_scaffold_releases_default = [
+  {
+    schemaVersion: 1,
+    id: "2026-09-29.5b063972.7f16574b",
+    source: {
+      repository: "thallylabs/starter",
+      commitSha: "5b0639728efe2b6a16ac93d3166e499c959e976b",
+      treeSha: "251a4f91ad6deda5a4c3e257b067c3b7f74a5c00",
+      archiveUrl: "https://codeload.github.com/thallylabs/starter/tar.gz/5b0639728efe2b6a16ac93d3166e499c959e976b",
+      manifestPath: "starter-release.json",
+      manifestSha256: "ad9eafe8a243eb23670ca39a314cda7843b3e6da809f9a3cd1c49bd80f44848d"
+    },
+    runtime: {
+      repository: "thallylabs/thally",
+      commitSha: "7f16574beefb0fdd91bc5bdaa322d3e7dc527c61",
+      treeSha: "e046affbd74d72e7a6c041361ec3418d4fd95120",
+      contentSource: "assets",
+      identityContractVersion: 1
+    },
+    starterVersion: 2
+  },
   {
     schemaVersion: 1,
     id: "2026-09-28.b0612637.c9291377",

package/dist/{chunk-NNT7JTC2.js → chunk-TPPRBG4B.js}

@@ -5,12 +5,12 @@ import {
   readDocsJson,
   scaffold,
   writeDocsJson
-} from "./chunk-SLDENDOT.js";
+} from "./chunk-KCBUOBEF.js";
 
 // src/migrate/index.ts
-import { existsSync as existsSync3, mkdirSync, mkdtempSync, readFileSync as readFileSync3, rmSync, writeFileSync } from "fs";
+import { existsSync as existsSync3, mkdirSync, mkdtempSync, readFileSync as readFileSync4, rmSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
-import { dirname, isAbsolute, join as join3, relative as relative2, resolve, sep } from "path";
+import { basename, dirname, isAbsolute, join as join4, relative as relative3, resolve, sep } from "path";
 import {
   cloneGitHubRepository,
   hydrateRemoteApiSpecs,
@@ -20,18 +20,98 @@ import {
   renderMigrationFiles
 } from "@thallylabs/migrate";
 
+// src/public-specs.ts
+import { lstatSync, readFileSync, readdirSync, statSync } from "fs";
+import { join, relative } from "path";
+import { parse as parseYaml } from "yaml";
+var OPENAPI_METHODS = ["get", "post", "put", "patch", "delete", "options", "head", "trace"];
+var SPEC_EXTENSIONS = /\.(?:json|ya?ml)$/i;
+var MAX_SPEC_BYTES = 1e7;
+var MAX_DEPTH = 8;
+var MAX_ENTRIES = 5e3;
+function shadowNote(urlPath) {
+  return urlPath === "openapi.json" || urlPath === "openapi.yaml" ? ` It is also served at /${urlPath} in place of the filtered specification, so visitors get this raw file there.` : "";
+}
+var isFlagged = (value) => value === true || value === "true";
+function specHasHiddenOperations(spec, overrides) {
+  if (overrides && typeof overrides === "object" && Object.values(overrides).some((o) => o?.hidden === true)) return true;
+  const components = spec.components;
+  for (const group of [spec.paths, spec.webhooks, spec["x-webhooks"], components?.pathItems]) {
+    if (!group || typeof group !== "object") continue;
+    for (const item of Object.values(group)) {
+      if (!item || typeof item !== "object") continue;
+      const record = item;
+      if (isFlagged(record["x-excluded"]) || isFlagged(record["x-hidden"])) return true;
+      for (const method of OPENAPI_METHODS) {
+        const op = record[method];
+        if (op && typeof op === "object" && (isFlagged(op["x-excluded"]) || isFlagged(op["x-hidden"]))) return true;
+      }
+    }
+  }
+  return false;
+}
+function findPublicSpecs(projectDir) {
+  const publicDir = join(projectDir, "public");
+  const scan = { specs: [], skipped: [] };
+  let seen = 0;
+  const walk = (dir, depth) => {
+    let entries;
+    try {
+      entries = readdirSync(dir).sort();
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (++seen > MAX_ENTRIES) return;
+      const full = join(dir, entry);
+      let stat;
+      try {
+        stat = lstatSync(full);
+        if (stat.isSymbolicLink()) {
+          const target = statSync(full);
+          if (!target.isFile()) continue;
+          stat = target;
+        }
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        if (depth < MAX_DEPTH && entry !== "node_modules") walk(full, depth + 1);
+        continue;
+      }
+      if (!stat.isFile() || !SPEC_EXTENSIONS.test(entry)) continue;
+      const urlPath = relative(publicDir, full).split(/[\\/]/).join("/");
+      if (stat.size > MAX_SPEC_BYTES) {
+        scan.skipped.push(`public/${urlPath}`);
+        continue;
+      }
+      try {
+        const raw = readFileSync(full, "utf8");
+        const parsed = /\.json$/i.test(entry) ? JSON.parse(raw) : parseYaml(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+        const spec = parsed;
+        if (typeof spec.openapi !== "string" && typeof spec.swagger !== "string") continue;
+        scan.specs.push({ path: `public/${urlPath}`, urlPath, hasHiddenOperations: specHasHiddenOperations(spec) });
+      } catch {
+      }
+    }
+  };
+  walk(publicDir, 0);
+  return scan;
+}
+
 // src/migrate/validate.ts
 import { spawnSync } from "child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { join as join2 } from "path";
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
+import { join as join3 } from "path";
 
 // src/check.ts
-import { existsSync, readFileSync, readdirSync, statSync } from "fs";
-import { join, extname, relative } from "path";
+import { existsSync, readFileSync as readFileSync2, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { join as join2, extname, relative as relative2 } from "path";
 import { execFileSync } from "child_process";
 
 // src/frontmatter.ts
-import { parse as parseYaml } from "yaml";
+import { parse as parseYaml2 } from "yaml";
 function parseFrontmatter(raw) {
   const source = raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw;
   const opening = /^---([^\r\n]*)\r?\n/.exec(source);
@@ -46,7 +126,7 @@ function parseFrontmatter(raw) {
   if (matter.trim() === "" || !["", "yaml", "yml"].includes(language)) {
     return { content, data: {} };
   }
-  const parsed = parseYaml(matter);
+  const parsed = parseYaml2(matter);
   return {
     content,
     data: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}
@@ -54,7 +134,57 @@ function parseFrontmatter(raw) {
 }
 
 // src/check.ts
-import { parse as parseYaml2 } from "yaml";
+import { parse as parseYaml3 } from "yaml";
+
+// src/openapi-publication.ts
+var METHODS = ["get", "post", "put", "patch", "delete", "options", "head", "trace"];
+var isObj = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var flagged = (value) => value === true || value === "true";
+function parseDocOperation(raw) {
+  if (typeof raw !== "string") return null;
+  const parts = raw.trim().split(/\s+/);
+  if (parts.length < 2) return null;
+  const path = parts.slice(1).join(" ");
+  return path.startsWith("/") ? { method: parts[0].toUpperCase(), path } : null;
+}
+function resolveLocalRef(document, ref) {
+  if (ref !== "#" && !ref.startsWith("#/")) return void 0;
+  let node = document;
+  for (const segment of ref.slice(2).split("/").filter(Boolean)) {
+    if (!isObj(node) && !Array.isArray(node)) return void 0;
+    let decoded = segment;
+    try {
+      decoded = decodeURIComponent(segment);
+    } catch {
+    }
+    node = node[decoded.replace(/~1/g, "/").replace(/~0/g, "~")];
+  }
+  return node;
+}
+function operationState(document, method, path, overrides) {
+  const verb = method.toLowerCase();
+  if (!METHODS.includes(verb) || !isObj(document) || !isObj(document.paths)) return "unknown";
+  const entry = document.paths[path];
+  if (!isObj(entry)) return "unknown";
+  const chain = [entry];
+  const seen = /* @__PURE__ */ new Set([entry]);
+  for (let current = entry; typeof current.$ref === "string"; ) {
+    const target = resolveLocalRef(document, current.$ref);
+    if (!isObj(target) || seen.has(target)) break;
+    seen.add(target);
+    chain.push(target);
+    current = target;
+  }
+  const item = Object.assign({}, ...[...chain].reverse());
+  const operation = item[verb];
+  if (!isObj(operation)) return "unknown";
+  if (chain.some((level) => flagged(level["x-excluded"])) || flagged(operation["x-excluded"])) return "excluded";
+  const override = isObj(overrides) ? overrides[`${verb.toUpperCase()} ${path}`] : void 0;
+  const hidden = isObj(override) && typeof override.hidden === "boolean" ? override.hidden : chain.some((level) => flagged(level["x-hidden"])) || flagged(operation["x-hidden"]);
+  return hidden ? "hidden" : "published";
+}
+
+// src/check.ts
 import { projectNavigationContract } from "@thallylabs/core/navigation";
 import { slugify } from "@thallylabs/core/slugify";
 function gitLocal(projectDir, args) {
@@ -111,14 +241,14 @@ function checkDrift(projectDir, file, data, issues) {
 function scanMdx(dir, results) {
   let entries;
   try {
-    entries = readdirSync(dir);
+    entries = readdirSync2(dir);
   } catch {
     return;
   }
   for (const entry of entries) {
-    const fullPath = join(dir, entry);
+    const fullPath = join2(dir, entry);
     try {
-      const stat = statSync(fullPath);
+      const stat = statSync2(fullPath);
       if (stat.isDirectory()) scanMdx(fullPath, results);
       else if (extname(entry).toLowerCase() === ".mdx") results.push(fullPath);
     } catch {
@@ -294,21 +424,70 @@ function resolveLink(target, redirects, dynamicRedirects = []) {
     current = resolveDynamicRedirectDestination(dynamicMatch.redirect, dynamicMatch.match);
   }
 }
-function validateOpenApi(projectDir, source, issues) {
-  const specPath = source.startsWith("/") ? join(projectDir, "public", source.slice(1)) : join(projectDir, source);
+function checkPublicSpecs(projectDir, tabs, issues) {
+  const configured = tabs.flatMap((tab) => tab.api?.source ? [tab.api.source.replace(/^\.\//, "")] : []);
+  const isConfigured = (spec) => configured.some((source) => source === `/${spec.urlPath}` || source === spec.path);
+  const hasElsewhereSource = configured.some((source) => !/^https?:/i.test(source));
+  const { specs, skipped } = findPublicSpecs(projectDir);
+  for (const spec of specs) {
+    if (isConfigured(spec)) continue;
+    if (!spec.hasHiddenOperations && !hasElsewhereSource) continue;
+    issues.push({
+      severity: "warning",
+      file: spec.path,
+      message: `${spec.path} is an OpenAPI file served publicly as /${spec.urlPath}${spec.hasHiddenOperations ? " and it contains x-excluded/x-hidden operations, which are downloadable from it" : " but is not the spec this site is configured with (an old copy?)"}.${shadowNote(spec.urlPath)} Re-running migration into an existing site does not remove old copies from public/: delete this file manually`
+    });
+  }
+  for (const path of skipped) {
+    issues.push({ severity: "warning", file: path, message: `${path} is too large to inspect; if it is an OpenAPI file with hidden operations it is served as-is from public/` });
+  }
+}
+function checkUnpublishedOperationPages(projectDir, tabs, pages, issues) {
+  const api = tabs.find((tab) => !tab.hidden && tab.api?.source)?.api;
+  const source = api?.source;
+  if (!source || pages.length === 0 || /^https?:/i.test(source)) return;
+  const specPath = source.startsWith("/") ? join2(projectDir, "public", source.slice(1)) : join2(projectDir, source);
+  let spec;
+  try {
+    const raw = readFileSync2(specPath, "utf8");
+    spec = /\.json$/i.test(source) ? JSON.parse(raw) : parseYaml3(raw);
+  } catch {
+    return;
+  }
+  const overrides = api.overrides;
+  for (const { file, method, path } of pages) {
+    const state = operationState(spec, method, path, overrides);
+    if (state === "hidden" || state === "excluded") {
+      issues.push({
+        severity: "warning",
+        file,
+        message: `page ${file} points at ${state} operation ${method} ${path} and is not published: it returns 404 and is left out of navigation, search, sitemap and llms.txt. Publish the operation or point the page at another one`
+      });
+    }
+  }
+}
+function validateOpenApi(projectDir, source, issues, overrides) {
+  const specPath = source.startsWith("/") ? join2(projectDir, "public", source.slice(1)) : join2(projectDir, source);
   if (!existsSync(specPath)) {
     issues.push({ severity: "error", message: `API reference points at "${source}" but the file does not exist`, file: source });
     return;
   }
   let spec;
   try {
-    const raw = readFileSync(specPath, "utf8");
-    spec = source.endsWith(".json") ? JSON.parse(raw) : parseYaml2(raw);
+    const raw = readFileSync2(specPath, "utf8");
+    spec = source.endsWith(".json") ? JSON.parse(raw) : parseYaml3(raw);
   } catch (err) {
     issues.push({ severity: "error", message: `OpenAPI spec is not valid ${source.endsWith(".json") ? "JSON" : "YAML"}: ${err.message}`, file: source });
     return;
   }
   const s = spec;
+  if (s && typeof s === "object" && (source.startsWith("/") || source.replace(/^\.\//, "").startsWith("public/")) && specHasHiddenOperations(s, overrides)) {
+    issues.push({
+      severity: "warning",
+      message: `OpenAPI spec "${source}" lives under public/ and contains x-excluded/x-hidden operations; public/ is served as-is, so those operations would be downloadable.${shadowNote(source.replace(/^\.?\/+/, "").replace(/^public\//, ""))} Move it to a project-root path such as "openapi/${source.split("/").pop()}", update docs.json, and delete the copy in public/ (re-running migration into an existing site does not remove old copies from public/)`,
+      file: source
+    });
+  }
   if (typeof s?.openapi !== "string" && typeof s?.swagger !== "string") {
     issues.push({ severity: "error", message: 'OpenAPI spec is missing the "openapi" (or "swagger") version field', file: source });
   }
@@ -326,7 +505,7 @@ function validateOpenApi(projectDir, source, issues) {
         continue;
       }
       const hasOp = Object.keys(ops).some((k) => methods.has(k.toLowerCase()));
-      if (!hasOp) {
+      if (!hasOp && typeof ops.$ref !== "string") {
         issues.push({ severity: "warning", message: `OpenAPI path "${p}" has no operations`, file: source });
       }
     }
@@ -334,13 +513,13 @@ function validateOpenApi(projectDir, source, issues) {
 }
 async function runCheck(projectDir, options) {
   const { fix, ci } = options;
-  if (!existsSync(join(projectDir, "docs.json"))) {
+  if (!existsSync(join2(projectDir, "docs.json"))) {
     console.error(`
   \u274C Not a Thally project: docs.json not found in ${projectDir}
 `);
     return 1;
   }
-  const contentDir = join(projectDir, "src", "content");
+  const contentDir = join2(projectDir, "src", "content");
   const issues = [];
   const config = readDocsJson(projectDir);
   const secondaryLocales = new Set(
@@ -369,7 +548,7 @@ async function runCheck(projectDir, options) {
     issues.push({ severity: "warning", message: `[duplicate] "${dup}" appears more than once in docs.json` });
   }
   for (const pageId of navPageIds) {
-    const candidates = [join(contentDir, `${pageId}.mdx`), join(contentDir, `${pageId}/index.mdx`)];
+    const candidates = [join2(contentDir, `${pageId}.mdx`), join2(contentDir, `${pageId}/index.mdx`)];
     if (!candidates.some((c) => existsSync(c))) {
       issues.push({ severity: "error", message: `"${pageId}" is in docs.json but has no MDX file`, file: `src/content/${pageId}.mdx` });
     }
@@ -377,6 +556,7 @@ async function runCheck(projectDir, options) {
   const allFiles = [];
   if (existsSync(contentDir)) scanMdx(contentDir, allFiles);
   const fixedOrphans = [];
+  const operationPages = [];
   const validPaths = /* @__PURE__ */ new Set(["/"]);
   const anchorsByPath = /* @__PURE__ */ new Map();
   const linksByFile = [];
@@ -387,13 +567,13 @@ async function runCheck(projectDir, options) {
     let content = "";
     let lineOffset = 0;
     try {
-      const raw = readFileSync(filePath, "utf8");
+      const raw = readFileSync2(filePath, "utf8");
       const parsed = parseFrontmatter(raw);
       data = parsed.data;
       content = parsed.content;
       lineOffset = raw.slice(0, raw.indexOf(content)).split("\n").length - 1;
     } catch {
-      issues.push({ severity: "error", message: `Could not parse frontmatter`, file: relative(projectDir, filePath) });
+      issues.push({ severity: "error", message: `Could not parse frontmatter`, file: relative2(projectDir, filePath) });
       continue;
     }
     const { navPageId } = localizedPage(pageId, secondaryLocales);
@@ -402,15 +582,17 @@ async function runCheck(projectDir, options) {
         addOrphanToNav(projectDir, pageId);
         fixedOrphans.push(pageId);
       } else {
-        issues.push({ severity: "warning", message: `"${pageId}" is not in docs.json nav (orphan)`, file: relative(projectDir, filePath) });
+        issues.push({ severity: "warning", message: `"${pageId}" is not in docs.json nav (orphan)`, file: relative2(projectDir, filePath) });
       }
     }
-    const rel2 = relative(projectDir, filePath);
+    const rel2 = relative2(projectDir, filePath);
     if (!data.title) issues.push({ severity: "warning", message: `Missing "title" in frontmatter`, file: rel2 });
     if (!data.description) issues.push({ severity: "warning", message: `Missing "description" in frontmatter`, file: rel2 });
     if (typeof data.openapi !== "string" && content.trim().length < 50) {
       issues.push({ severity: "warning", message: `Very short body (${content.trim().length} chars) \u2014 page may be empty`, file: rel2 });
     }
+    const operation = parseDocOperation(data.openapi);
+    if (operation) operationPages.push({ file: rel2, ...operation });
     if (options.drift) checkDrift(projectDir, rel2, data, issues);
     const path = pageIdToPath(pageId, secondaryLocales);
     const anchors = extractHeadingAnchors(content);
@@ -454,7 +636,7 @@ async function runCheck(projectDir, options) {
       }
     }
   }
-  const publicDir = join(projectDir, "public");
+  const publicDir = join2(projectDir, "public");
   for (const { file, images, offset } of linksByFile) {
     for (const { target, line: contentLine } of images) {
       const line = contentLine + offset;
@@ -467,14 +649,16 @@ async function runCheck(projectDir, options) {
       } catch {
         continue;
       }
-      if (!existsSync(join(publicDir, decoded))) {
+      if (!existsSync(join2(publicDir, decoded))) {
         issues.push({ severity: "warning", message: `Image not found: "${target}" has no file under public/`, file, line });
       }
     }
   }
   for (const tab of config.tabs) {
-    if (tab.api?.source) validateOpenApi(projectDir, tab.api.source, issues);
+    if (tab.api?.source) validateOpenApi(projectDir, tab.api.source, issues, tab.api.overrides);
   }
+  checkPublicSpecs(projectDir, config.tabs, issues);
+  checkUnpublishedOperationPages(projectDir, config.tabs, operationPages, issues);
   const errors = issues.filter((i) => i.severity === "error");
   options.onIssues?.(issues);
   const warnings = issues.filter((i) => i.severity === "warning");
@@ -544,9 +728,9 @@ async function validateMigration(projectDir, skip = false, installationFailed =
     result.messages.push("Dependency installation failed; production build was not attempted. Review the installation output before retrying.");
     return result;
   }
-  const packagePath = join2(projectDir, "package.json");
+  const packagePath = join3(projectDir, "package.json");
   try {
-    const manifest = existsSync2(packagePath) ? JSON.parse(readFileSync2(packagePath, "utf8")) : void 0;
+    const manifest = existsSync2(packagePath) ? JSON.parse(readFileSync3(packagePath, "utf8")) : void 0;
     if (!manifest?.scripts?.build) {
       result.messages.push("No build script is available; production rendering is not verified.");
       return result;
@@ -568,7 +752,7 @@ async function validateMigration(projectDir, skip = false, installationFailed =
 // src/migrate/index.ts
 function projectPath(projectDir, candidate) {
   const target = resolve(projectDir, candidate);
-  const fromRoot = relative2(resolve(projectDir), target);
+  const fromRoot = relative3(resolve(projectDir), target);
   if (isAbsolute(fromRoot) || fromRoot === ".." || fromRoot.startsWith(`..${sep}`)) {
     throw new Error(`Generated migration path escapes the project: ${candidate}`);
   }
@@ -577,7 +761,7 @@ function projectPath(projectDir, candidate) {
 function readExistingConfig(projectDir) {
   const configPath = projectPath(projectDir, "docs.json");
   if (!existsSync3(configPath)) return void 0;
-  return JSON.parse(readFileSync3(configPath, "utf8"));
+  return JSON.parse(readFileSync4(configPath, "utf8"));
 }
 function resetFreshMigrationContent(projectDir) {
   const contentDirectory = projectPath(projectDir, "src/content");
@@ -600,8 +784,8 @@ async function discoverMigration(options) {
   }
   const source = parseGitHubRepositoryUrl(options.sourceUrl);
   if (options.branch) source.branch = options.branch;
-  const temporaryRoot = mkdtempSync(join3(tmpdir(), "thally-migrate-"));
-  const cloneDir = join3(temporaryRoot, "repository");
+  const temporaryRoot = mkdtempSync(join4(tmpdir(), "thally-migrate-"));
+  const cloneDir = join4(temporaryRoot, "repository");
   console.log(`  \u{1F4E6} Cloning ${source.owner}/${source.repo}...`);
   try {
     const cloneWarnings = [];
@@ -618,6 +802,19 @@ async function discoverMigration(options) {
     rmSync(temporaryRoot, { recursive: true, force: true });
   }
 }
+function publicSpecWarning(projectDir, bundle) {
+  const { specs, skipped } = findPublicSpecs(projectDir);
+  if (specs.length === 0 && skipped.length === 0) return null;
+  const migrated = new Set(bundle.assets.filter((asset) => asset.projectRelative).map((asset) => basename(asset.path)));
+  const lines = [
+    ...specs.map((spec) => `${spec.path}${migrated.has(basename(spec.path)) ? " (same file name as a migrated spec)" : ""}${spec.hasHiddenOperations ? " (contains x-excluded/x-hidden operations)" : ""}${shadowNote(spec.urlPath) ? ` (answers /${spec.urlPath} in place of the filtered specification)` : ""}`),
+    ...skipped.map((path) => `${path} (too large to inspect)`)
+  ];
+  return {
+    code: "unsupported-config",
+    message: `Existing OpenAPI files under public/ are served publicly as-is: ${lines.join("; ")}. Migrated specs are written to openapi/, and re-running migration does not remove old copies from public/. Delete any old copy manually (nothing was deleted), or its hidden operations stay downloadable.`
+  };
+}
 async function migrateDocs(options) {
   const projectDir = resolve(options.projectDir);
   const bundle = await discoverMigration(options);
@@ -647,9 +844,13 @@ async function migrateDocs(options) {
     }
     bundle.docsConfig.i18n ??= { defaultLocale: "en", locales: [{ code: "en", label: "English" }] };
   }
+  if (options.into) {
+    const stale = publicSpecWarning(projectDir, bundle);
+    if (stale) bundle.warnings.unshift(stale);
+  }
   const rendered = renderMigrationFiles(bundle, {
     existingConfig: options.into ? readExistingConfig(projectDir) : void 0,
-    existingComponentRegistry: existsSync3(projectPath(projectDir, "src/mdx/custom-components.tsx")) ? readFileSync3(projectPath(projectDir, "src/mdx/custom-components.tsx"), "utf8") : void 0
+    existingComponentRegistry: existsSync3(projectPath(projectDir, "src/mdx/custom-components.tsx")) ? readFileSync4(projectPath(projectDir, "src/mdx/custom-components.tsx"), "utf8") : void 0
   });
   for (const file of rendered) {
     const destination = projectPath(projectDir, file.path);

package/dist/{chunk-UX57AKM4.js → chunk-UBIX5ISG.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   readStarterReleaseManifest
-} from "./chunk-ND33X4NN.js";
+} from "./chunk-BNVHCZWS.js";
 import {
   STABLE_SCAFFOLD_RELEASE
-} from "./chunk-I6IIZGQY.js";
+} from "./chunk-MSCEHMMG.js";
 
 // src/download.ts
 import { Readable, Transform, pipeline } from "stream";

package/dist/index.js

@@ -3,17 +3,17 @@ import {
   migrateDocs,
   parseFrontmatter,
   runCheck
-} from "./chunk-NNT7JTC2.js";
+} from "./chunk-TPPRBG4B.js";
 import {
   logo,
   scaffold,
   slugify,
   success
-} from "./chunk-SLDENDOT.js";
+} from "./chunk-KCBUOBEF.js";
 import "./chunk-XYRM4GAT.js";
-import "./chunk-UX57AKM4.js";
-import "./chunk-ND33X4NN.js";
-import "./chunk-I6IIZGQY.js";
+import "./chunk-UBIX5ISG.js";
+import "./chunk-BNVHCZWS.js";
+import "./chunk-MSCEHMMG.js";
 
 // src/index.ts
 import { existsSync as existsSync2, readdirSync } from "fs";

package/dist/migrate/index.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import {
   migrateDocs
-} from "../chunk-NNT7JTC2.js";
-import "../chunk-SLDENDOT.js";
+} from "../chunk-TPPRBG4B.js";
+import "../chunk-KCBUOBEF.js";
 import "../chunk-XYRM4GAT.js";
-import "../chunk-UX57AKM4.js";
-import "../chunk-ND33X4NN.js";
-import "../chunk-I6IIZGQY.js";
+import "../chunk-UBIX5ISG.js";
+import "../chunk-BNVHCZWS.js";
+import "../chunk-MSCEHMMG.js";
 export {
   migrateDocs
 };

package/dist/release.js

@@ -3,7 +3,7 @@ import {
   STABLE_SCAFFOLD_RELEASE,
   SUPPORTED_SCAFFOLD_RELEASES,
   isStableScaffoldRelease
-} from "./chunk-I6IIZGQY.js";
+} from "./chunk-MSCEHMMG.js";
 export {
   STABLE_SCAFFOLD_RELEASE,
   SUPPORTED_SCAFFOLD_RELEASES,

package/dist/scaffold.js

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 import {
   scaffold
-} from "./chunk-SLDENDOT.js";
+} from "./chunk-KCBUOBEF.js";
 import "./chunk-XYRM4GAT.js";
 import {
   STARTER_ARCHIVE_ROOT,
   STARTER_COMMIT_SHA,
   STARTER_REPOSITORY,
   validateStarterArchiveEntry
-} from "./chunk-UX57AKM4.js";
-import "./chunk-ND33X4NN.js";
+} from "./chunk-UBIX5ISG.js";
+import "./chunk-BNVHCZWS.js";
 import {
   STABLE_SCAFFOLD_RELEASE
-} from "./chunk-I6IIZGQY.js";
+} from "./chunk-MSCEHMMG.js";
 export {
   STABLE_SCAFFOLD_RELEASE,
   STARTER_ARCHIVE_ROOT,

package/dist/starter-sync.js

@@ -8,8 +8,8 @@ import {
   planStarterRuntimeSync,
   readStarterReleaseManifest,
   starterManifestSha256
-} from "./chunk-ND33X4NN.js";
-import "./chunk-I6IIZGQY.js";
+} from "./chunk-BNVHCZWS.js";
+import "./chunk-MSCEHMMG.js";
 export {
   applyStarterRuntimeSyncPlan,
   classifyStarterPath,

package/dist/starter-update.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   downloadStarter
-} from "./chunk-UX57AKM4.js";
+} from "./chunk-UBIX5ISG.js";
 import {
   applyStarterRuntimeSyncPlan,
   mergeStarterOwnershipContracts,
@@ -9,11 +9,11 @@ import {
   planStarterRuntimeSync,
   readStarterReleaseManifest,
   starterManifestSha256
-} from "./chunk-ND33X4NN.js";
+} from "./chunk-BNVHCZWS.js";
 import {
   STABLE_SCAFFOLD_RELEASE,
   SUPPORTED_SCAFFOLD_RELEASES
-} from "./chunk-I6IIZGQY.js";
+} from "./chunk-MSCEHMMG.js";
 
 // src/starter-update.ts
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-thally-docs",
-  "version": "0.10.62",
+  "version": "0.10.65",
   "description": "Scaffold an open-source Thally docs site for people, search engines, and AI tools.",
   "type": "module",
   "engines": {
@@ -45,7 +45,7 @@
     "@anthropic-ai/sdk": "^0.36.0",
     "@inquirer/prompts": "^7.0.0",
     "@thallylabs/core": "0.2.9",
-    "@thallylabs/migrate": "0.2.12",
+    "@thallylabs/migrate": "0.2.14",
     "p-limit": "^6.1.0",
     "tar": "^7.5.22",
     "yaml": "^2.6.0"