#Root Files

selfdoc can generate root-level project files (like README.md and CLAUDE.md) from templates that live in your docs/ directory. The templates use the same directive syntax as your documentation pages, so the generated files always reflect the current state of your source code.

#How It Works

1. You create a template in docs/ with an underscore prefix (e.g., docs/_README.md, docs/_CLAUDE.md).
2. You list those templates in the root_files config array.
3. When you run selfdoc gen, each template is read, its directives are resolved against your source code, and the result is written to the project root (without the underscore). Generated files are set to mode 444 (read-only) to prevent accidental edits.

So docs/_README.md becomes README.md, and docs/_CLAUDE.md becomes CLAUDE.md.

#Configuration

Add the template paths to root_files in your selfdoc.json. Each entry must be an underscore-prefixed file in docs/ that serves as the template for a root-level project file. The underscore prefix distinguishes templates from regular documentation pages that appear on the built site:

{
  "root_files": [
    "docs/_README.md",
    "docs/_CLAUDE.md"
  ]
}

Each entry must be an underscore-prefixed file in docs/. The underscore prefix is mandatory -- it distinguishes templates from regular documentation pages.

#Template Format

Templates are regular Markdown files with optional frontmatter and directives. The frontmatter is stripped from the output (it is only used during the build). Everything else -- including resolved directive output -- goes into the generated file.

Example docs/_README.md:

---
title: README template
---

# MyProject

:<: ref path="mypackage"
:=:
:>:

## Installation

\`\`\`bash
pip install myproject
\`\`\`

After selfdoc gen, the project root gets a README.md with the directive replaced by actual module documentation extracted from source.

#Generated File Markers

Every generated root file starts with an HTML comment header that identifies it as machine-generated and names the source template. This marker serves two purposes: it warns humans not to edit the file directly, and it tells selfdoc that the file is safe to overwrite on the next run:

<!-- Auto-generated by selfdoc from docs/_README.md -- do not edit -->

This header serves two purposes:

1. It tells humans not to edit the file directly.
2. It tells selfdoc that the file was previously generated, making it safe to overwrite on the next run.

#Read-Only Permissions

Generated root files are set to chmod 444 (read-only) after writing. This is a safety measure -- if you or your editor accidentally open the generated file and try to save changes, the OS will block the write. Always edit the template in docs/, never the generated output.

#Regenerating

Run selfdoc gen to regenerate all root files from their templates. This resolves every directive in every template listed in root_files, overwrites the output files, and sets them to read-only permissions. It also runs automatically as part of selfdoc build:

selfdoc gen

This resolves directives in every template listed in root_files and overwrites the output files. It is also run as part of selfdoc build, so your root files stay current whenever you build the docs site.

Next: Data Generation -->