---
name: add-docs-links
description: Maintains the PatternFly MCP documentation catalog in src/docs.json—add, edit, or remove entries with correct raw URLs, meta, and validation. Use when the user asks to add or register documentation links, update or fix docs.json entries, remove catalog rows, contribute to the docs catalog, or align with docs.json tests and CI audit.
---

# Add Documentation Links to docs.json

## When to use

- User wants to **add**, **change**, or **remove** rows in `src/docs.json`, or fix broken / unreachable catalog links
- User provides a GitHub URL (blob or raw) to register in the catalog — convert blob → raw, pick refs, verify reachability, shape entries, update `meta` and `generated`, and run tests
- User asks to update or fix `docs.json` entries, contribute to the docs catalog, or align with docs.json tests and CI audit

For **edits or removals**: find the row by `path` and/or its `docs` key; update `meta` / `generated`; run tests. Same rules as adds: whitelist, unique `path`, and `src/__tests__/docs.json.test.ts` (including `baseHashes` and the Repository Breakdown table when refs change).

## Workflow

1. **Resolve raw URL and ref**
   - Map the link to `owner/repo` and file path; build **raw** `https://raw.githubusercontent.com/{owner}/{repo}/{ref}/{file}`.
   - Prefer the **same `ref`** already used in `docs.json` for that `patternfly/<repo>` (copy from an existing `path`).
   - **New** `patternfly/<repo>` (or new ref / `rh-uxd/<repo>`): after you add URLs, open `docs.json.test.ts` and update `expect(baseHashes.size)` **and** the Repository Breakdown table (including the **Total** row)—do not guess counts from this skill.
   - New ref for an existing repo: resolve SHA (e.g. commits API) or use a stable tag.

2. **Whitelist**
   - `path` must match `whitelist.urls` in `src/options.defaults.ts`. See [reference.md — URL whitelist](reference.md#url-whitelist-allowed-domains). Use **https** only. Do not widen the whitelist in a catalog-only PR.

3. **Reachability**
   - Response must be 2xx (e.g. `curl -sI -o /dev/null -w "%{http_code}" "<url>"`). If not, fix ref or path; do not add a dead link.

4. **Unique `path`**
   - Each `path` appears once in the whole file.

5. **Placement in `docs`**
   - **New top-level key** under `docs` (e.g. `"AiHelpers"`): append as the **last property** inside `"docs": { … }` (after the current last key’s block). Do not insert mid-file by theme or alphabet.
   - **New object** in an **existing** key’s array: append to the **end of that array** unless the user specifies order.
   - **Edits**: keep the same key and array index unless the user asks to move.

6. **Entry shape**
   - Fields and types: [reference.md — Entry format](reference.md#entry-format). Copy `section` / `category` from the closest similar row when unsure.

7. **`meta` and `generated`**
   - `meta.totalEntries` = number of keys in `docs`.
   - `meta.totalDocs` = total objects across all arrays.
   - `generated` = `new Date().toISOString()`.

8. **Tests**
   - From repo root: `npm test` or `jest --selectProjects unit --roots=src/`.
   - If snapshots fail, update only where the catalog drives output (`docs.embedded`, `tool.patternFly*`, `resource.patternFlyDocs*`), e.g. scoped `npm test -- -u path/to/file.test.ts`.

**CI:** `.github/workflows/audit.yml` on PRs that touch `src/docs.json` or `tests/audit/**`.

## Additional resources

- [reference.md](reference.md) — entry format, top-level structure, URL whitelist, duplicate check, ref lookup, unit test constraints, example entry

## Quick checks

- [ ] Blob → raw; ref reused per repo when possible.
- [ ] `path` whitelisted, **https**, 2xx.
- [ ] No duplicate `path`.
- [ ] New **keys** at **end** of `docs`; new **array rows** at **end** of the target array.
- [ ] `meta` and `generated` updated.
- [ ] New repo/ref: `docs.json.test.ts` `baseHashes` size **and** Repository Breakdown table (Total row) still match.
- [ ] Tests pass; snapshots updated only if catalog-driven output changed.