@takazudo/zudo-doc 5.8.0 → 5.9.0

package/dist/plugins/internal/codex-resources/rules.js

@@ -0,0 +1,255 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  formatFrontmatterString,
+  cleanDir,
+  ensureDir,
+  renderCodeFence,
+  writeCategoryIndex
+} from "../resource-docs-shared/index.js";
+import {
+  assertUniqueSlug,
+  renderTableRow,
+  warn,
+  writeGeneratedPage
+} from "./utils.js";
+function freshState() {
+  return { quote: null, triple: false, escaped: false, comment: false };
+}
+function advanceState(text, index, state) {
+  const char = text[index] ?? "";
+  if (state.comment) {
+    if (char === "\n") state.comment = false;
+    return 1;
+  }
+  if (state.quote !== null) {
+    if (state.escaped) {
+      state.escaped = false;
+      return 1;
+    }
+    if (char === "\\") {
+      state.escaped = true;
+      return 1;
+    }
+    if (state.triple && text.slice(index, index + 3) === state.quote.repeat(3)) {
+      state.quote = null;
+      state.triple = false;
+      return 3;
+    }
+    if (!state.triple && char === state.quote) state.quote = null;
+    return 1;
+  }
+  if (char === "#") {
+    state.comment = true;
+    return 1;
+  }
+  if (char === "'" || char === '"') {
+    state.quote = char;
+    state.triple = text.slice(index, index + 3) === char.repeat(3);
+    return state.triple ? 3 : 1;
+  }
+  return 1;
+}
+function findPrefixRuleBodies(source) {
+  const bodies = [];
+  const state = freshState();
+  let index = 0;
+  while (index < source.length) {
+    if (state.quote === null && !state.comment && source.startsWith("prefix_rule", index)) {
+      const before = source[index - 1];
+      const after = source[index + "prefix_rule".length];
+      if ((!before || !/[\w]/.test(before)) && (!after || !/[\w]/.test(after))) {
+        let open = index + "prefix_rule".length;
+        while (/\s/.test(source[open] ?? "")) open++;
+        if (source[open] === "(") {
+          const callState = freshState();
+          let depth = 1;
+          let cursor = open + 1;
+          const bodyStart = cursor;
+          while (cursor < source.length) {
+            if (callState.quote === null && !callState.comment) {
+              if (source[cursor] === "(") depth++;
+              if (source[cursor] === ")") {
+                depth--;
+                if (depth === 0) break;
+              }
+            }
+            cursor += advanceState(source, cursor, callState);
+          }
+          bodies.push(source.slice(bodyStart, cursor));
+          index = cursor < source.length ? cursor + 1 : source.length;
+          continue;
+        }
+      }
+    }
+    index += advanceState(source, index, state);
+  }
+  return bodies;
+}
+function splitTopLevel(text, delimiter) {
+  const parts = [];
+  const state = freshState();
+  let square = 0;
+  let round = 0;
+  let curly = 0;
+  let start = 0;
+  let index = 0;
+  while (index < text.length) {
+    if (state.quote === null && !state.comment) {
+      const char = text[index];
+      if (char === "[") square++;
+      else if (char === "]") square--;
+      else if (char === "(") round++;
+      else if (char === ")") round--;
+      else if (char === "{") curly++;
+      else if (char === "}") curly--;
+      else if (char === delimiter && square === 0 && round === 0 && curly === 0) {
+        parts.push(text.slice(start, index));
+        start = index + 1;
+      }
+    }
+    index += advanceState(text, index, state);
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
+function parseStringLiteral(value) {
+  const text = value.trim();
+  const quote = text[0];
+  if (quote !== '"' && quote !== "'" || text.at(-1) !== quote) return void 0;
+  if (text.startsWith(quote.repeat(3)) && text.endsWith(quote.repeat(3))) {
+    return text.slice(3, -3);
+  }
+  const inner = text.slice(1, -1);
+  let result = "";
+  for (let i = 0; i < inner.length; i++) {
+    const char = inner[i];
+    if (char !== "\\") {
+      result += char;
+      continue;
+    }
+    const next = inner[++i];
+    if (next === void 0) return void 0;
+    const escapes = {
+      n: "\n",
+      r: "\r",
+      t: "	",
+      "\\": "\\",
+      "'": "'",
+      '"': '"'
+    };
+    result += escapes[next] ?? next;
+  }
+  return result;
+}
+function parsePatternValue(text) {
+  const trimmed = text.trim();
+  const stringValue = parseStringLiteral(trimmed);
+  if (stringValue !== void 0) return stringValue;
+  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return void 0;
+  const inner = trimmed.slice(1, -1);
+  if (inner.trim() === "") return [];
+  const values = [];
+  for (const part of splitTopLevel(inner, ",")) {
+    if (part.trim() === "") continue;
+    const parsed = parsePatternValue(part);
+    if (parsed === void 0) return void 0;
+    values.push(parsed);
+  }
+  return values;
+}
+function formatPattern(value) {
+  if (!Array.isArray(value)) return value;
+  const parts = [];
+  for (const element of value) {
+    if (Array.isArray(element)) {
+      if (element.some(Array.isArray)) return void 0;
+      parts.push(element.join("|"));
+    } else {
+      parts.push(element);
+    }
+  }
+  return parts.join(" ");
+}
+function parseRule(body) {
+  const args = /* @__PURE__ */ new Map();
+  for (const part of splitTopLevel(body, ",")) {
+    const assignment = splitTopLevel(part, "=");
+    if (assignment.length !== 2) continue;
+    const key = assignment[0]?.trim();
+    const value = assignment[1];
+    if (key && value !== void 0) args.set(key, value.trim());
+  }
+  const rawPattern = args.get("pattern");
+  const parsedPattern = rawPattern === void 0 ? void 0 : parsePatternValue(rawPattern);
+  const decision = args.has("decision") ? parseStringLiteral(args.get("decision") ?? "") : "allow";
+  return {
+    pattern: parsedPattern === void 0 ? void 0 : formatPattern(parsedPattern),
+    decision,
+    justification: args.has("justification") ? parseStringLiteral(args.get("justification") ?? "") : void 0
+  };
+}
+function generateRulesCategory(config) {
+  const rulesDir = path.join(config.codexDir, "rules");
+  const outputDir = path.join(config.docsDir, "codex-rules");
+  cleanDir(outputDir);
+  if (!fs.existsSync(rulesDir)) return [];
+  let files;
+  try {
+    files = fs.readdirSync(rulesDir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith(".rules")).map((entry) => entry.name).sort();
+  } catch (error) {
+    warn(rulesDir, `unable to read rules directory: ${String(error)}`);
+    return [];
+  }
+  if (files.length === 0) return [];
+  ensureDir(outputDir);
+  const items = [];
+  const emitted = /* @__PURE__ */ new Map();
+  for (const filename of files) {
+    const filePath = path.join(rulesDir, filename);
+    const slug = filename.replace(/\.rules$/, "");
+    assertUniqueSlug("rule", slug, filePath, emitted);
+    let source;
+    try {
+      source = fs.readFileSync(filePath, "utf8");
+    } catch (error) {
+      warn(filePath, `unable to read rules file, skipping it: ${String(error)}`);
+      continue;
+    }
+    const rows = findPrefixRuleBodies(source).map(parseRule);
+    const body = [
+      "## Rules",
+      "",
+      "| Pattern | Decision | Justification |",
+      "| --- | --- | --- |",
+      ...rows.length > 0 ? rows.map(
+        (row) => renderTableRow([row.pattern, row.decision, row.justification])
+      ) : [renderTableRow(Array.from({ length: 3 }))],
+      "",
+      "## Source",
+      "",
+      renderCodeFence(source, "python")
+    ].join("\n");
+    writeGeneratedPage({
+      outputPath: path.join(outputDir, `${slug}.mdx`),
+      title: filename,
+      description: `Command approval rules from ${filename}`,
+      sidebarLabel: filename,
+      body
+    });
+    items.push({ filename, slug });
+  }
+  if (items.length > 0) {
+    writeCategoryIndex(
+      outputDir,
+      "Rules",
+      909,
+      "Command approval rules",
+      formatFrontmatterString
+    );
+  }
+  return items;
+}
+export {
+  generateRulesCategory
+};

package/dist/plugins/internal/codex-resources/skills.d.ts

@@ -0,0 +1,2 @@
+import type { CodexResourcesConfig } from "./generate.js";
+export declare function generateSkillsCategoryDocs(config: CodexResourcesConfig): import("../resource-docs-shared/skills.js").SkillItem[];

package/dist/plugins/internal/codex-resources/skills.js

@@ -0,0 +1,84 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import {
+  escapeForMdx,
+  formatFrontmatterString,
+  generateSkillsCategory
+} from "../resource-docs-shared/index.js";
+import { isRecord, warn } from "./utils.js";
+function optionalMetadataString(record, field, filePath) {
+  const value = record[field];
+  if (value === void 0) return void 0;
+  if (typeof value === "string") return value;
+  warn(filePath, `${field} must be a string; omitting it`);
+  return void 0;
+}
+function renderOpenAiMetadata(skillAbsDir) {
+  const filePath = path.join(skillAbsDir, "agents", "openai.yaml");
+  if (!fs.existsSync(filePath)) return "";
+  let data;
+  try {
+    const yaml = fs.readFileSync(filePath, "utf8");
+    data = matter(`---
+${yaml}
+---
+`).data;
+  } catch (error) {
+    warn(filePath, `unable to parse YAML, omitting metadata: ${String(error)}`);
+    return "";
+  }
+  if (!isRecord(data)) {
+    warn(filePath, "YAML root must be an object; omitting metadata");
+    return "";
+  }
+  let interfaceData;
+  if (data.interface !== void 0) {
+    if (isRecord(data.interface)) interfaceData = data.interface;
+    else warn(filePath, "interface must be an object; omitting interface metadata");
+  }
+  let policy;
+  if (data.policy !== void 0) {
+    if (isRecord(data.policy)) policy = data.policy;
+    else warn(filePath, "policy must be an object; omitting policy metadata");
+  }
+  const displayName = interfaceData ? optionalMetadataString(interfaceData, "display_name", filePath) : void 0;
+  const shortDescription = interfaceData ? optionalMetadataString(interfaceData, "short_description", filePath) : void 0;
+  let explicitOnly = false;
+  if (policy?.allow_implicit_invocation !== void 0) {
+    if (typeof policy.allow_implicit_invocation === "boolean") {
+      explicitOnly = policy.allow_implicit_invocation === false;
+    } else {
+      warn(
+        filePath,
+        "policy.allow_implicit_invocation must be a boolean; omitting invocation metadata"
+      );
+    }
+  }
+  return [
+    displayName ? `**Display name:** ${escapeForMdx(displayName)}` : "",
+    shortDescription ? `**Short description:** ${escapeForMdx(shortDescription)}` : "",
+    explicitOnly ? `**Invocation:** explicit only (\`$${path.basename(skillAbsDir)}\`)` : ""
+  ].filter(Boolean).join("\n");
+}
+function generateSkillsCategoryDocs(config) {
+  const projectRoot = config.projectRoot ?? config.codexDir;
+  const scanRoot = config.scanRoot ?? projectRoot;
+  return generateSkillsCategory({
+    skillsDirs: [
+      path.join(config.codexDir, "skills"),
+      path.join(projectRoot, ".agents", "skills"),
+      path.join(scanRoot, ".agents", "skills")
+    ],
+    outputDir: path.join(config.docsDir, "codex-skills"),
+    label: "Skills",
+    position: 910,
+    description: "Skill packages",
+    sourceLabel: ".codex/skills",
+    renderExtraHeader: renderOpenAiMetadata,
+    renderFrontmatterString: formatFrontmatterString
+  });
+}
+export {
+  generateSkillsCategoryDocs
+};

package/dist/plugins/internal/codex-resources/utils.d.ts

@@ -0,0 +1,14 @@
+export declare function warn(filePath: string, message: string): void;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function filenameSlug(filename: string): string;
+export declare function renderTableRow(values: unknown[]): string;
+export declare function assertUniqueSlug(resource: string, slug: string, filePath: string, emitted: Map<string, string>): void;
+export declare function writeGeneratedPage({ outputPath, title, description, sidebarLabel, sidebarPosition, body, }: {
+    outputPath: string;
+    title: string;
+    description: string;
+    sidebarLabel?: string;
+    sidebarPosition?: number;
+    body: string;
+}): void;
+export declare function languageForFilename(filename: string): string;

package/dist/plugins/internal/codex-resources/utils.js

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  assertNotIndexReserved,
+  escapeMarkdownTableCell,
+  formatFrontmatterString
+} from "../resource-docs-shared/index.js";
+function warn(filePath, message) {
+  console.warn(`${filePath}: ${message}`);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function filenameSlug(filename) {
+  return filename.replace(/\./g, "-");
+}
+function renderTableRow(values) {
+  return `| ${values.map(escapeMarkdownTableCell).join(" | ")} |`;
+}
+function assertUniqueSlug(resource, slug, filePath, emitted) {
+  assertNotIndexReserved(
+    slug,
+    `codex-resources: "${filePath}" maps to the reserved slug "index", which is used for the category metadata file. Rename the file or directory to resolve the conflict.`
+  );
+  const previous = emitted.get(slug);
+  if (previous !== void 0) {
+    throw new Error(
+      `codex-resources: ${resource} slug collision \u2014 "${slug}" is produced by both "${previous}" and "${filePath}". Rename one of the files to resolve the conflict.`
+    );
+  }
+  emitted.set(slug, filePath);
+}
+function writeGeneratedPage({
+  outputPath,
+  title,
+  description,
+  sidebarLabel,
+  sidebarPosition,
+  body
+}) {
+  const position = sidebarPosition === void 0 ? "" : `sidebar_position: ${sidebarPosition}
+`;
+  const label = sidebarLabel === void 0 ? "" : `sidebar_label: ${formatFrontmatterString(sidebarLabel)}
+`;
+  fs.writeFileSync(
+    outputPath,
+    `---
+title: ${formatFrontmatterString(title)}
+description: ${formatFrontmatterString(description)}
+${position}${label}generated: true
+---
+
+${body.trim()}
+`
+  );
+}
+function languageForFilename(filename) {
+  switch (path.extname(filename).toLowerCase()) {
+    case ".sh":
+      return "bash";
+    case ".py":
+      return "python";
+    case ".js":
+    case ".mjs":
+      return "javascript";
+    case ".ts":
+      return "typescript";
+    default:
+      return "";
+  }
+}
+export {
+  assertUniqueSlug,
+  filenameSlug,
+  isRecord,
+  languageForFilename,
+  renderTableRow,
+  warn,
+  writeGeneratedPage
+};

package/dist/plugins/internal/resource-docs-shared/fs.d.ts

@@ -0,0 +1,3 @@
+export declare function ensureDir(dir: string): void;
+export declare function cleanDir(dir: string): void;
+export declare function listFiles(dir: string): string[];

package/dist/plugins/internal/resource-docs-shared/fs.js

@@ -0,0 +1,19 @@
+import fs from "node:fs";
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+function cleanDir(dir) {
+  if (!fs.existsSync(dir)) return;
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+function listFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isFile()).map((d) => d.name).sort();
+}
+export {
+  cleanDir,
+  ensureDir,
+  listFiles
+};

package/dist/plugins/internal/resource-docs-shared/index.d.ts

@@ -0,0 +1,7 @@
+export { escapeForMdx } from "./escape-for-mdx.js";
+export { cleanDir, ensureDir, listFiles } from "./fs.js";
+export { assertNotIndexReserved, escapeTitle, formatFrontmatterString, parseFrontmatter, type FrontmatterStringRenderer, writeCategoryIndex, writeUnlistedSubPage, } from "./mdx.js";
+export { isRepoRelativeLink, downgradeRepoRelativeLinks } from "./links.js";
+export { escapeMarkdownTableCell, renderCodeFence, } from "./markdown-structure.js";
+export { EXCLUDED_DIR_NAMES, findNamedFiles } from "./walk.js";
+export { generateSkillsCategory, getScriptDescription, getSkillFileTree, getSkillReferences, type GenerateSkillsCategoryOptions, type RenderExtraHeader, type SkillItem, type SkillReference, } from "./skills.js";

package/dist/plugins/internal/resource-docs-shared/index.js

@@ -0,0 +1,44 @@
+import { escapeForMdx } from "./escape-for-mdx.js";
+import { cleanDir, ensureDir, listFiles } from "./fs.js";
+import {
+  assertNotIndexReserved,
+  escapeTitle,
+  formatFrontmatterString,
+  parseFrontmatter,
+  writeCategoryIndex,
+  writeUnlistedSubPage
+} from "./mdx.js";
+import { isRepoRelativeLink, downgradeRepoRelativeLinks } from "./links.js";
+import {
+  escapeMarkdownTableCell,
+  renderCodeFence
+} from "./markdown-structure.js";
+import { EXCLUDED_DIR_NAMES, findNamedFiles } from "./walk.js";
+import {
+  generateSkillsCategory,
+  getScriptDescription,
+  getSkillFileTree,
+  getSkillReferences
+} from "./skills.js";
+export {
+  EXCLUDED_DIR_NAMES,
+  assertNotIndexReserved,
+  cleanDir,
+  downgradeRepoRelativeLinks,
+  ensureDir,
+  escapeForMdx,
+  escapeMarkdownTableCell,
+  escapeTitle,
+  findNamedFiles,
+  formatFrontmatterString,
+  generateSkillsCategory,
+  getScriptDescription,
+  getSkillFileTree,
+  getSkillReferences,
+  isRepoRelativeLink,
+  listFiles,
+  parseFrontmatter,
+  renderCodeFence,
+  writeCategoryIndex,
+  writeUnlistedSubPage
+};

package/dist/plugins/internal/resource-docs-shared/links.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Whether a markdown link target is a repo-relative file reference
+ * (`./wrangler.toml`, `../../schema/photos.sql`, `foo/bar.md`) rather than
+ * something the doc site can resolve: an absolute URL (`https://…`), a
+ * protocol-relative URL (`//…`), a site-absolute path (`/docs/…`), a pure
+ * anchor (`#…`), or a scheme (`mailto:`, `tel:`).
+ */
+export declare function isRepoRelativeLink(url: string): boolean;
+/**
+ * Downgrade repo-relative markdown links in a mirrored `CLAUDE.md` body to
+ * inline code so they don't dangle in the flattened mirror tree (#2411).
+ *
+ * A `CLAUDE.md`'s relative links point at real repo files (correct for an
+ * in-repo reader), but the mirror flattens each file into a single
+ * `claude-md/<name>.mdx` page with no counterpart for those targets — left as
+ * links they surface as `broken link:` warnings on every affected page. Inline
+ * code keeps the reference legible (`` `wrangler.toml` ``) without a href.
+ *
+ * Code spans are preserved verbatim: a `[x](./y)` inside a fenced block or an
+ * inline-code span is literal text, not a link, and must not be rewritten.
+ */
+export declare function downgradeRepoRelativeLinks(content: string): string;

package/dist/plugins/internal/resource-docs-shared/links.js

@@ -0,0 +1,44 @@
+function isRepoRelativeLink(url) {
+  const trimmed = url.trim();
+  if (trimmed === "") return false;
+  if (trimmed.startsWith("#")) return false;
+  if (trimmed.startsWith("/")) return false;
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(trimmed)) return false;
+  return true;
+}
+function downgradeRepoRelativeLinks(content) {
+  const blockPlaceholder = "\0CRLINK_BLOCK_";
+  const inlinePlaceholder = "\0CRLINK_INLINE_";
+  const codeBlocks = [];
+  const withBlocks = content.replace(/(`{3,}|~{3,})[^\n]*\n[\s\S]*?\1/g, (match) => {
+    codeBlocks.push(match);
+    return `${blockPlaceholder}${codeBlocks.length - 1}\0`;
+  });
+  const transformed = withBlocks.split(new RegExp(`(${blockPlaceholder}\\d+\0)`, "g")).map((part) => {
+    if (new RegExp(`^${blockPlaceholder}\\d+\0$`).test(part)) return part;
+    const inlineCodes = [];
+    const withInline = part.replace(
+      /(`{1,3})(?!`)([\s\S]*?[^`])\1(?!`)/g,
+      (match) => {
+        inlineCodes.push(match);
+        return `${inlinePlaceholder}${inlineCodes.length - 1}\0`;
+      }
+    );
+    const rewritten = withInline.replace(
+      /!?\[([^\]]*)\]\(([^)]+)\)/g,
+      (match, text, url) => isRepoRelativeLink(url) ? `\`${text}\`` : match
+    );
+    return rewritten.replace(
+      new RegExp(`${inlinePlaceholder}(\\d+)\0`, "g"),
+      (_, idx) => inlineCodes[Number(idx)] ?? ""
+    );
+  }).join("");
+  return transformed.replace(
+    new RegExp(`${blockPlaceholder}(\\d+)\0`, "g"),
+    (_, idx) => codeBlocks[Number(idx)] ?? ""
+  );
+}
+export {
+  downgradeRepoRelativeLinks,
+  isRepoRelativeLink
+};

package/dist/plugins/internal/resource-docs-shared/markdown-structure.d.ts

@@ -0,0 +1,9 @@
+/** Render source inside a Markdown fence that cannot be closed by the source. */
+export declare function renderCodeFence(source: string, language?: string): string;
+/**
+ * Render an arbitrary value as a structurally safe Markdown table cell.
+ *
+ * Code-span delimiters are chosen from the value itself. Pipes are escaped
+ * for the surrounding table and physical newlines are collapsed to spaces.
+ */
+export declare function escapeMarkdownTableCell(value: unknown): string;

package/dist/plugins/internal/resource-docs-shared/markdown-structure.js

@@ -0,0 +1,22 @@
+function renderCodeFence(source, language = "") {
+  const runs = source.match(/`+/g) ?? [];
+  const longestRun = runs.reduce((max, run) => Math.max(max, run.length), 0);
+  const fence = "`".repeat(Math.max(3, longestRun + 1));
+  const trailingNewline = source.endsWith("\n") ? "" : "\n";
+  return `${fence}${language}
+${source}${trailingNewline}${fence}`;
+}
+function escapeMarkdownTableCell(value) {
+  if (value === void 0 || value === null || value === "") return "\u2014";
+  const content = String(value).replace(/\r\n?|\n/g, " ").replace(/\|/g, "\\|");
+  if (content === "") return "\u2014";
+  const runs = content.match(/`+/g) ?? [];
+  const longestRun = runs.reduce((max, run) => Math.max(max, run.length), 0);
+  const delimiter = "`".repeat(Math.max(1, longestRun + 1));
+  const needsPadding = /^[` ]|[` ]$/.test(content);
+  return needsPadding ? `${delimiter} ${content} ${delimiter}` : `${delimiter}${content}${delimiter}`;
+}
+export {
+  escapeMarkdownTableCell,
+  renderCodeFence
+};

package/dist/plugins/internal/resource-docs-shared/mdx.d.ts

@@ -0,0 +1,23 @@
+import matter from "gray-matter";
+export declare function parseFrontmatter(content: string): matter.GrayMatterFile<string> | null;
+export declare function escapeTitle(s: string): string;
+export type FrontmatterStringRenderer = (value: string) => string;
+export declare function formatFrontmatterString(value: string): string;
+export declare function writeCategoryIndex(outputDir: string, label: string, position: number, description: string, renderString?: FrontmatterStringRenderer): void;
+/**
+ * Writes an unlisted sub-page MDX file. Used for skill references, scripts,
+ * and assets.
+ *
+ * The route is derived from the file's path within the content collection —
+ * deliberately NOT from an explicit `slug:`. zfb's `resolveMarkdownLinks`
+ * resolves relative links against the source file path, so the on-disk
+ * location of these pages must match the URL the skill page links to. Writing
+ * them at `<dir>/ref-<name>.mdx` (siblings of the skill's `index.mdx`) is what
+ * makes the `./ref-<name>` links resolve (#2411).
+ */
+export declare function writeUnlistedSubPage(outputPath: string, title: string, body: string, renderString?: FrontmatterStringRenderer): void;
+/**
+ * Guards that the given name/slug is not the reserved "index" value.
+ * Throws with a contextual message if it is.
+ */
+export declare function assertNotIndexReserved(nameOrSlug: string, errorMessage: string): void;