Doc Registration — make a new doc discoverable

When dealing with documentation in software projects, ensuring that new or relocated docs are discoverable is as crucial as creating the content itself. I recently had to register a new doc and learned some practical steps from the doc-registration guide in the overnight build system. This process involved precise updates to two key files: INDEX.md and .claude/registry/LOOKUP.md.

The Registration Process

When I moved a guide, the first step was to update the relevant INDEX.md. Each INDEX.md file, like guides/web-design/INDEX.md, acts as a directory for specific areas, and maintaining its unique style is critical. If my doc was about web design, guides/web-design/INDEX.md was the file to edit.

In the INDEX.md, I added a row matching the existing format, whether it was a table row or an Obsidian-style [[path|label]] wikilink. I ensured the path was consistent with the neighboring entries, using either a repo-root-relative or index-relative path.

Lookup Table Update

The next mandatory step was updating .claude/registry/LOOKUP.md, where I added a row in the format | <Concept> | `<repo-root-relative path>` | <search terms> |. The search terms are the key here, acting as the primary discovery signal. I included a range of 5-12 terms using nouns, synonyms, verbs, and key filenames from the doc's headings. This step ensures that agents can locate the document through various relevant searches.

Common Pitfalls

One common mistake is forgetting that .claude/registry/LOOKUP.md requires paths to be repo-root-relative, not relative to .claude/. Also, expanding CLAUDE.md isn't necessary for routine registrations, as the searchable table now resides in the LOOKUP.md file since August 2026. Duplicate rows are another issue — if a doc or its directory is already mentioned, it's better to enhance the existing row's search terms rather than creating a new entry.

Validation

After these updates, I ran a validation script using python scripts/check_registered.py --root <repo>/.claude --doc <doc-path>. This script checks if the document is correctly registered and discoverable, preventing any oversight in the registration process.

These steps, drawn directly from the overnight build system's guidelines, ensure that new documentation is not only created but easily accessible, enhancing the usability of the entire codebase.