create-thally-docs 0.10.23 → 0.10.26

package/README.md

@@ -1,10 +1,9 @@
 # create-thally-docs
 
-Scaffold the first customer-facing knowledge surface in a
-[Thally](https://github.com/thallylabs/thally) product-knowledge pipeline. The
-result is an open documentation site that serves every page to humans as
-polished HTML and to agents as structured JSON, JSON-LD, and Markdown from the
-same URL.
+Scaffold an open-source [Thally](https://github.com/thallylabs/thally) docs
+site for people, search engines, and AI tools. The result keeps your source in
+Git and publishes each page as HTML, Markdown, structured JSON, JSON-LD, and
+agent discovery files.
 
 ## Quick start
 

package/dist/{chunk-FCGVK2SJ.js → chunk-2RWSXKSV.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   readStarterReleaseManifest
-} from "./chunk-DMPW77OB.js";
+} from "./chunk-AC3VR55N.js";
 import {
   STABLE_SCAFFOLD_RELEASE
-} from "./chunk-AJAB2TTJ.js";
+} from "./chunk-3B6CW5VF.js";
 
 // src/download.ts
 import { Readable, Transform, pipeline } from "stream";

package/dist/{chunk-AJAB2TTJ.js → chunk-3B6CW5VF.js}

@@ -3,19 +3,19 @@
 // src/stable-scaffold-release.json
 var stable_scaffold_release_default = {
   schemaVersion: 1,
-  id: "2026-09-02.35ae4423.8aec7e21",
+  id: "2026-09-05.b8a69237.2c73d8c3",
   source: {
     repository: "thallylabs/starter",
-    commitSha: "35ae442319dac8db8b8fd07aa8edb092f571a5c2",
-    treeSha: "d32386bb2de59c0ce40880d0cc9cdadf3ccd8687",
-    archiveUrl: "https://codeload.github.com/thallylabs/starter/tar.gz/35ae442319dac8db8b8fd07aa8edb092f571a5c2",
+    commitSha: "b8a6923724e7dd7d16e75b50531e097a47e77682",
+    treeSha: "4e0426e44b4216e02e3c7dd50a543a7d1b94e959",
+    archiveUrl: "https://codeload.github.com/thallylabs/starter/tar.gz/b8a6923724e7dd7d16e75b50531e097a47e77682",
     manifestPath: "starter-release.json",
-    manifestSha256: "f84917a7558af9058d1b97c8f6c443c5a9f86c4bcf54edc01ba62abce6a4e5d6"
+    manifestSha256: "e1e7962089419a0de68d513c7153555cf388338b25261ed978332abd581b8589"
   },
   runtime: {
     repository: "thallylabs/thally",
-    commitSha: "8aec7e211bc5428b48fac34b8f80dc0168ec4d19",
-    treeSha: "3587a31f3b6faf9f38635ff04c15f1c06721159c",
+    commitSha: "2c73d8c312b290598a4335ef77c9e04d8cbe1b4b",
+    treeSha: "930c8a4974300649852769e4fcdab2798c4b3b79",
     contentSource: "assets",
     identityContractVersion: 1
   },
@@ -24,6 +24,66 @@ var stable_scaffold_release_default = {
 
 // src/previous-scaffold-releases.json
 var previous_scaffold_releases_default = [
+  {
+    schemaVersion: 1,
+    id: "2026-09-02.814f1f54.cef2fe3b",
+    source: {
+      repository: "thallylabs/starter",
+      commitSha: "814f1f54f5a53a129c552941124d81307dc8b048",
+      treeSha: "03f37cd5e7c504f92b517f8b4194f4b9294ed4bf",
+      archiveUrl: "https://codeload.github.com/thallylabs/starter/tar.gz/814f1f54f5a53a129c552941124d81307dc8b048",
+      manifestPath: "starter-release.json",
+      manifestSha256: "46804f563d00e02783c0aa963e5c3dcf932ae11134e2c8f2843faff4fb4e1047"
+    },
+    runtime: {
+      repository: "thallylabs/thally",
+      commitSha: "cef2fe3b11895cf6ce60d17177ac97200f975507",
+      treeSha: "0edafb000e3fb477f0f2eac93e262b4c07127851",
+      contentSource: "assets",
+      identityContractVersion: 1
+    },
+    starterVersion: 2
+  },
+  {
+    schemaVersion: 1,
+    id: "2026-09-02.e29a6539.b84cbc74",
+    source: {
+      repository: "thallylabs/starter",
+      commitSha: "e29a653933aea5c38a24e773e2f174f1e7893930",
+      treeSha: "0b4bc19b79deb3f43a5a2f47de8954f74b0ebdf5",
+      archiveUrl: "https://codeload.github.com/thallylabs/starter/tar.gz/e29a653933aea5c38a24e773e2f174f1e7893930",
+      manifestPath: "starter-release.json",
+      manifestSha256: "ccb4f7e8bf1c4e7b9ba5c5918b627289216e50de7c7500ad34225d1b9e906abd"
+    },
+    runtime: {
+      repository: "thallylabs/thally",
+      commitSha: "b84cbc74161e2103adf7e8abd79b79e09cb34106",
+      treeSha: "30f1d213cb5e4a4b8c61145277be129d6ff07063",
+      contentSource: "assets",
+      identityContractVersion: 1
+    },
+    starterVersion: 2
+  },
+  {
+    schemaVersion: 1,
+    id: "2026-09-02.35ae4423.8aec7e21",
+    source: {
+      repository: "thallylabs/starter",
+      commitSha: "35ae442319dac8db8b8fd07aa8edb092f571a5c2",
+      treeSha: "d32386bb2de59c0ce40880d0cc9cdadf3ccd8687",
+      archiveUrl: "https://codeload.github.com/thallylabs/starter/tar.gz/35ae442319dac8db8b8fd07aa8edb092f571a5c2",
+      manifestPath: "starter-release.json",
+      manifestSha256: "f84917a7558af9058d1b97c8f6c443c5a9f86c4bcf54edc01ba62abce6a4e5d6"
+    },
+    runtime: {
+      repository: "thallylabs/thally",
+      commitSha: "8aec7e211bc5428b48fac34b8f80dc0168ec4d19",
+      treeSha: "3587a31f3b6faf9f38635ff04c15f1c06721159c",
+      contentSource: "assets",
+      identityContractVersion: 1
+    },
+    starterVersion: 2
+  },
   {
     schemaVersion: 1,
     id: "2026-09-02.6754e995.53facc72",

package/dist/{chunk-DMPW77OB.js → chunk-AC3VR55N.js}

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

package/dist/{chunk-JW72Y2YF.js → chunk-BBRZGMM6.js}

@@ -5,7 +5,7 @@ import {
 } from "./chunk-ORUAMPNF.js";
 import {
   downloadStarter
-} from "./chunk-FCGVK2SJ.js";
+} from "./chunk-2RWSXKSV.js";
 
 // src/scaffold.ts
 import { existsSync, mkdirSync, readdirSync } from "fs";

package/dist/{chunk-JWTHIV4D.js → chunk-V5M5JVUF.js}

@@ -3,7 +3,7 @@ import {
   initGit,
   installDeps,
   scaffold
-} from "./chunk-JW72Y2YF.js";
+} from "./chunk-BBRZGMM6.js";
 
 // src/migrate/index.ts
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   migrateDocs
-} from "./chunk-JWTHIV4D.js";
+} from "./chunk-V5M5JVUF.js";
 import {
   logo,
   readDocsJson,
@@ -9,11 +9,11 @@ import {
   slugify,
   success,
   writeDocsJson
-} from "./chunk-JW72Y2YF.js";
+} from "./chunk-BBRZGMM6.js";
 import "./chunk-ORUAMPNF.js";
-import "./chunk-FCGVK2SJ.js";
-import "./chunk-DMPW77OB.js";
-import "./chunk-AJAB2TTJ.js";
+import "./chunk-2RWSXKSV.js";
+import "./chunk-AC3VR55N.js";
+import "./chunk-3B6CW5VF.js";
 
 // src/index.ts
 import { existsSync as existsSync3, readdirSync as readdirSync2 } from "fs";
@@ -204,19 +204,30 @@ import { join, extname, relative } from "path";
 import { execFileSync } from "child_process";
 
 // src/frontmatter.ts
-import matter from "gray-matter";
-var FRONTMATTER_OPTIONS = {
-  engines: {
-    javascript: () => ({}),
-    js: () => ({})
-  }
-};
+import { parse as parseYaml } from "yaml";
 function parseFrontmatter(raw) {
-  return matter(raw, FRONTMATTER_OPTIONS);
+  const source = raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw;
+  const opening = /^---([^\r\n]*)\r?\n/.exec(source);
+  if (!opening || opening[1].startsWith("-")) return { content: source, data: {} };
+  const language = opening[1].trim().toLowerCase();
+  const remainder = source.slice(opening[0].length);
+  const closing = /^---[ \t]*\r?$/m.exec(remainder);
+  const matter = closing ? remainder.slice(0, closing.index) : remainder;
+  let content = closing ? remainder.slice(closing.index + closing[0].length) : "";
+  if (content.startsWith("\r\n")) content = content.slice(2);
+  else if (content.startsWith("\n")) content = content.slice(1);
+  if (matter.trim() === "" || !["", "yaml", "yml"].includes(language)) {
+    return { content, data: {} };
+  }
+  const parsed = parseYaml(matter);
+  return {
+    content,
+    data: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}
+  };
 }
 
 // src/check.ts
-import { parse as parseYaml } from "yaml";
+import { parse as parseYaml2 } from "yaml";
 function gitLocal(projectDir, args2) {
   try {
     const out = execFileSync("git", args2, { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
@@ -297,8 +308,16 @@ function scanMdx(dir, results) {
 }
 function addOrphanToNav(projectDir, pageId) {
   const config = readDocsJson(projectDir);
-  const tab = config.tabs.find((t) => !t.href && !t.api && t.groups && t.groups.length > 0);
-  if (!tab?.groups) return;
+  const tab = config.tabs.find((candidate) => !candidate.href && !candidate.api && (candidate.pages?.length || candidate.groups?.length));
+  if (!tab) return;
+  if (tab.pages) {
+    if (!tab.pages.includes(pageId)) {
+      tab.pages.push(pageId);
+      writeDocsJson(projectDir, config);
+    }
+    return;
+  }
+  if (!tab.groups) return;
   const lastGroup = tab.groups[tab.groups.length - 1];
   const existing = lastGroup.pages.filter((p) => typeof p === "string");
   if (!existing.includes(pageId)) {
@@ -358,7 +377,7 @@ function validateOpenApi(projectDir, source, issues) {
   let spec;
   try {
     const raw = readFileSync(specPath, "utf8");
-    spec = source.endsWith(".json") ? JSON.parse(raw) : parseYaml(raw);
+    spec = source.endsWith(".json") ? JSON.parse(raw) : parseYaml2(raw);
   } catch (err) {
     issues.push({ severity: "error", message: `OpenAPI spec is not valid ${source.endsWith(".json") ? "JSON" : "YAML"}: ${err.message}`, file: source });
     return;
@@ -414,16 +433,18 @@ async function runCheck(projectDir, options) {
   const navPageIds = /* @__PURE__ */ new Set();
   const duplicates = /* @__PURE__ */ new Set();
   for (const tab of config.tabs) {
-    if (tab.href && (!tab.groups || tab.groups.length === 0)) {
+    const hasNavigationNodes = Boolean(tab.pages?.length || tab.groups?.length);
+    if (tab.href && !hasNavigationNodes) {
       if (tab.href.startsWith("/")) navPageIds.add(tab.href.slice(1) || "introduction");
       continue;
     }
-    if (tab.api && tab.api.navigation !== false) continue;
-    if (!tab.groups || tab.groups.length === 0) {
+    if (tab.api && tab.api.navigation !== false && !hasNavigationNodes) continue;
+    if (!hasNavigationNodes) {
       issues.push({ severity: "error", message: `Tab "${tab.tab}" has no groups and no href \u2014 it will render empty` });
       continue;
     }
-    collectNavPageIds(tab.groups.map((g) => g), navPageIds, duplicates);
+    collectNavPageIds(tab.pages ?? [], navPageIds, duplicates);
+    collectNavPageIds(tab.groups ?? [], navPageIds, duplicates);
   }
   for (const dup of duplicates) {
     issues.push({ severity: "warning", message: `[duplicate] "${dup}" appears more than once in docs.json` });
@@ -583,11 +604,11 @@ function getAllPageIds(config) {
   const skippedApiTabs = [];
   const hrefOnlyPages = [];
   for (const tab of config.tabs) {
-    if (tab.api) {
+    if (tab.api && !tab.pages && !tab.groups) {
       skippedApiTabs.push(tab.tab);
       continue;
     }
-    if (!tab.groups && tab.href) {
+    if (!tab.pages && !tab.groups && tab.href) {
       const pageId = tab.href.replace(/^\//, "");
       if (pageId && !seen.has(pageId)) {
         seen.add(pageId);
@@ -596,13 +617,10 @@ function getAllPageIds(config) {
       }
       continue;
     }
-    if (!tab.groups) continue;
-    for (const group of tab.groups) {
-      for (const id of collectPageIds(group.pages)) {
-        if (!seen.has(id)) {
-          seen.add(id);
-          ids.push(id);
-        }
+    for (const id of collectPageIds([...tab.pages ?? [], ...tab.groups ?? []])) {
+      if (!seen.has(id)) {
+        seen.add(id);
+        ids.push(id);
       }
     }
   }
@@ -798,6 +816,91 @@ var valueFlags = /* @__PURE__ */ new Set([
   "--pages",
   "--platform"
 ]);
+var commandFlags = {
+  scaffold: /* @__PURE__ */ new Set(["--help", "-h", "--yes", "-y", "--install", "--no-install"]),
+  migrate: /* @__PURE__ */ new Set([
+    "--help",
+    "-h",
+    "--api-key",
+    "--branch",
+    "--docs-dir",
+    "--into",
+    "--max-pages",
+    "--platform",
+    "--yes",
+    "-y"
+  ]),
+  check: /* @__PURE__ */ new Set(["--help", "-h", "--fix", "--ci", "--external", "--drift"]),
+  translate: /* @__PURE__ */ new Set([
+    "--help",
+    "-h",
+    "--api-key",
+    "--force",
+    "--locale",
+    "--model",
+    "--pages",
+    "--yes",
+    "-y"
+  ])
+};
+var mainHelp = `
+Usage:
+  create-thally-docs [project-dir] [options]
+  create-thally-docs <command> [arguments] [options]
+
+Commands:
+  migrate <source> [output-dir]  Import an existing documentation project
+  check [project-dir]            Validate content and navigation
+  translate [project-dir]        Translate documentation into another locale
+
+Scaffold options:
+  -y, --yes       Accept defaults and skip interactive prompts
+  --install       Install project dependencies after scaffolding
+  --no-install    Skip dependency installation without prompting
+  -h, --help      Show this help
+
+Run create-thally-docs <command> --help for command-specific options.
+`;
+var commandHelp = {
+  migrate: `
+Usage:
+  create-thally-docs migrate <github-or-docs-url> [output-dir] [options]
+
+Options:
+  --into <dir>         Migrate into an existing Thally project
+  --branch <name>      Override the detected Git branch
+  --docs-dir <path>    Override the detected documentation directory
+  --max-pages <count>  Limit a public URL crawl to 1-1000 pages
+  --platform <name>    Use mintlify, docusaurus, or auto
+  --api-key <key>      Anthropic API key for non-Markdown conversion
+  -y, --yes            Skip interactive prompts
+  -h, --help           Show this help
+`,
+  check: `
+Usage:
+  create-thally-docs check [project-dir] [options]
+
+Options:
+  --fix       Add orphan pages to navigation when possible
+  --ci        Use CI-oriented validation behavior
+  --external  Check external links
+  --drift     Check documentation provenance and freshness
+  -h, --help  Show this help
+`,
+  translate: `
+Usage:
+  create-thally-docs translate [project-dir] --locale <code> [options]
+
+Options:
+  --locale <code>  Target locale code (required)
+  --pages <ids>    Translate only the comma-separated page IDs
+  --force          Overwrite existing translations
+  --api-key <key>  Anthropic API key (defaults to ANTHROPIC_API_KEY)
+  --model <id>     Claude model to use
+  -y, --yes        Skip the confirmation prompt
+  -h, --help       Show this help
+`
+};
 var positional = [];
 for (let i = 0; i < args.length; i++) {
   if (args[i].startsWith("-")) {
@@ -815,6 +918,21 @@ function getFlagValue(flag) {
   }
   return void 0;
 }
+function resolveCommand(subcommand) {
+  if (subcommand === "migrate" || subcommand === "check" || subcommand === "translate") {
+    return subcommand;
+  }
+  return "scaffold";
+}
+function printHelp(command) {
+  console.log(command === "scaffold" ? mainHelp : commandHelp[command]);
+}
+function validateFlags(command) {
+  const unknownFlag = flags.find((flag) => !commandFlags[command].has(flag));
+  if (!unknownFlag) return;
+  const helpCommand = command === "scaffold" ? "" : ` ${command}`;
+  throw new Error(`Unknown option "${unknownFlag}". Run create-thally-docs${helpCommand} --help for usage.`);
+}
 async function runMigrateCommand() {
   let sourceUrl = positional[1];
   if (!sourceUrl) {
@@ -938,6 +1056,12 @@ async function runTranslateSubcommand() {
 }
 async function main() {
   const subcommand = positional[0];
+  const command = resolveCommand(subcommand);
+  if (flags.includes("--help") || flags.includes("-h")) {
+    printHelp(command);
+    return;
+  }
+  validateFlags(command);
   if (subcommand === "migrate") {
     await runMigrateCommand();
   } else if (subcommand === "check") {

package/dist/migrate/index.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import {
   migrateDocs
-} from "../chunk-JWTHIV4D.js";
-import "../chunk-JW72Y2YF.js";
+} from "../chunk-V5M5JVUF.js";
+import "../chunk-BBRZGMM6.js";
 import "../chunk-ORUAMPNF.js";
-import "../chunk-FCGVK2SJ.js";
-import "../chunk-DMPW77OB.js";
-import "../chunk-AJAB2TTJ.js";
+import "../chunk-2RWSXKSV.js";
+import "../chunk-AC3VR55N.js";
+import "../chunk-3B6CW5VF.js";
 export {
   migrateDocs
 };

package/dist/release.js

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

package/dist/scaffold.js

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 import {
   scaffold
-} from "./chunk-JW72Y2YF.js";
+} from "./chunk-BBRZGMM6.js";
 import "./chunk-ORUAMPNF.js";
 import {
   STARTER_ARCHIVE_ROOT,
   STARTER_COMMIT_SHA,
   STARTER_REPOSITORY,
   validateStarterArchiveEntry
-} from "./chunk-FCGVK2SJ.js";
-import "./chunk-DMPW77OB.js";
+} from "./chunk-2RWSXKSV.js";
+import "./chunk-AC3VR55N.js";
 import {
   STABLE_SCAFFOLD_RELEASE
-} from "./chunk-AJAB2TTJ.js";
+} from "./chunk-3B6CW5VF.js";
 export {
   STABLE_SCAFFOLD_RELEASE,
   STARTER_ARCHIVE_ROOT,

package/dist/starter-sync.js

@@ -8,8 +8,8 @@ import {
   planStarterRuntimeSync,
   readStarterReleaseManifest,
   starterManifestSha256
-} from "./chunk-DMPW77OB.js";
-import "./chunk-AJAB2TTJ.js";
+} from "./chunk-AC3VR55N.js";
+import "./chunk-3B6CW5VF.js";
 export {
   applyStarterRuntimeSyncPlan,
   classifyStarterPath,

package/dist/starter-update.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   downloadStarter
-} from "./chunk-FCGVK2SJ.js";
+} from "./chunk-2RWSXKSV.js";
 import {
   applyStarterRuntimeSyncPlan,
   mergeStarterOwnershipContracts,
@@ -9,11 +9,11 @@ import {
   planStarterRuntimeSync,
   readStarterReleaseManifest,
   starterManifestSha256
-} from "./chunk-DMPW77OB.js";
+} from "./chunk-AC3VR55N.js";
 import {
   STABLE_SCAFFOLD_RELEASE,
   SUPPORTED_SCAFFOLD_RELEASES
-} from "./chunk-AJAB2TTJ.js";
+} from "./chunk-3B6CW5VF.js";
 
 // src/starter-update.ts
 import {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-thally-docs",
-  "version": "0.10.23",
-  "description": "Scaffold the first documentation surface in a Thally product-knowledge pipeline.",
+  "version": "0.10.26",
+  "description": "Scaffold an open-source Thally docs site for people, search engines, and AI tools.",
   "type": "module",
   "engines": {
     "node": ">=18"
@@ -44,8 +44,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.36.0",
     "@inquirer/prompts": "^7.0.0",
-    "@thallylabs/migrate": "0.2.2",
-    "gray-matter": "^4.0.3",
+    "@thallylabs/migrate": "0.2.4",
     "p-limit": "^6.1.0",
     "tar": "^7.5.22",
     "yaml": "^2.6.0"
@@ -64,7 +63,7 @@
     "mdx",
     "nextjs",
     "ai",
-    "agent-native",
+    "product-knowledge",
     "mcp",
     "create"
   ],