The Topic Registry: A Plain-Language Guide

The topic registry is the catalog of a project’s documents. With this update it is built automatically: one command reads every document file, lists what is there, grouped by subject area, and points out labeling problems, without changing anything.

This guide is for people who work through Claude rather than a terminal. For the technical reference, see the plugin page[1].

1. What is the topic registry

Who this is for
Anyone who writes, reviews or looks after documents in an IKE project and works through Claude rather than a terminal: authors, reviewers, regulatory and quality staff, and project leads. No knowledge of Maven, Git or AsciiDoc is assumed.
Purpose
To give you a trustworthy, current picture of a project’s documents (what exists, where it is stored, which subject area it belongs to and whether each one is labeled correctly) in a few seconds, so that gaps are caught before a review or a submission rather than during one.

The registry is a fresh catalog of every document in a project, built by reading the label block at the top of each file. Think of a librarian walking the shelves and writing down each book’s title, subject and condition, instead of trusting an old card catalog that someone typed by hand.

Use it when you want to know:

  • What documents exist in this project, in which folders and under which subject areas?
  • Is every document labeled properly (name, type, status, keywords)?
  • What has been added since the catalog was last built?

The technical name is idoc:topic-registry. It is a command in the IKE documentation toolkit and works on any IKE documentation project, large or small. A test on a 290-document project finished in under a tenth of a second.

Before this update the registry was typed by hand, as a topic-registry.yaml file kept next to the documents. That file is no longer maintained; the registry the build writes is the current record.

You do not need to type commands. Ask Claude in plain words, as shown under each action below. The exact command is listed for reference.

2. Tutorial: your first registry

This walk-through takes about ten minutes. You will build the registry, read it, fix a problem it reports, and add a new document to it. The file names are made up for illustration; yours will differ.

2.1. Step 1: Build the registry

First, open the project in Claude. "The project" is the folder on your computer that holds the documents. Opening it tells Claude which folder to work in.

In the Claude desktop app (Mac or Windows)
  1. Open the Claude app and switch to the Code tab.
  2. Choose the project folder when Claude asks where to work. Pick the top folder of the project, the one that contains a file named pom.xml, not the documents folder inside it.
  3. Start a new session. The folder name shown in the session confirms you are in the right place.
In a web browser
  1. Go to https://claude.ai/code[2] and sign in.
  2. Pick the project’s repository from the list. This needs the project to be on GitHub and your GitHub account to be connected; Claude walks you through connecting it the first time.

If the project is not on your computer yet, ask the person who maintains it for the GitHub address, then tell Claude in the desktop app: "Download the project at <address> and open it."

To check that you are in the right place, ask: "Which folder are you working in, and does it have a pom.xml?"

Once the project is open, say:

Build the topic registry for this project.

Claude runs the command and shows you the result. Nothing in your project changes.

2.2. Step 2: Read the list

The result is a folder-by-folder list, followed by one summary line:

src/docs/asciidoc
  topics/
    cleaning-steps.adoc         ops-cleaning-steps     procedure  -
    device-description.adoc     dev-device-description concept    draft
  submission.adoc               assembly, 2 includes
registry: topics/cleaning-steps.adoc: missing required attribute :topic-status:
2 topics, 1 other file, 1 finding; topic registry written to target/topic-registry.yaml (41 ms)

Read it like this:

  • Each labeled document shows four things: its file name, its name (id), its type and its status.
  • A dash means that label is missing. Here cleaning-steps.adoc has no status.
  • The first part of a name, before the first hyphen, is its subject area: ops for ops-cleaning-steps, dev for dev-device-description. The saved file groups documents by it.
  • submission.adoc is a binder: a file that pulls two other documents together.
  • The line starting with registry: is a finding. It names the file and says what is wrong.
  • The last line counts everything and says where the registry file was saved.

2.3. Step 3: Fix the finding

The finding says cleaning-steps.adoc is missing its status label. You can fix it yourself by adding this line to the label block at the top of the file:

:topic-status: draft

Or let Claude do it:

Fix what the topic registry reported.

The registry itself never edits a document. Any change is made by you or by Claude, where you can review it.

2.4. Step 4: Run it again

Say:

Build the topic registry again.

The registry is rebuilt from scratch. The dash is replaced by draft, and the summary line now ends in 0 findings. That is the whole routine: run, read, fix, run again.

2.5. Step 5: Add a new document

Suppose a new document, storage-conditions.adoc, has just been added to the topics folder. You do not have to re-read the whole collection. Say:

Add topics/storage-conditions.adoc to the topic registry.

The result is short:

registry: topic ops-storage-conditions at topics/storage-conditions.adoc
added 1 file to target/topic-registry.yaml without rescanning (12 ms)

The new document is now in the registry, placed in its subject area and checked like every other document.

2.6. Step 6: Look something up

The saved registry is what Claude reads when you ask about the project’s documents. Say, for example:

Which documents in the topic registry cover storage conditions, and what status are they in?

If the project still has the hand-typed registry file next to the documents from before the update, you can also ask:

Compare the built registry with the hand-typed file and list the differences.

The built registry is the current record.

You have now used every part of the registry you are likely to need. The rest of this guide is reference.

3. Actions you can take

There are six actions. Action 1 is the one you will use almost every time. The others adjust it.

# Action Ask Claude
1 Build the registry "Build the topic registry for this project."
2 Add new documents without re-reading everything "Add the file X to the topic registry."
3 Look in different folders "Build the topic registry from the folders X and Y."
4 Save the registry somewhere else "Build the topic registry and save it to Z."
5 Allow a very large collection "Build the topic registry and raise the file limit to 10,000."
6 Turn the registry off "Skip the topic registry for this run."

3.1. Action 1: Build the registry

What it does
Reads every document file in the project’s standard documents folder and produces the catalog.
What you get
A folder-by-folder list on screen, a saved registry file, and a one-line summary such as "3 topics, 1 other file, 0 findings".
Good to know
If the project has no documents folder, the registry says so in one line and moves on. That is normal, not an error. It lets one request cover a whole group of projects at once. A project can also be set up so that the registry is rebuilt on every build; the plugin page shows how.
Exact command
mvn idoc:topic-registry

3.2. Action 2: Add new documents without re-reading everything

What it does
Reads only the files you name and merges them into the registry that already exists. List several files separated by commas.
When to use it
One or a few documents were just added or changed, and the collection is large enough that you do not want to re-read all of it.
Good to know
  • Adding the same file twice is safe; the newer entry replaces the older one.
  • The new document’s name is checked against the registry, so a duplicate name is still caught.
  • If no registry exists yet, a full build (Action 1) runs instead.
  • Deleted documents are not noticed this way. After deleting or moving documents, use Action 1.
  • Each file must be a document file inside one of the folders the registry covers. Otherwise the run stops and says which file to check.
Exact command
mvn idoc:topic-registry -Dike.topic-registry.add=src/docs/asciidoc/topics/storage-conditions.adoc

3.3. Action 3: Look in different folders

What it does
Points the registry at one or more folders you name, instead of the standard documents folder. List several folders separated by commas.
When to use it
Your documents live somewhere unusual, or you only care about one part of the collection.
Good to know
If a folder you name does not exist, the run stops and tells you which folder to check. This protects you from a typo silently producing an empty catalog.
Exact command
mvn idoc:topic-registry -Dike.topic-registry.roots=folderA,folderB

3.4. Action 4: Save the registry somewhere else

What it does
Writes the registry file to a location you choose. Normally it goes into the project’s temporary build folder as target/topic-registry.yaml.
When to use it
You want to keep a copy to share, or to compare two runs side by side.
Exact command
mvn idoc:topic-registry -Dike.topic-registry.output=/path/to/registry.yaml

3.5. Action 5: Allow a very large collection

What it does
Raises the safety limit on how many document files one folder may hold. The limit is 5,000 files.
When to use it
Only when a run stops with the message "More than 5000 .adoc files". The limit exists to catch the registry being pointed at the wrong, enormous folder by mistake.
Exact command
mvn idoc:topic-registry -Dike.topic-registry.maxFiles=10000

3.6. Action 6: Turn the registry off

What it does
Skips the registry for one run. Nothing is read and nothing is written.
When to use it
The registry is part of a larger automated job and you do not need it this time.
Exact command
mvn idoc:topic-registry -Dike.skip.topic-registry=true

Actions 3, 4 and 5 can be combined in a single request.

4. What you get back

Every full run gives you three things: a list on screen, a saved file, and a summary line.

The on-screen list
Folders, then each file inside. A labeled document shows its name, type and status. Any other file shows whether it is a binder that pulls other documents together, or a plain file. Step 2 of the tutorial shows an example.
The registry file
A saved, structured catalog with more detail, in the standard IKE registry layout: labeled documents grouped by subject area, then binders, then plain files, then findings. This is the file Claude reads when you ask what the project contains.
The summary line
Counts of labeled documents, other files and problems found, plus where the file was saved and how long the run took.
For each labeled document For every other file
Name (id), file location and title File location and title
Type, status and origin Whether it is a binder (assembly) or a plain file
Keywords, summary and related documents How many documents it pulls in
Length in characters Its document settings
Whether the label block is complete, or what is missing

The registry file is rebuilt from scratch on every full run. Do not edit it and do not store it with the project’s documents. If you want to keep one, use Action 4.

5. Problems it points out

The registry reports labeling problems, called findings, but never stops the run because of them. Each finding names the file it concerns. Findings appear as warnings on screen and in a list at the end of the registry file.

The message says What it means How to fix it
missing required attribute The label block lacks one of the four required labels: name (id), type, status or keywords. Add the missing label at the top of the file.
unknown type The type is not one of: concept, task, procedure, reference, dialog. Change it to one of the five.
unknown status The status is not one of: draft, proposed, review, published, deprecated. Change it to one of the five.
no anchor before the heading The bookmark that lets other documents link to this one is missing. Add the bookmark line, matching the document’s name.
anchor does not match The bookmark and the document’s name differ, so links may break. Make the two identical.
no level-1 heading The document has no main title. Add a title line.
duplicate id Two files claim the same name. The message names both. Rename one of them.
symbolic link, skipped The file is a shortcut to another file. Shortcuts are never followed, so it was not read. Usually none needed. Replace the shortcut with a real file if it belongs here.

Only labeled documents are checked. Binders and plain files are listed but never produce findings.

6. What it never does

The registry only reads your documents and writes one file of its own. It is safe to run at any time, as often as you like.

  • It never edits, moves, renames or deletes a document.
  • It never touches the registry file that was typed by hand before the update. That file is no longer maintained; the built registry is the current record.
  • It never fails a run because of a labeling problem. Problems are reported, not enforced.
  • It never reads outside the folders it was given. Shortcuts that point elsewhere are skipped and reported.
  • It ignores working folders that hold no real documents (target, .git, node_modules).

A run stops early in only a few cases: a folder or file you named does not exist or is outside the registry’s folders (Actions 2 and 3), the file limit is exceeded (Action 5), or a file or folder cannot be read or written. Each message says what to check.

7. Words used in this guide

Word Meaning
Document file A text file ending in .adoc, the format IKE documents are written in (AsciiDoc).
Label block The lines at the top of a document that state its name, type, status, keywords and other details. Technically, the :topic-*: header.
Labeled document (topic) A document that has a label block with a name.
Subject area (domain) The first part of a document’s name, before the first hyphen: ops in ops-cleaning-steps. The registry groups documents by it.
Binder (assembly) A file that pulls other documents together into one larger document.
Plain file A document file with no label block that pulls nothing in.
Topic registry The automatically built catalog, target/topic-registry.yaml.
Registry file before the update The hand-typed topic-registry.yaml kept next to the documents, no longer maintained now that the registry is built on every run.
Finding A labeling problem the registry noticed.
Searching...
No results.