feat(tooling): pf-4720 add pf-docs collections

docs/development.md

@@ -544,8 +544,9 @@ The server maintains multiple record collections that provide documentation and
 #### General collection reseeding
 
 When PatternFly releases new documentation or component features, reseed the embedded local collection data:
-- `npm run build:collections`: Runs the complete crawler and manifest update pipeline and runs collection tests.
+- `npm run build:collections`: Runs reseeding for all collections and collection tests.
 - `npm run build:collections-api`: Updates `src/collection.patternFlyApi.json` and outputs CSV diffs to `reports/`.
+- `npm run build:collections-docs`: Updates `src/docs.json` with latest repository hashes.
 
 #### Unique collections
 
@@ -555,19 +556,27 @@ When PatternFly releases new documentation or component features, reseed the emb
 
 The original curated Markdown collection. It pins remote repository URLs to specific Git commit SHAs to guarantee consistent documentation and remove upstream breaking changes.
 
-- **Update workflow**: Follow the [add-docs-links skill](../guidelines/skills/add-docs-links/SKILL.md) to add, update, or remove entries.
+- **Update workflow**: Follow the [add-docs-links skill](../guidelines/skills/add-docs-links/SKILL.md) for manual additions/edits, or run the automated reseeding script:
+  ```bash
+  # Reseed the Docs collection
+  npm run build:collections-docs
+
+  # Run collection test suites only
+  npm run test:collections
+
+  # Run collection test suites in watch mode
+  npm run test:collections-dev
+  ```
+- **Automated synchronization**: The Docs reseeding pipeline (`tooling/collections/update.patternFlyDocs.ts`) automatically resolves the latest commit SHAs across referenced GitHub repositories, recalculates `meta.totalEntries` and `meta.totalDocs`, and generates an audit diff report at `reports/YYYYMMDD-collection.patternFlyDocs.report.csv`.
 - **Validation**: Ensure all raw URLs are HTTPS, match the domain whitelist in `src/options.defaults.ts`, and return 2xx responses.
-- **Testing**: Run `npm test` and update `baseHashes` and the Repository Breakdown table in `src/__tests__/docs.json.test.ts` whenever refs change.
+- **Testing**: Run `npm run test:collections` or `npm test`, updating `baseHashes` and the Repository Breakdown table in `src/__tests__/docs.json.test.ts` when refs change.
 
 ##### 2. Pre-built API collection (`src/collection.patternFlyApi.json`)
 
 The server packages pre-seeded API endpoints to enable instant server startup without network overhead.
 
 - **Update commands**:
   ```bash
-  # Reseed the API collection and run collection test suites
-  npm run build:collections
-
   # Reseed the API collection
   npm run build:collections-api
 

guidelines/README.md

@@ -37,7 +37,7 @@ Agents should use these phrases as signals to consult specific documentation and
 | **"review development guide"**      | Review `docs/development.md` for CLI, API, and plugin authoring.                                                                                       |
 | **"create an example tool plugin"** | Review `guidelines/agent_coding.md`, `docs/development.md`, `docs/examples/*`, and `src/*` for context, coding standards, and existing example formats. |
 | **"add documentation links"** / **"add doc entries"** / **"register docs"** / **"update docs.json"** / **"contribute to docs.json"** | Follow `guidelines/skills/add-docs-links/SKILL.md`: docs.json format, duplicate check, raw URL confirmation, then run unit tests and update meta. |
-| **"reseed collections"** / **"update collections"** / **"build collections"** | Follow `docs/development.md#updating-collections`: run `npm run build:collections` (or `build:collections-api`) to sync API records. |
+| **"reseed collections"** / **"update collections"** / **"build collections"** / **"refresh docs manifest"** | Follow `docs/development.md#updating-collections`: run `npm run build:collections` (or `build:collections-api` / `build:collections-docs`) to sync API records and docs manifest. |
 | **"review zod"** / **"zod upgrade"** / **"zod integration review"** / **"zod update report"** | Follow `guidelines/skills/review-zod-integration/SKILL.md`: release notes vs codebase, tests, report at `reports/YYYYMMDD-HHMMSS-zod-{semver}-update-report.md` (UTC). |
 | **"troubleshoot server"** / **"debug server"** | Review `docs/usage.md#troubleshooting` and the PatternFly MCP server resource `patternfly://context` |
 

package.json

@@ -35,8 +35,9 @@
     "build": "npm run build:clean; npm run test:types; pkgroll",
     "build:clean": "rm -rf dist",
     "build:watch": "npm run build -- --watch",
-    "build:collections": "npm run build:collections-api && jest --selectProjects tooling:collections",
+    "build:collections": "npm run build:collections-api && npm run build:collections-docs && jest --selectProjects tooling:collections",
     "build:collections-api": "UPDATE_COLLECTIONS=true tsx ./tooling/collections/update.patternFlyApi.ts",
+    "build:collections-docs": "UPDATE_COLLECTIONS=true tsx ./tooling/collections/update.patternFlyDocs.ts",
     "container:build": "bash ./scripts/container.build.sh",
     "container:start": "bash ./scripts/container.run.sh",
     "release": "changelog --non-cc --link-url https://github.com/patternfly/patternfly-mcp.git",

src/__tests__/docs.json.test.ts

@@ -74,7 +74,7 @@ describe('docs.json', () => {
      *
      * | Repository | Hash / Branch | Count | Type |
      * |---|---|---|---|
-     * | uxd-ai-helpers | e8cca17430a8ccb062ed1878073165417a081b34 | 6 | **Primary** |
+     * | uxd-ai-helpers | e8cca17430a8ccb062ed1878073165417a081b34 | 6 | One-off |
      * | patternfly-cli | ce032cd16ddb90c540cb4f18c6830e190cd9e3e9 | 1 | One-off |
      * | patternfly-elements | 402b3b0e7ed73cb2aa21531e0eab4216c2211212 | 1 | One-off |
      * | patternfly-mcp | 4e1cd7c636f6ac17c851f54a920549e5377f3809 | 5 | One-off |

tests/audit/api.audit.test.ts

@@ -4,10 +4,10 @@ import { expandApiEmbeddedCollection, type ApiEmbeddedCollection } from '../../s
 import { checkUrl } from './utils/checkUrl';
 
 describe('PatternFly API Link Audit', () => {
-  const catalogPath = resolve(process.cwd(), 'src/collection.patternFlyApi.json');
-  const raw = readFileSync(catalogPath, 'utf-8');
-  const catalog: ApiEmbeddedCollection = JSON.parse(raw);
-  const expanded = expandApiEmbeddedCollection(catalog);
+  const collectionPath = resolve(process.cwd(), 'src/collection.patternFlyApi.json');
+  const raw = readFileSync(collectionPath, 'utf-8');
+  const collection: ApiEmbeddedCollection = JSON.parse(raw);
+  const expanded = expandApiEmbeddedCollection(collection);
 
   // Sample a subset across records
   const maxSample = Number(process.env.API_AUDIT_MAX_TOTAL ?? 20);

tests/audit/docs.audit.test.ts

@@ -1,11 +1,19 @@
 import { randomInt } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { jest } from '@jest/globals';
-import docs from '../../src/docs.json';
+import { type PatternFlyMcpDocsCatalog } from '../../src/docs.embedded';
 import { checkUrl } from './utils/checkUrl';
 
 describe('Documentation Link Audit', () => {
   let auditSet: string[] = [];
 
+  const collectionPath = resolve(process.cwd(), 'src/docs.json');
+
+  const docs: PatternFlyMcpDocsCatalog = existsSync(collectionPath)
+    ? JSON.parse(readFileSync(collectionPath, 'utf-8'))
+    : { meta: { totalEntries: 0, totalDocs: 0, source: '' }, docs: {} };
+
   /**
    * Extracts and returns a prefix based on the provided URL.
    * - If the hostname is not "raw.githubusercontent.com", the hostname is returned.