---
name: documentation-topology
description: Manage documentation topology and ownership metadata for codebases. Use when Codex needs to create or maintain docs/docs-config.json, inventory Markdown docs, assign doc status such as active/frozen/archived/generated, register topics, map canonical topic ownership, or validate frozen-doc constraints before editing.
---

# Documentation Topology

Use this skill to manage documentation topology, not product behavior.

This skill owns:

- `docs/docs-config.json`
- documentation inventory
- doc status such as `active`, `frozen`, `archived`, or `generated`
- topic registration
- canonical topic ownership in `topic_map`

Do not use this skill to rewrite documentation prose unless the user explicitly
asks for topology-only metadata updates to be accompanied by doc edits.

## 1. Workflow

### 1.1. Load or create docs config

Use `scripts/index_docs.py` first.

Always pass the target repository explicitly with `--root <target-repo>`. Do
not rely on the current working directory.

- Validate current topology with:
  `python scripts/index_docs.py --json --root <target-repo> --check`
- If `docs/docs-config.json` is missing and the task is in scope, create it
  with:
  `python scripts/index_docs.py --json --root <target-repo> --write-config`

Treat `docs/docs-config.json` as the source of truth for documentation
topology after it exists.

### 1.2. Validate topic ownership

Use:

- `python scripts/build_topic_map.py --json --root <target-repo>`
- `python scripts/build_topic_map.py --json --root <target-repo> --suggest-topics`

Check for:

- topics declared in docs but missing from `topic_map`
- topics missing from the top-level `topics` registry
- canonical topic collisions
- docs with no topics
- topics mapped to nonexistent docs

When reviewing or expanding doc topics:

- use `--suggest-topics` to see candidate topics inferred from filenames and
  headings
- do not treat every heading as a stored topic
- keep `topics` broad enough to cover what the doc materially discusses
- keep `canonical_topics` narrower and limited to the topics the doc owns as
  the primary source of truth

### 1.3. Create topics explicitly

Do not invent a hidden built-in topic list.

When a new topic is needed, create it explicitly in the config with:

- `python scripts/create_topic.py --json --root <target-repo> <topic>`

If the topic should be attached to a document:

- `python scripts/create_topic.py --json --root <target-repo> --path <doc-path> <topic>`

If the topic should also become canonical for that document:

- `python scripts/create_topic.py --json --root <target-repo> --path <doc-path> --canonical <topic>`

### 1.4. Check frozen docs

Before editing docs that may be restricted, run:

- `python scripts/check_frozen_docs.py --json --root <target-repo> <doc-path> [...]`

Do not edit docs marked `frozen`, `archived`, or `generated` unless the user
explicitly asks.

## 2. Rules

- Keep `docs/docs-config.json` aligned with actual files.
- Add newly created docs to the config when they are in scope.
- Remove deleted docs from the config.
- Update status when a doc becomes `frozen`, `archived`, or `generated`.
- Keep `topic_map` aligned with canonical topic ownership.
- Do not require every topic in `topics` to appear in `topic_map`; shared
  coverage topics may appear in multiple docs without one canonical owner.
- Do not assign the same canonical topic to multiple docs unless the user
  explicitly wants that ambiguity.
- Do not collapse each document to one topic by default; include all
  meaningful stable topics the doc materially covers.
- Use heading phrases as topic candidates when they represent stable sections
  of responsibility, such as API areas or operational domains.
- Keep topology metadata human-editable and lightweight.
- Do not store product behavior, API truth, config defaults, or command truth
  in `docs/docs-config.json`.

## 3. Script contract

Prefer JSON output.

Exit codes:

- `0` = success, no issues
- `1` = success, issues found
- `2` = config or usage error
- `3` = runtime failure

## 4. Bundled scripts

This sub-skill includes local bundled scripts:

- `scripts/index_docs.py`
- `scripts/build_topic_map.py`
- `scripts/create_topic.py`
- `scripts/check_frozen_docs.py`
- `scripts/doc_support.py`

Use these local scripts instead of reaching outside the skill folder.