docs: update usage, architecture, maintenance (#143)

* 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
@@ -116,7 +116,7 @@ Basic code style guidelines are generally enforced by ESLint, but there are addi
 - Tests should focus on functionality.
 - Tests should not be written for external packages. That is the responsibility of the external package, or it shouldn't be used.
 
-#### Typescript
+#### TypeScript
 - Typings within the project may be generally loose for initial development but should be refined over time.
 - Typings exposed to consumers should always attempt to maintain consistency.
 - Typings for tests are less of a focus than functionality checks.
@@ -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
 
@@ -157,12 +176,12 @@ For detailed information on agent interaction, see [guidelines/README.md](./guid
 As developers, we often have our own preferred workflows, and that includes working with AI agents. To that point, we've added agent guidance
 to allow customization for your work environment through a tool-agnostic git-ignored directory `./.agent` in the root of the project.
 
-#### Noting AI Agent contributions
+#### Noting AI agent contributions
 
 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.
 
@@ -94,6 +94,10 @@ main();
 
 For comprehensive usage, development, and project state [read the docs](./docs/README.md).
 
+- **Architecture**: Learn about our [hybrid documentation model and data sources](./docs/architecture.md#data-sources-and-integrations).
+- **Usage**: Detailed guide on [built-in tools and resources](./docs/usage.md).
+- **Development**: Reference for [CLI options and tool plugins](./docs/development.md).
+
 ## Contributing
 
 Contributing? Guidelines can be found here [CONTRIBUTING.md](./CONTRIBUTING.md).

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
-- **[System Architecture](./architecture.md)**: Design concept and architecture.
+### 🏗️ Architecture & design
+- **[System Architecture](./architecture.md)**: Architecture and roadmap.
 - **[Roadmap](./architecture.md#roadmap)**: Future plans for the project.

docs/architecture.md

@@ -6,29 +6,41 @@ 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 is centered on a **Resource Metadata** discovery layer that enables 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.
+> [A more in-depth version of our **hybrid documentation** concept is currently in progress](#hybrid-documentation-in-progress).
 
-#### Use PatternFly documentation
+#### Discovery layer (resource metadata)
 
-A built-in tool for reading and using PatternFly documentation and resources integrated into the server.
+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`).
 
-#### Find and discover PatternFly documentation
+> 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).
 
-An evolving "future" tool (still undergoing refinement) for finding PatternFly documentation and resources not directly integrated into the server.
+#### Hybrid documentation (in-progress)
 
-> 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 more updates based on our hybrid documentation concept in upcoming releases. The base 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.
+
+### Data sources and integrations
+
+The PatternFly MCP server aggregates content from multiple official sources to provide a comprehensive development resource.
+
+#### PatternFly ai-helpers
+The server integrates the [patternfly/ai-helpers](https://github.com/patternfly/ai-helpers) repository to provide specialized, LLM-optimized guidance. This integration powers several key resource categories:
+- **AI Guidance**: Specialized patterns for React Charts, Chatbot, and general React development.
+- **Styling Standards**: CSS and styling requirements tailored for AI code generation.
+- **Prompt Engineering**: Includes `ai-prompt-guidance.md` to help users write more effective prompts for PatternFly.
+
+These helpers are a core part of our [Hybrid documentation](#hybrid-documentation-in-progress), acting as the bridge between stable design patterns and dynamic implementation details.
 
 ### Tools, resources, and prompts as customizable plugins
 
@@ -48,60 +60,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**: 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
 ```