docs: update usage, architecture, maintenance

* contributing, node maintenance schedule
* architecture, recent adds for features and planning
* development, minor adds for node maintenance, future work
* usage, add recent adds, refactors for tools, resources

Author: cdcabrera

CONTRIBUTING.md

@@ -59,7 +59,7 @@ Development pull requests (PRs) should be opened against the default branch.
 > If your pull request work contains any of the following warning signs
 >  - has no related issue
 >  - ignores existing code style
->  - out of sync commits (not rebased against the default branch)
+>  - out-of-sync commits (not rebased against the default branch)
 >  - poorly structured commits and messages
 >  - any one commit relies on other commits to work (beyond "review requested updates")
 >  - dramatic file restructures that attempt complex behavior
@@ -142,9 +142,28 @@ npm run test:integration
 
 This mode leverages the `--mode test` and `--mode-test-url` flags to redirect resource lookups to a fixture server instead of live or local resources.
 
+## Maintenance: Node.js engine bumps
+
+The `Node.js` engine requirements are updated on a predictable biannual schedule to ensure the server remains secure, leverages modern runtime features, and provides stability for consumers.
+
+> Our engine requirements are intended to be the minimum to run the MCP server. They are not intended to be a maximum, as newer versions may introduce breaking changes or require additional configuration.
+
+### Schedule and process
+- **Timing**: Bumps are generally targeted for **Spring (April/May)** and **Fall (October/November)**, aligned with the [Node.js release schedule](https://nodejs.org/en/about/previous-releases) as versions enter or exit LTS.
+- **Security**: Out-of-band updates may be performed if critical security considerations arise.
+- **Version Targets**:
+  - Focus on the latest **even-numbered (LTS/Stable)** versions (e.g., bumping to 22, 24, or 26).
+  - GitHub Workflows should be updated to include the latest available even version.
+
+### Acceptance criteria for bumps
+- Update `package.json` engine requirements.
+- Update related GitHub Action workflows (CI/CD).
+- Update "Environmental Requirements" in documentation.
+- Ensure all tests pass on the new target version.
+
 ## AI agent
 
-### User Section
+### User section
 
 Current agent interaction can be triggered with the chat command
 
@@ -162,7 +181,7 @@ to allow customization for your work environment through a tool-agnostic git-ign
 Please reference [PatternFly's AI-assisted development guidelines](https://github.com/patternfly/.github/blob/main/CONTRIBUTING.md) for guidance on how to
 acknowledge AI agent contributions.
 
-### Agent Only
+### Agent only
 Agents: This repository contains a hierarchical guideline system. Agents should review agent-only comment blocks.
 
 <!--

README.md

@@ -10,7 +10,7 @@ It is intended to be extensible to meet the needs of different teams and project
 - [Node.js 20+](https://nodejs.org/)
 - NPM (or equivalent package manager)
 
-## Quick Start
+## Quick start
 
 The PatternFly MCP Server supports multiple configurations; see the [usage documentation](./docs/usage.md#mcp-client-configuration) for details.
 

docs/README.md

@@ -1,16 +1,16 @@
-# PatternFly MCP Server Documentation
+# PatternFly MCP Server documentation
 
 Welcome to the PatternFly MCP Server documentation. This guide is organized by user intent.
 
 ### 🚀 Usage
 - **[MCP Tools and Resources](./usage.md)**: Use built-in tools and resources like `searchPatternFlyDocs` and `usePatternFlyDocs`.
 - **[Client Configuration](./usage.md)**: Configure the server for your environment.
 
-### 🛠️ Developer Reference
+### 🛠️ Developer reference
 - **[CLI Reference](./development.md#cli-usage)**: Reference of server options.
 - **[API Reference](./development.md#programmatic-usage)**: Using the server as a base library in your own Node.js MCP.
 - **[Examples](./examples/README.md)**: Standalone snippets for HTTP transport, embedding, and custom tools.
 
-### 🏗️ Architecture & Design
+### 🏗️ Architecture & design
 - **[System Architecture](./architecture.md)**: Design concept and architecture.
 - **[Roadmap](./architecture.md#roadmap)**: Future plans for the project.

docs/architecture.md

@@ -6,29 +6,27 @@ The PatternFly MCP server is centered around the concept of a library for all th
 
 ### The library, PatternFly integration
 
-PatternFly integration is centered around the following current, and future, tools:
-- Searching for a resource
-- Use and read a resource
-- Finding, or discovering, a resource
+The current PatternFly MCP server provides a hybrid documentation system that will merge baseline guidelines with dynamic content. It is centered around a **Resource Metadata** discovery layer that powers the following core concepts:
 
-#### Search PatternFly documentation
+- **Searching for resources**: Querying the library for relevant documentation and components.
+- **Reading resources**: Accessing full documentation and machine-readable schemas.
+- **Discovering resources**: Navigating the library via resource indexes and URI templates.
 
-A built-in tool for searching PatternFly documentation and resources integrated into the server.
+#### Discovery layer (resource metadata)
 
-#### Use PatternFly documentation
+Instead of a standalone "discovery" tool, the server implements a robust **Resource Metadata system**. This system:
+- Generates automated indexes for all available documentation (`patternfly://docs/index`), components (`patternfly://components/index`), and schemas (`patternfly://schemas/index`).
+- Supports completion logic for MCP clients, allowing LLMs and users to browse available resources effortlessly.
+- Provides parameterized URI templates (RFC 6570) like `patternfly://docs/{name}` for direct, predictable access.
+- Provides generated `meta` resources that document available MCP resource template parameters for MCP clients that do not have completion (`patternfly://docs/meta`, `patternfly://components/meta`, `patternfly://schemas/meta`).
 
-A built-in tool for reading and using PatternFly documentation and resources integrated into the server.
+> This discovery layer treats the MCP server as a living library. It enables the server to provide updates for all built-in tools and resources while maintaining a tailored experience based on user patterns (e.g., tailoring responses for designers vs. developers).
 
-#### Find and discover PatternFly documentation
+#### Hybrid documentation model (in-progress)
 
-An evolving "future" tool (still undergoing refinement) for finding PatternFly documentation and resources not directly integrated into the server.
-
-> This tool treats the MCP server as a library. Like a library, sometimes you need an interlibrary loan to gain access to the resource you need.
->
-> The interlibrary concept is key because it starts to highlight that this third MCP tool could
-> - Help provide updates for all PatternFly MCP server built-in tools, resources, and prompts
-> - Maintain up-to-date documentation and resources
-> - Provide a tailored experience for users based on their use patterns (e.g., a designer's experience is tailored to design, a developer's experience is tailored to development)
+We'll be introducing our hybrid documentation model in upcoming releases. This concept balances stability and currentness by integrating core guidelines and standards directly into the server while syncing from the latest available PatternFly implementation.
+- **Baseline Data**: Core guidelines and standards integrated directly into the server for standalone purposes, quick starts, and immediate access.
+- **Dynamic Content**: Content synced from the latest available PatternFly implementation while you work, ensuring the LLM always has access to the latest documentation and patterns.
 
 ### Tools, resources, and prompts as customizable plugins
 
@@ -48,60 +46,74 @@ Key goals aided by moving towards plugins:
 flowchart TD
   subgraph A1["MCP server"]
     subgraph E1["Session context"]
-      subgraph F1["Logging, stats context"]
+      subgraph F1["Logging, Resource discovery context"]
         subgraph F1A["Built-In tools"]
-          F1AA(["Search PF docs"])
-          F1AB(["Use PF docs"])
+          F1AA(["Search PatternFly docs"])
+          F1AB(["Use PatternFly docs"])
         end
-        F1B --> F1A
-        F1B(["Built-In resources"])
+        F1B <--> F1A
+        F1B(["Built-In resources & discovery layer"])
       end
     end
     D1(["Server proxy"])
+    D1 <--> F1
+    subgraph G1["Child process host"]
+      G1A(["Tools host & isolation sandbox"])
+    end
+    D1 <--> G1
   end
-  B1(["Local external tools, prompts, resources"])
+  B1(["Local and remote external tools, prompts, resources"])
   B1 <--> D1
 ```
 
 ## Roadmap
 
 ### Planned features and integrations
 
-To get towards our future state, there are a series of planned features and integrations.
+Our roadmap focuses on expanding the server's reach and providing a more integrated development experience.
 
-Current focus:
-- **YAML configuration for remote tools, resources and prompts** - YAML configuration for remote MCP tools, resources, and prompt plugins
-- **MCP resource, prompts, and helper function sharing** - A way to share MCP resources, prompts, and helper functions towards external tool plugins.
-- **Find PatternFly documentation tool** - A tool that reaches out to known PatternFly documentation sources, caches locally, and integrates the results with existing MCP tools and resources.
-- **PatternFly API integration** - A JSON API for PatternFly documentation, components, and patterns.
-- **Hosted resource for sharing MCP tools, resources, prompts** - Shared tooling customization through PatternFly AI tooling repository (or equivalent)
+#### In-progress
+- **Hybrid documentation model**: A JSON API for documentation, components, and patterns that ensures the server is always in sync with the latest releases.
+   - **PatternFly API Integration**: Embedded integration into the server for standalone purposes, quick starts, and immediate access.
+   - **Child Process Lifecycle Management**: Background process while you work for API synchronization.
 
-Under consideration:
-- **MCP client** - A tailored MCP client specific for the PatternFly MCP server.
-- **Auditing for shared tools, resources, and prompts** - An auditing tool that helps you refine your shared tools, resources, and prompts.
-- **Containerized PatternFly MCP server, client, and LLM** - A containerized PatternFly MCP server, client, and embedded LLM. Use your own PatternFly chat client resource.
+#### In-planning and under review
+- **Resource-Tool Integration**: Directly integrate MCP resources into tool responses to reduce token counts and allow tools to accept URI links as inputs.
+- **Environment & Analysis Tooling**: A third built-in tool focused on environment snapshots, code analysis, and whitelisted resource access for local project analysis.
+- **Agentless MCP Client**: An MCP client for use without an LLM, allowing PatternFly tooling to integrate into CLI tools and CI/CD pipelines.
+- **YAML Configuration**: Remote tool, resource, and prompt plugins configured via YAML.
+- **Resource/Helper Sharing**: Mechanisms to share resources and helper functions across external tool plugins.
 
 #### Future state
 
 ```mermaid
 flowchart TD
   subgraph A1["MCP server"]
     subgraph E1["Session context"]
-      subgraph F1["Logging, stats context"]
+      subgraph F1["Logging, Resource discovery context"]
         F1C(["Built-In prompts"])
         F1C <--> F1A
         subgraph F1A["Built-In tools"]
-          F1AA(["Search PF docs"])
-          F1AB(["Use PF docs"])
-          F1AC(["Find PF docs"])
+          F1AA(["Search PatternFly docs"])
+          F1AB(["Use PatternFly docs"])
+          F1AC(["Analyze environment"])
         end
         F1B <--> F1A
-        F1B(["Built-In resources"])
+        F1B(["Built-In resources & discovery layer"])
       end
     end
-    F1B --> D1
     D1(["Server proxy"])
+    D1 <--> F1
+    subgraph G1["Child process host"]
+      G1A(["Tools host & isolation sandbox"])
+      G1B(["API synchronization process"])
+    end
+    D1 <--> G1
+  end
+  subgraph H1["Agentless client layer"]
+    H1A(["CLI & Automation integration"])
   end
+  A1 <--> H1
   B1(["Local and remote external tools, prompts, resources"])
   B1 <--> D1
 ```

docs/development.md

@@ -7,8 +7,10 @@ Complete guide to using the PatternFly MCP Server for development including CLI
 - [Programmatic Usage](#programmatic-usage)
 - [Tool Plugins](#tool-plugins)
 - [Initial Troubleshooting](#initial-troubleshooting)
+- [Project Maintenance](#project-maintenance)
+- [In-progress and future work](#in-progress-and-future-work)
 
-## CLI Usage
+## CLI usage
 
 ### Available options
 
@@ -128,6 +130,11 @@ const server: PfMcpInstance = await start(options);
 
 The documentation catalog `src/docs.json` pins remote resources to specific commit SHAs (or explicit refs) for stability and reproducibility. This avoids unexpected upstream changes from breaking results. The `searchPatternFlyDocs` tool handles these lookups transparently for the user.
 
+#### Environmental requirements
+
+- **Node.js 20+**: Required to run the core MCP server.
+- **Node.js 22+**: Required for loading external tool plugins (`--tool`) and for developers working on advanced process isolation features.
+
 **Example: Programmatic test mode**
 ```typescript
 import { start, type PfMcpInstance } from '@patternfly/patternfly-mcp';
@@ -220,7 +227,7 @@ const logSubscription = subscribe(logChannel, logHandler);
 
 Reference typings are exported from the package. The full listing can be found in [src/index.ts](../src/index.ts).
 
-### Embedding the Server
+### Embedding the server
 
 You can embed the MCP server inside your application using the `start()` function and provide **Tool Modules** directly.
 
@@ -271,13 +278,13 @@ See [examples/](examples/) for more programmatic usage examples.
 
 You can extend the server's capabilities by loading **Tool Plugins** at startup. These plugins run out‑of‑process in an isolated **Tools Host** to ensure security and stability.
 
-### Environmental Requirements
+### Environmental requirements
 
 - **Node.js >= 22**: Loading external tool plugins (`--tool`) requires Node.js version 22 or higher due to the use of advanced process isolation and ESM module loading features.
 - **ESM**: Plugins MUST be authored as ECMAScript Modules.
 - **Dependency Resolution**: Plugins importing from `@patternfly/patternfly-mcp` require the package to be resolvable in the execution environment. This may require a local `npm install` in the plugin's directory or project root if the package is not available globally.
 
-### Security & Isolation
+### Security & isolation
 
 The server provides two isolation modes for external plugins via the `--plugin-isolation` flag:
 
@@ -293,7 +300,7 @@ The server provides two isolation modes for external plugins via the `--plugin-i
 - **`Tool Factory`**: A function wrapper `(options) => Tool` (internal).
 - **`Tool Module`**: The programmatic result of `createMcpTool`, representing a collection of tools.
 
-### Authoring Tools
+### Authoring tools
 
 We recommend using the `createMcpTool` helper to define tools. It ensures your tools are properly normalized for the server.
 
@@ -329,7 +336,7 @@ export default createMcpTool([
 ]);
 ```
 
-#### Input Schema Format
+#### Input schema format
 
 The `inputSchema` property accepts either **plain JSON Schema objects** or **Zod schemas**. Both formats are automatically converted to the format required by the MCP SDK.
 
@@ -357,24 +364,31 @@ const inputSchema = z.object({
 
 See [examples/toolPluginHelloWorld.js](examples/toolPluginHelloWorld.js) for a basic example.
 
-## Initial Troubleshooting
+## Initial troubleshooting
 
-### Tool Plugins
+### Tool plugins
 
 - **Plugins don't appear**: Verify the Node version (requires Node.js >= 20; >= 22 for tool plugins) and check logs (enable `--log-stderr`).
 - **Startup warnings/errors**: Startup `load:ack` warnings/errors from tool plugins are logged when stderr/protocol logging is enabled.
 - **Schema errors**: If `tools/call` rejects with schema errors, ensure `inputSchema` is valid. See [Authoring Tools](#authoring-tools) for details.
 - **Network access issues**: If the tool is having network access issues, you may need to configure `--plugin-isolation none`. This is generally discouraged for security reasons but may be necessary in some cases.
 
-### HTTP Transport
+### HTTP transport
 
 - **Connection issues**: Ensure the port is not already in use and the host is correct.
 - **CORS errors**: Configure `--allowed-origins` if accessing from a web client.
 - **DNS rebinding protection**: If behind a proxy, ensure correct `Host` header and configure `--allowed-hosts`.
 
-### General Issues
+### General issues
 
 - **Server won't start**: Check Node.js version (requires Node.js >= 20; >= 22 for tool plugins).
 - **Missing tools/resources**: Verify the server started successfully and check logs with `--log-stderr`.
 - **Type errors**: Ensure TypeScript types are installed: `npm install --save-dev @types/node`
 
+## Project maintenance
+
+For information on how we manage project dependencies, including our biannual Node.js engine bump schedule, please refer to the [Maintenance section in CONTRIBUTING.md](../CONTRIBUTING.md#maintenance-nodejs-engine-bumps).
+
+## In-progress and future work
+
+For more information on our development roadmap, including "in-progress" and "future" work, please refer to the [Architecture & Roadmap](./architecture.md#roadmap) documentation.

docs/usage.md

@@ -62,15 +62,31 @@ Fetch full documentation and component JSON schemas for specific PatternFly URLs
 
 ## Built-in resources
 
-> MCP resources represent indexed collections of documentation.
+> MCP resources represent indexed collections of documentation and machine-readable metadata.
 
-The server exposes this resource-centric architecture via the `patternfly://` URI scheme:
+The server exposes a resource-centric architecture via the `patternfly://` URI scheme. MCP clients can use these resources directly. [Review the roadmap for future resource updates](./architecture.md#roadmap).
 
-- **`patternfly://context`**: General PatternFly MCP server context and high-level rules.
-- **`patternfly://docs/index`**: Index of all available documentation pages.
-- **`patternfly://docs/{name}`**: Documentation for a specific component (e.g., `patternfly://docs/Button`).
-- **`patternfly://schemas/index`**: Index of all available component schemas.
-- **`patternfly://schemas/{name}`**: JSON Schema for a specific component (e.g., `patternfly://schemas/Button`).
+### Discovery resources
+
+Use these indexes to discover what is available in the library:
+
+- **`patternfly://docs/index{?version,category,section}`**: A comprehensive index of all available PatternFly documentation pages.
+- **`patternfly://components/index{?version,category}`**: A list of all available PatternFly component names.
+- **`patternfly://components/meta{?version}`**: Metadata discovery for components, helpful for understanding available filter parameters.
+- **`patternfly://schemas/index{?version,category}`**: An index of all available component JSON schemas.
+
+### Component and documentation resources
+
+Access specific component documentation or technical specifications using the following URI templates (RFC 6570):
+
+- **`patternfly://docs/{name}{?version,category,section}`**: Full human-readable documentation for a specific component (e.g., `patternfly://docs/button`) or guideline.
+- **`patternfly://schemas/{name}{?version,category}`**: Machine-readable JSON Schema for a specific component, detailing props, types, and validation rules (e.g., `patternfly://schemas/button`).
+
+### Context and guidelines
+
+- **`patternfly://context`**: General PatternFly MCP server context, including high-level development rules and accessibility guidelines.
+
+> **Tip for LLMs**: When a user asks about a component you aren't familiar with, first check `patternfly://docs/index` to find the correct name, then read the documentation via `patternfly://docs/{name}`. Use `patternfly://components/index` for a cleaner list of component-only names.
 
 ## MCP client configuration