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

@@ -142,6 +142,25 @@ 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

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,6 +7,8 @@ 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
 
@@ -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';
@@ -378,3 +385,10 @@ See [examples/toolPluginHelloWorld.js](examples/toolPluginHelloWorld.js) for a b
 - **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