## Overview

zudo-doc can automatically generate documentation pages from your project's Codex resources — `AGENTS.md` files, configuration profiles, custom agents, hooks, rules, and skills. When enabled, these pages appear under the **Codex** header navigation section.

## Enabling Codex Resources

Set `codexResources` in `zfb.config.ts`:

```ts title="zfb.config.ts"
export default defineConfig(
  zudoDoc({
    codexResources: {
      codexDir: ".codex",
    },
  }),
);
```

Set it to `false` to disable the integration:

```ts
codexResources: false,
```

## What Gets Generated

The integration creates the following documentation sections:

| Generated directory | Contents | Source |
|---------------------|----------|--------|
| `codex/` (position 904) | Overview page with category cards | — |
| `codex-agents-md/` (position 905) | Every `AGENTS.md` and `AGENTS.override.md` | Walked from `scanRoot` |
| `codex-config/` (position 906) | `config.toml`, `*.config.toml` profiles, and `config.toml.example` | `.codex/` |
| `codex-agents/` (position 907) | Custom subagents | `.codex/agents/*.toml` |
| `codex-hooks/` (position 908) | Lifecycle hooks and hook scripts | `.codex/hooks.json` and `.codex/hooks/` |
| `codex-rules/` (position 909) | Command approval rules | `.codex/rules/*.rules` |
| `codex-skills/` (position 910) | Skill packages | `.codex/skills/` and project/scan-root `.agents/skills/` directories |

Each resource section has an index page, and discovered resources are rendered as individual detail pages.

## How It Works

The integration runs at build time as the `@takazudo/zudo-doc/plugins/codex-resources` zfb plugin. When `codexResources` is configured, `zudoDoc()` wires in the plugin automatically. Its `preBuild` hook:

1. Resolves `projectRoot`, `scanRoot`, and the configured `.codex/` directory
2. Walks `scanRoot` for `AGENTS.md` and `AGENTS.override.md` files
3. Discovers configuration, agents, hooks, rules, and skills from the configured resource locations
4. Generates MDX index and detail pages in the seven `codex*` directories
5. Makes those pages available to zfb's content collections for rendering

The generated pages appear under the **Codex** header navigation tab. Configure the tab with `categoryMatch: "codex"` so it activates for every generated Codex section.

Set the header item to `versioned: false`. Generated Codex content is never written beneath `/v/{version}`, so a version-aware link would point to a route that does not exist while an archived version is active.

## Locale Behavior

The overview and category-index pages are generated in every configured locale, using `resource.*` UI strings for their title, description, and labels. The default content directory holds the canonical source dump for each individual resource body; its language follows the source files and is not necessarily English. Locale-prefixed routes display that body inside localized navigation and chrome without an untranslated-page banner. The language switcher keeps links to every configured locale.

English and Japanese `resource.*` strings ship with the package. Other supported locale codes follow the normal requested locale → configured default → English → literal fallback chain. You can override the labels through `ZudoDocConfig.translations`. See [Internationalization](https://zudo-doc.takazudomodular.com/docs/guides/i18n#generated-pages-and-default-locale-bodies) for the storage rationale, `llms.txt` and search behavior, and the `defaultLocaleOnlyPrefixes` opt-out.

## Configuration Options

| Option | Type | Description |
|--------|------|-------------|
| `codexDir` | string | Path to the `.codex/` directory, resolved from `projectRoot` |
| `projectRoot` | string | Optional project root override; anchors `codexDir` and the generated `docsDir` |
| `scanRoot` | string | Optional repository-wide discovery root; defaults to `projectRoot` and controls both the `AGENTS.md` / `AGENTS.override.md` walk and the repository-level `.agents/skills/` root |

[Dynamic content unavailable in text export]

Skills are discovered in precedence order from `<codexDir>/skills/`, `<projectRoot>/.agents/skills/`, then `<scanRoot>/.agents/skills/`. Roots that resolve to the same real path are deduplicated. If different directories provide the same skill name, the first root wins and the plugin logs a warning, even though Codex itself permits same-named skills in different scopes.



[Dynamic content unavailable in text export]

To maintain a skill once for both Claude Code and Codex, keep its source in one location and symlink the skill directory into `.claude/skills/` and `.codex/skills/`.



## Repository-Relative Links in Mirrors

In mirrored resource bodies, Markdown links and images targeting repository-relative paths become inline code, since those paths do not identify documentation URLs. The link label or image alt text is displayed. This applies to Claude `CLAUDE.md`, commands, and agents; Codex `AGENTS.md`; and both integrations' skill bodies and sub-pages.

In the main skill body, links into `references/`, `scripts/`, and `assets/` remain links only when the corresponding sub-page is actually generated. Missing targets and files that do not produce pages, such as `.sh` scripts, become inline code. Repository-relative links inside sub-page bodies are downgraded too; the generated-target exception applies to the main skill body.

External URLs, root-relative URLs, and page fragments are retained. Link examples inside inline code or fenced code are unchanged. Ordinary authored MDX continues to follow the [documentation linking rules](https://zudo-doc.takazudomodular.com/docs/getting-started/writing-docs).