# Xh Update Doc Links > Pre-commit documentation consistency check. Ensures docs/README.md index, docs/planning/docs-roadmap.md, and the MCP server's document registry (docs/doc-registry.json) stay in sync with documentation files on disk. Validates inter-doc links and enhances cross-references when new docs are added. Use this skill whenever adding, renaming, moving, or deleting any README or concept doc — and before committing documentation changes. Also use when asked to "update the docs index", "check doc links", or "sync the doc registry". Use when this capability is needed. - Skill: `tomevault-io/xh-update-doc-links` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/xh-update-doc-links` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/xh-update-doc-links/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/xh-update-doc-links --- # xh-update-doc-links — Documentation Consistency Check Pre-commit skill to ensure documentation index files, the MCP document registry, inter-doc links, and cross-references stay consistent after editing READMEs or concept docs. This skill syncs indexes and links — it does not write or rewrite documentation content. See `xh-update-docs` for creating or updating doc content. ## Step 1: Discover Documentation Files Build a complete inventory of documentation files on disk. 1. Use `Glob` to find all `**/README.md` files, excluding `node_modules/`, `public/`, and `static/` directories. 2. Use `Glob` to find all files under `docs/`. 3. Run `git diff --name-only` and `git status --porcelain` to identify which docs were recently changed or added. 4. Build a master list of all documentation files, noting which are new or recently modified. ## Step 2: Read Index Files Read the two index files and parse their current entries. 1. Read `docs/README.md` — focus on the **Package Documentation** section (the tables under "Core Framework", "Components", "Utilities", "Concepts", and "Other Packages"). - Parse each table row to extract the package path and linked README path. - Parse the "Other Packages" paragraph to extract unlisted package names. 2. Read `docs/planning/docs-roadmap.md` — parse all priority tables and the Concepts table. - Extract each package path, description, and status value. - Note which entries are `Planned`, `Drafted`, or `[Done](link)`. ## Step 3: Reconcile Indexes Compare documentation on disk against both index files. ### docs/README.md Reconciliation For each README on disk: - Check if it has an entry in the appropriate `docs/README.md` table (Core Framework, Components, Utilities, Concepts, or Other Packages). - **Missing entries:** Add a new table row in the correct section using this format: ```markdown | [`/package/`](../package/README.md) | One-sentence description | Key, Topics, Here | ``` (Note: paths are relative from `docs/`, so package READMEs use `../` prefix.) - **Stale entries:** If an entry links to a README that no longer exists, remove it. - **Promotion:** If a package is listed in the "Other Packages" paragraph and now has a README, move it to the appropriate table and remove it from the paragraph. - **AGENTS.md directive:** Verify that `AGENTS.md` still contains the directive pointing to `docs/README.md` (the "Hoist Documentation" section). Do not re-add package tables to AGENTS.md. ### docs-roadmap.md Reconciliation For each README on disk: - Check if it has an entry in `docs/planning/docs-roadmap.md` with the correct status. - **Status updates:** Change `Planned` → `[Done](../../path/README.md)` for newly completed docs. Change `Drafted` → `[Done](../../path/README.md)` if appropriate. - **Missing entries:** Add entries for docs not yet on the roadmap. - **Progress notes:** When meaningful changes occur (new docs indexed, status promotions, registry additions — not minor link fixes or cosmetic cleanups), append a progress note entry for the current date to `docs/planning/docs-roadmap-log.md`. Follow the existing chronological format. ## Step 4: Validate Inter-Doc Links Scan every documentation file (READMEs + concept docs) for relative markdown links. 1. For each file, extract all markdown links matching `[text](path)` where `path` is a relative path (not a URL). 2. Resolve each relative path from the source file's directory. 3. Verify the target exists on disk. 4. **Broken links:** Report and fix. Common fixes include: - Correcting `../` depth for moved files - Updating paths for renamed files - Removing links to deleted files ## Step 5: Enhance Cross-Links When new or recently changed docs are detected, look for cross-linking opportunities. 1. **Topic-based linking:** Scan existing READMEs for sections that discuss the same topic as a new doc. Where an existing README has a brief treatment of a topic that now has dedicated documentation, add a contextual "See [`/package/`](path) for details" link. 2. **Related Packages sections:** Check if a new README was created for a package that is referenced without a link in another doc's "Related Packages" section. Add the link using the format: ```markdown - [`/package/`](path) - Brief description ``` 3. **Be conservative:** Only add links where the existing text already discusses the topic. Do not restructure existing content or add new sections just to create links. Do not rewrite or rephrase existing prose — only insert link references. ## Step 6: Reconcile Document Registry Ensure `docs/doc-registry.json` reflects the current documentation on disk. This JSON file is the single source of truth for both the MCP server (which loads it at startup via `mcp/data/doc-registry.ts`) and the toolbox documentation viewer. 1. **Read and parse** `docs/doc-registry.json`. Each entry in the `entries` array is a JSON object. The entry's `id` field is also the file path relative to the repo root (e.g. `cmp/grid/README.md`, `docs/lifecycle-app.md`). 2. **Detect missing entries** — compare the Step 1 documentation inventory against registry entry `id` fields. For each unregistered doc, add a new entry with these fields: - `id`: file path relative to repo root (e.g. `cmp/grid/README.md`, `docs/upgrade-notes/v82-upgrade-notes.md`). This doubles as the unique identifier. - `title`: derived from the doc's top-level `# heading`. - `mcpCategory`: MCP category — one of `package`, `concept`, `devops`, `conventions`, or `index`. - `viewerCategory`: toolbox viewer category — one of `overview`, `concepts`, `core`, `components`, `desktop`, `mobile`, `utilities`, `supporting`, `devops`, or `upgrade`. - `description`: concise one-sentence summary matching existing entry style. - `keywords`: 5–12 key terms as a JSON array of strings — include API names, class names, and topic terms. 3. **Place entries** in logical order within the `entries` array (grouped by category). 4. **Remove stale entries** whose `id` (file path) no longer exists on disk. 5. **Update moved/renamed docs** — fix `id` values (and `title` if the change is structural). 6. **Verify existing entries** — spot-check that metadata (title, description, keywords) is still accurate for recently changed docs. Only fix entries that are clearly stale or incorrect; do not rewrite working entries for style. ## Step 7: Report Output a summary organized into these sections: 1. **Index Updates** — `docs/README.md` entries added, updated, or removed. 2. **Roadmap Updates** — Status changes and new entries in `docs-roadmap.md`, progress notes appended to `docs-roadmap-log.md`. 3. **Broken Links Fixed** — Source file, broken target, and fix applied. 4. **New Cross-Links Added** — Source file, target doc, and surrounding context. 5. **Registry Updates** — Entries added, removed, or updated in `docs/doc-registry.json`, with `id` for each change. 6. **Items Needing Review** — Ambiguities or items requiring human judgment. If no changes were needed in a category, note "None" for that section. --- > Source: [xh/hoist-react](https://github.com/xh/hoist-react) — distributed by [TomeVault](https://tomevault.io).