@takazudo/zudo-doc 5.8.0 → 5.9.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `@takazudo/zudo-doc` are documented in this file.
 
 The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
 
+## [5.9.0] - 2026-08-20
+
+### Features
+
+- Added Codex Resources generation for `AGENTS.md`, Codex configuration, custom agents, hooks, rules, and skills, with dedicated parsing and rendering for each resource type. (`666c12059`)
+- Added the public Codex Resources plugin and wired it through package settings, presets, `create-zudo-doc`, and generated project configuration. (`752a3fe5a`, `a7fa47906`, `5831cd73e`)
+- Added Codex Resources showcase data, navigation, localization, development watching, and complete English and Japanese documentation. (`a4dca1e40`, `1a2e6d5bc`, `f1396e7a1`)
+
+### Bug Fixes
+
+- Added type validation and deterministic fallbacks for malformed skill frontmatter values. (`710a1d225`)
+- Made generated Codex Resources frontmatter formatter-stable while preserving YAML string semantics and existing Claude Resources output.
+
+### Other Changes
+
+- Extracted shared resource-documentation helpers while preserving existing Claude Resources output byte-for-byte. (`c9165d5cb`)
+- Expanded generator, scaffold, build, and responsive navigation regression coverage for Codex Resources. (`142c11aa4`)
+
 ## [5.8.0] - 2026-08-20
 
 ### Features

package/dist/config.d.ts

@@ -72,6 +72,12 @@ type ClaudeResourcesConfig = {
     projectRoot?: string;
     scanRoot?: string;
 } | false;
+/** The `settings.codexResources` block (or `false` when disabled). */
+type CodexResourcesConfig = {
+    codexDir: string;
+    projectRoot?: string;
+    scanRoot?: string;
+} | false;
 export declare const DEFAULT_SETTINGS: Settings;
 export interface ZudoDocConfig {
     /**
@@ -372,6 +378,18 @@ export interface ZudoDocConfig {
      * @default false
      */
     claudeResources?: ClaudeResourcesConfig;
+    /**
+     * Codex-resources ingestion config, or `false` to disable.
+     * `codexDir` is the `.codex/` directory, resolved against `projectRoot`.
+     * `projectRoot` anchors relative paths and the output base. `scanRoot` is
+     * the repo-wide discovery root for the `AGENTS.md` / `AGENTS.override.md`
+     * walk (including its relPath base for titles/slugs) and the repo-level
+     * `.agents/skills/` root; it defaults to `projectRoot`. This lets a doc site
+     * in a repo subdirectory scan repo-wide instructions and team skills while
+     * writing into its own collection (#2558).
+     * @default false
+     */
+    codexResources?: CodexResourcesConfig;
     /**
      * Route prefixes served only in the default locale (never locale-prefixed).
      * @default []

package/dist/config.js

@@ -70,6 +70,7 @@ const DEFAULT_SETTINGS = {
   htmlPreview: void 0,
   versions: false,
   claudeResources: false,
+  codexResources: false,
   defaultLocaleOnlyPrefixes: [],
   footer: false,
   headerNav: [],

package/dist/i18n-defaults/index.js

@@ -6,6 +6,7 @@ const defaultTranslations = {
     "nav.components": "Components",
     "nav.reference": "Reference",
     "nav.claude": "Claude",
+    "nav.codex": "Codex",
     "nav.changelog": "Changelog",
     "nav.develop": "Develop",
     "nav.previous": "Previous",
@@ -65,6 +66,7 @@ const defaultTranslations = {
     "nav.components": "\u30B3\u30F3\u30DD\u30FC\u30CD\u30F3\u30C8",
     "nav.reference": "\u30EA\u30D5\u30A1\u30EC\u30F3\u30B9",
     "nav.claude": "Claude",
+    "nav.codex": "Codex",
     "nav.changelog": "\u5909\u66F4\u5C65\u6B74",
     "nav.develop": "\u958B\u767A",
     "nav.previous": "\u524D\u3078",
@@ -124,6 +126,7 @@ const defaultTranslations = {
     "nav.components": "Komponenten",
     "nav.reference": "Referenz",
     "nav.claude": "Claude",
+    "nav.codex": "Codex",
     "nav.changelog": "Changelog",
     "nav.develop": "Entwicklung",
     "nav.previous": "Zur\xFCck",

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

@@ -0,0 +1,4 @@
+import type { ZfbPlugin } from "@takazudo/zfb/plugins";
+export { runCodexResourcesPreStep } from "./internal/codex-resources/index.js";
+declare const plugin: ZfbPlugin;
+export default plugin;

package/dist/plugins/codex-resources.js

@@ -0,0 +1,31 @@
+import { runCodexResourcesPreStep } from "./internal/codex-resources/index.js";
+import { runCodexResourcesPreStep as runCodexResourcesPreStep2 } from "./internal/codex-resources/index.js";
+const PLUGIN_NAME = "@takazudo/zudo-doc-codex-resources";
+const plugin = {
+  name: PLUGIN_NAME,
+  async preBuild(ctx) {
+    const codexDir = ctx.options["codexDir"];
+    if (typeof codexDir !== "string" || codexDir.length === 0) {
+      throw new Error(
+        `[${PLUGIN_NAME}] preBuild: options.codexDir must be a non-empty string (got ${JSON.stringify(codexDir)})`
+      );
+    }
+    const projectRootOpt = ctx.options["projectRoot"];
+    const scanRootOpt = ctx.options["scanRoot"];
+    const docsDirOpt = ctx.options["docsDir"];
+    const result = runCodexResourcesPreStep({
+      codexDir,
+      projectRoot: typeof projectRootOpt === "string" ? projectRootOpt : ctx.projectRoot,
+      scanRoot: typeof scanRootOpt === "string" ? scanRootOpt : void 0,
+      docsDir: typeof docsDirOpt === "string" ? docsDirOpt : "src/content/docs"
+    });
+    ctx.logger.info(
+      `codex-resources: ${result.agentsMd} AGENTS.md, ${result.config} config, ${result.agents} agents, ${result.hooks} hooks, ${result.rules} rules, ${result.skills} skills`
+    );
+  }
+};
+var codex_resources_default = plugin;
+export {
+  codex_resources_default as default,
+  runCodexResourcesPreStep2 as runCodexResourcesPreStep
+};

package/dist/plugins/internal/claude-resources/generate.js

@@ -1,133 +1,17 @@
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
-import { escapeForMdx } from "./escape-for-mdx.js";
-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 parseFrontmatter(content) {
-  try {
-    return matter(content);
-  } catch {
-    return null;
-  }
-}
-function escapeTitle(s) {
-  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-}
-function listFiles(dir) {
-  if (!fs.existsSync(dir)) return [];
-  return fs.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isFile()).map((d) => d.name).sort();
-}
-function writeCategoryIndex(outputDir, label, position, description) {
-  const mdx = `---
-title: "${escapeTitle(label)}"
-description: "${escapeTitle(description)}"
-sidebar_position: ${position}
-category_no_page: true
-generated: true
----
-`;
-  fs.writeFileSync(path.join(outputDir, "index.mdx"), mdx);
-}
-function writeUnlistedSubPage(outputPath, title, body) {
-  fs.writeFileSync(
-    outputPath,
-    `---
-title: "${escapeTitle(title)}"
-unlisted: true
-generated: true
----
-
-${body}
-`
-  );
-}
-function assertNotIndexReserved(nameOrSlug, errorMessage) {
-  if (nameOrSlug === "index") {
-    throw new Error(errorMessage);
-  }
-}
-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)] ?? ""
-  );
-}
-const EXCLUDED_DIR_NAMES = /* @__PURE__ */ new Set([
-  "node_modules",
-  "worktrees",
-  "dist",
-  "out",
-  "public",
-  "__inbox",
-  "test-results"
-]);
-function findClaudeMdFiles(dir, excludeDirs) {
-  const results = [];
-  if (!fs.existsSync(dir)) return results;
-  const excludes = excludeDirs.map(
-    (d) => d.endsWith(path.sep) ? d.slice(0, -path.sep.length) : d
-  );
-  for (const item of fs.readdirSync(dir)) {
-    if (EXCLUDED_DIR_NAMES.has(item)) continue;
-    if (item.startsWith(".")) continue;
-    const itemPath = path.join(dir, item);
-    if (excludes.some((d) => itemPath === d || itemPath.startsWith(d + path.sep))) continue;
-    let stat;
-    try {
-      stat = fs.lstatSync(itemPath);
-    } catch {
-      continue;
-    }
-    if (stat.isDirectory()) {
-      results.push(...findClaudeMdFiles(itemPath, excludes));
-    } else if (stat.isFile() && item === "CLAUDE.md") {
-      results.push(itemPath);
-    }
-  }
-  return results;
-}
+import {
+  assertNotIndexReserved,
+  cleanDir,
+  downgradeRepoRelativeLinks,
+  ensureDir,
+  escapeForMdx,
+  escapeTitle,
+  findNamedFiles,
+  generateSkillsCategory,
+  parseFrontmatter,
+  writeCategoryIndex
+} from "../resource-docs-shared/index.js";
 function generateClaudemdDocs(config) {
   const projectRoot = config.projectRoot ?? config.claudeDir;
   const scanRoot = config.scanRoot ?? projectRoot;
@@ -138,7 +22,7 @@ function generateClaudemdDocs(config) {
     path.join(projectRoot, "e2e", "fixtures"),
     path.join(config.docsDir)
   ];
-  const files = findClaudeMdFiles(scanRoot, excludeDirs);
+  const files = findNamedFiles(scanRoot, excludeDirs, ["CLAUDE.md"]);
   if (files.length === 0) return [];
   ensureDir(outputDir);
   const items = [];
@@ -220,170 +104,15 @@ ${escapeForMdx(parsed.content.trim())}
   writeCategoryIndex(outputDir, "Commands", 901, "Custom slash commands");
   return items;
 }
-function getSkillFileTree(skillDir, subDirs) {
-  const lines = [`${skillDir}/`];
-  const entries = [{ isDir: false, name: "SKILL.md" }];
-  for (const sub of subDirs) {
-    entries.push({ isDir: true, name: sub.name, children: sub.files });
-  }
-  for (let i = 0; i < entries.length; i++) {
-    const entry = entries[i];
-    if (!entry) continue;
-    const isLast = i === entries.length - 1;
-    const prefix = isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
-    if (!entry.isDir) {
-      lines.push(`${prefix}${entry.name}`);
-    } else {
-      lines.push(`${prefix}${entry.name}/`);
-      for (let j = 0; j < entry.children.length; j++) {
-        const child = entry.children[j];
-        if (!child) continue;
-        const childIsLast = j === entry.children.length - 1;
-        const continuation = isLast ? "    " : "\u2502   ";
-        const childPrefix = childIsLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
-        lines.push(`${continuation}${childPrefix}${child}`);
-      }
-    }
-  }
-  return lines.join("\n");
-}
-function getScriptDescription(filePath) {
-  try {
-    const topLines = fs.readFileSync(filePath, "utf8").split("\n", 2);
-    const firstLine = topLines[0] ?? "";
-    const commentLine = firstLine.startsWith("#!") ? topLines[1] ?? "" : firstLine;
-    const match = commentLine.match(/^(?:#|\/\/)\s*(.+)/);
-    return match ? ` \u2014 ${match[1]}` : "";
-  } catch {
-    return "";
-  }
-}
-function getSkillReferences(skillsDir, skillDir) {
-  const refsDir = path.join(skillsDir, skillDir, "references");
-  if (!fs.existsSync(refsDir)) return [];
-  return fs.readdirSync(refsDir).filter((f) => f.endsWith(".md")).map((f) => {
-    const content = fs.readFileSync(path.join(refsDir, f), "utf8");
-    const name = f.replace(/\.md$/, "");
-    const h1Match = content.match(/^#\s+(.+)$/m);
-    const title = h1Match?.[1] ?? name;
-    return { name, title, content };
-  }).sort((a, b) => a.name.localeCompare(b.name));
-}
 function generateSkillsDocs(config) {
-  const skillsDir = path.join(config.claudeDir, "skills");
-  const outputDir = path.join(config.docsDir, "claude-skills");
-  cleanDir(outputDir);
-  if (!fs.existsSync(skillsDir)) return [];
-  const dirs = fs.readdirSync(skillsDir).filter((d) => {
-    const skillPath = path.join(skillsDir, d);
-    return fs.statSync(skillPath).isDirectory() && fs.existsSync(path.join(skillPath, "SKILL.md"));
+  return generateSkillsCategory({
+    skillsDirs: [path.join(config.claudeDir, "skills")],
+    outputDir: path.join(config.docsDir, "claude-skills"),
+    label: "Skills",
+    position: 902,
+    description: "Skill packages",
+    sourceLabel: ".claude/skills"
   });
-  if (dirs.length === 0) return [];
-  ensureDir(outputDir);
-  const items = [];
-  for (const dir of dirs) {
-    assertNotIndexReserved(
-      dir,
-      `claude-resources: skill directory ".claude/skills/index/" uses the reserved name "index", which is used for the category metadata file. Rename the skill directory to resolve the conflict.`
-    );
-    const content = fs.readFileSync(
-      path.join(skillsDir, dir, "SKILL.md"),
-      "utf8"
-    );
-    const parsed = parseFrontmatter(content);
-    if (!parsed) continue;
-    const name = parsed.data.name || dir;
-    const description = parsed.data.description || "";
-    const references = getSkillReferences(skillsDir, dir);
-    items.push({ name, dir, description, references });
-    const scriptFiles = listFiles(path.join(skillsDir, dir, "scripts"));
-    const assetFiles = listFiles(path.join(skillsDir, dir, "assets"));
-    const refFiles = references.map((r) => `${r.name}.md`);
-    const subDirs = [];
-    if (scriptFiles.length > 0) subDirs.push({ name: "scripts", files: scriptFiles });
-    if (refFiles.length > 0) subDirs.push({ name: "references", files: refFiles });
-    if (assetFiles.length > 0) subDirs.push({ name: "assets", files: assetFiles });
-    let fileStructureSection = "";
-    if (subDirs.length > 0) {
-      const tree = `\`\`\`
-${getSkillFileTree(dir, subDirs)}
-\`\`\``;
-      const links = [];
-      for (const ref of references) {
-        links.push(`- [references/${ref.name}.md](./ref-${ref.name})`);
-      }
-      for (const f of scriptFiles.filter((s) => s.endsWith(".md"))) {
-        const slug = f.replace(/\.md$/, "");
-        links.push(`- [scripts/${f}](./script-${slug})`);
-      }
-      for (const f of assetFiles.filter((a) => a.endsWith(".md"))) {
-        const slug = f.replace(/\.md$/, "");
-        links.push(`- [assets/${f}](./asset-${slug})`);
-      }
-      const linkList = links.length > 0 ? `
-
-${links.join("\n")}` : "";
-      fileStructureSection = `## File Structure
-
-${tree}${linkList}`;
-    }
-    const shortDesc = description.length > 200 ? description.substring(0, 200) + "..." : description;
-    let skillBody = parsed.content.trim();
-    skillBody = skillBody.replace(/\]\(references\/([^)]+)\.md\)/g, "](./ref-$1)").replace(/\]\(scripts\/([^)]+)\.md\)/g, "](./script-$1)").replace(/\]\(assets\/([^)]+)\.md\)/g, "](./asset-$1)");
-    const body = [
-      fileStructureSection,
-      escapeForMdx(skillBody)
-    ].filter(Boolean).join("\n\n");
-    const mdx = `---
-title: "${escapeTitle(name)}"
-description: "${escapeTitle(shortDesc)}"
-sidebar_label: "${escapeTitle(name)}"
-generated: true
----
-
-${body}`;
-    const skillDirOut = path.join(outputDir, dir);
-    ensureDir(skillDirOut);
-    fs.writeFileSync(path.join(skillDirOut, "index.mdx"), mdx);
-    for (const ref of references) {
-      writeUnlistedSubPage(
-        path.join(skillDirOut, `ref-${ref.name}.mdx`),
-        ref.title,
-        escapeForMdx(ref.content.trim())
-      );
-    }
-    for (const f of scriptFiles.filter((s) => s.endsWith(".md"))) {
-      const slug = f.replace(/\.md$/, "");
-      const raw = fs.readFileSync(
-        path.join(skillsDir, dir, "scripts", f),
-        "utf8"
-      );
-      const h1Match = raw.match(/^#\s+(.+)$/m);
-      const title = h1Match?.[1] ?? slug;
-      writeUnlistedSubPage(
-        path.join(skillDirOut, `script-${slug}.mdx`),
-        title,
-        escapeForMdx(raw.trim())
-      );
-    }
-    for (const f of assetFiles.filter((a) => a.endsWith(".md"))) {
-      const slug = f.replace(/\.md$/, "");
-      const raw = fs.readFileSync(
-        path.join(skillsDir, dir, "assets", f),
-        "utf8"
-      );
-      const h1Match = raw.match(/^#\s+(.+)$/m);
-      const title = h1Match?.[1] ?? slug;
-      writeUnlistedSubPage(
-        path.join(skillDirOut, `asset-${slug}.mdx`),
-        title,
-        escapeForMdx(raw.trim())
-      );
-    }
-  }
-  items.sort((a, b) => a.name.localeCompare(b.name));
-  writeCategoryIndex(outputDir, "Skills", 902, "Skill packages");
-  return items;
 }
 function generateAgentsDocs(config) {
   const agentsDir = path.join(config.claudeDir, "agents");

package/dist/plugins/internal/codex-resources/agents-md.d.ts

@@ -0,0 +1,6 @@
+import type { CodexResourcesConfig } from "./generate.js";
+export interface AgentsMdItem {
+    relPath: string;
+    slug: string;
+}
+export declare function generateAgentsMdCategory(config: CodexResourcesConfig): AgentsMdItem[];

package/dist/plugins/internal/codex-resources/agents-md.js

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  formatFrontmatterString,
+  cleanDir,
+  downgradeRepoRelativeLinks,
+  ensureDir,
+  escapeForMdx,
+  escapeMarkdownTableCell,
+  findNamedFiles,
+  writeCategoryIndex
+} from "../resource-docs-shared/index.js";
+import { assertUniqueSlug, writeGeneratedPage } from "./utils.js";
+function generateAgentsMdCategory(config) {
+  const projectRoot = config.projectRoot ?? config.codexDir;
+  const scanRoot = config.scanRoot ?? projectRoot;
+  const outputDir = path.join(config.docsDir, "codex-agents-md");
+  cleanDir(outputDir);
+  const excludeDirs = [
+    path.join(scanRoot, "e2e", "fixtures"),
+    path.join(projectRoot, "e2e", "fixtures"),
+    config.docsDir
+  ];
+  const files = findNamedFiles(scanRoot, excludeDirs, [
+    "AGENTS.md",
+    "AGENTS.override.md"
+  ]);
+  if (files.length === 0) return [];
+  const items = files.map((absPath) => {
+    const relPath = path.relative(scanRoot, absPath);
+    const dirPart = path.dirname(relPath);
+    const baseSlug = dirPart === "." ? "root" : dirPart.split(path.sep).join("--");
+    const slug = path.basename(absPath) === "AGENTS.override.md" ? `${baseSlug}--override` : baseSlug;
+    return { absPath, relPath, slug };
+  });
+  items.sort((a, b) => {
+    if (a.slug === "root") return -1;
+    if (b.slug === "root") return 1;
+    return a.relPath.localeCompare(b.relPath);
+  });
+  ensureDir(outputDir);
+  const emitted = /* @__PURE__ */ new Map();
+  items.forEach((item, index) => {
+    assertUniqueSlug("AGENTS.md", item.slug, item.relPath, emitted);
+    const content = fs.readFileSync(item.absPath, "utf8");
+    writeGeneratedPage({
+      outputPath: path.join(outputDir, `${item.slug}.mdx`),
+      title: `/${item.relPath}`,
+      description: `Codex instructions at /${item.relPath}`,
+      sidebarPosition: index + 1,
+      sidebarLabel: item.relPath,
+      body: `**Path:** ${escapeMarkdownTableCell(item.relPath)}
+
+${escapeForMdx(
+        downgradeRepoRelativeLinks(content.trim())
+      )}`
+    });
+  });
+  writeCategoryIndex(
+    outputDir,
+    "AGENTS.md",
+    905,
+    "Project instructions for Codex",
+    formatFrontmatterString
+  );
+  return items.map(({ relPath, slug }) => ({ relPath, slug }));
+}
+export {
+  generateAgentsMdCategory
+};

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

@@ -0,0 +1,7 @@
+import type { CodexResourcesConfig } from "./generate.js";
+export interface AgentItem {
+    filename: string;
+    slug: string;
+    name: string;
+}
+export declare function generateAgentsCategory(config: CodexResourcesConfig): AgentItem[];

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

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "smol-toml";
+import {
+  formatFrontmatterString,
+  cleanDir,
+  ensureDir,
+  escapeForMdx,
+  escapeMarkdownTableCell,
+  renderCodeFence,
+  writeCategoryIndex
+} from "../resource-docs-shared/index.js";
+import {
+  assertUniqueSlug,
+  filenameSlug,
+  isRecord,
+  warn,
+  writeGeneratedPage
+} from "./utils.js";
+function optionalString(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 generateAgentsCategory(config) {
+  const agentsDir = path.join(config.codexDir, "agents");
+  const outputDir = path.join(config.docsDir, "codex-agents");
+  cleanDir(outputDir);
+  if (!fs.existsSync(agentsDir)) return [];
+  let files;
+  try {
+    files = fs.readdirSync(agentsDir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith(".toml")).map((entry) => entry.name).sort();
+  } catch (error) {
+    warn(agentsDir, `unable to read agents 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(agentsDir, filename);
+    let source;
+    let parsed;
+    try {
+      source = fs.readFileSync(filePath, "utf8");
+      parsed = parse(source);
+    } catch (error) {
+      warn(filePath, `unable to parse TOML, skipping file: ${String(error)}`);
+      continue;
+    }
+    if (!isRecord(parsed)) {
+      warn(filePath, "parsed TOML root was not an object, skipping file");
+      continue;
+    }
+    const slug = filenameSlug(filename.replace(/\.toml$/, ""));
+    assertUniqueSlug("agent", slug, filename, emitted);
+    const name = optionalString(parsed, "name", filePath) ?? slug;
+    const description = optionalString(parsed, "description", filePath) ?? "";
+    const model = optionalString(parsed, "model", filePath);
+    const reasoning = optionalString(parsed, "model_reasoning_effort", filePath);
+    const sandbox = optionalString(parsed, "sandbox_mode", filePath);
+    const instructions = optionalString(parsed, "developer_instructions", filePath);
+    const badges = [
+      model ? `**Model:** ${escapeMarkdownTableCell(model)}` : "",
+      reasoning ? `**Reasoning effort:** ${escapeMarkdownTableCell(reasoning)}` : "",
+      sandbox ? `**Sandbox:** ${escapeMarkdownTableCell(sandbox)}` : ""
+    ].filter(Boolean);
+    const sections = [badges.join("\n")];
+    if (instructions !== void 0) {
+      sections.push(
+        `## Developer instructions
+
+${escapeForMdx(instructions.trim())}`
+      );
+    }
+    sections.push(`## Source
+
+${renderCodeFence(source, "toml")}`);
+    writeGeneratedPage({
+      outputPath: path.join(outputDir, `${slug}.mdx`),
+      title: name,
+      description,
+      sidebarLabel: name,
+      body: sections.filter(Boolean).join("\n\n")
+    });
+    items.push({ filename, slug, name });
+  }
+  if (items.length > 0) {
+    writeCategoryIndex(
+      outputDir,
+      "Agents",
+      907,
+      "Custom subagents",
+      formatFrontmatterString
+    );
+  }
+  return items;
+}
+export {
+  generateAgentsCategory
+};

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

@@ -0,0 +1,6 @@
+import type { CodexResourcesConfig } from "./generate.js";
+export interface ConfigItem {
+    filename: string;
+    slug: string;
+}
+export declare function generateConfigCategory(config: CodexResourcesConfig): ConfigItem[];