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,23 @@ 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.
+
+### 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,26 @@ 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 PatternFly MCP server provides a hybrid documentation system that merges baseline guidelines with dynamic content. It is centered around a **Resource Metadata** discovery layer that powers the following core tools:
 
-#### 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 automated indexes and URI templates.
 
-A built-in tool for searching PatternFly documentation and resources integrated into the server.
+#### Hybrid Documentation Model
 
-#### Use PatternFly documentation
+The library maintains a balance between being stable and current:
+- **Baseline Data**: Core guidelines and accessibility standards integrated directly into the server.
+- **Dynamic Content**: Component documentation and schemas synced from the PatternFly implementation, ensuring the LLM always has access to the latest props and patterns.
 
-A built-in tool for reading and using PatternFly documentation and resources integrated into the server.
+#### Discovery Layer (Resource Metadata)
 
-#### Find and discover 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`) and schemas (`patternfly://schemas/index`).
+- Supports completion logic for MCP clients, allowing users to browse available resources effortlessly.
+- Provides parameterized URI templates (RFC 6570) like `patternfly://docs/{name}` for direct, predictable access.
 
-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)
+> 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).
 
 ### Tools, resources, and prompts as customizable plugins
 
@@ -48,59 +45,72 @@ 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
+- **PatternFly API Integration**: A JSON API for documentation, components, and patterns that ensures the server is always in sync with the latest releases.
+- **Child Process Lifecycle Management**: Background processes for API synchronization and tool isolation.
 
-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.
+#### Future goals
+- **Resource-Tool Integration**: Directly integrate MCP resources into tool responses to reduce token counts and allow tools to accept URI links as inputs.
+- **Agentless MCP Client**: An MCP client for use without an LLM, allowing PatternFly tooling to integrate into CLI tools and CI/CD pipelines.
+- **Environment & Analysis Tooling**: A third built-in tool focused on environment snapshots, code analysis, and whitelisted resource access for local project analysis.
+- **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
+    subgraph H1["Agentless client layer"]
+      H1A(["CLI & Automation integration"])
+    end
+    A1 <--> H1
   end
   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. These resources can be used directly by MCP clients or referenced by tools to provide context.
 
-- **`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